From bd0192d22d41b0904f905fb685d2d9a247e2ca75 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 26 Jul 2010 15:03:31 -0500 Subject: [PATCH] revised docs for -j flag to `raco setup' Glad to see the docs, but revised for the following reasons: * define a meta-variable like `n' before using it * typeset meta-variables specially, usually as a Racket variable * 'processor-count' needed a `for-label' import for the hyperlink * use @exec{} for `make install', because it's a command rather than plain English * although `PLT_SETUP_OPTIONS' was introduced for `-j', it makes sense in general; revising the prose and moving to the end of the bullet makes that more clear (but good job including the index entry) * used `env' so that the example command line works for more shells --- collects/scribblings/raco/setup.scrbl | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/collects/scribblings/raco/setup.scrbl b/collects/scribblings/raco/setup.scrbl index d02bab4776..9e4e5f2245 100644 --- a/collects/scribblings/raco/setup.scrbl +++ b/collects/scribblings/raco/setup.scrbl @@ -20,7 +20,8 @@ launcher/launcher compiler/sig launcher/launcher-sig - racket/gui/base)) + racket/gui/base + racket/future)) @(define-syntax-rule (local-module mod . body) (begin @@ -72,14 +73,11 @@ The @exec{raco setup} command performs two main services: controlled by @filepath{info.rkt}; see @elemref["clean"]{@racket[clean]} for more information. - The @DFlag{workers} (or @Flag{j}) flag to @exec{raco setup} causes it - to compile upto n jobs in parallel. The default is - @racket[(processor-count)], which uses all the machine's processing cores. - The number of workers to use during parallel build can also be set through - the @as-index{@envvar{PLT_SETUP_OPTIONS}} environment variable when running - make install. - - @commandline{PLT_SETUP_OPTIONS="-j 1" make install.} + The @DFlag{workers} (or @Flag{j}) flag to @exec{raco setup} takes + an argument @scheme[_n] to make compilation use up to @scheme[_n] + parallel processes. The default value of @scheme[_n] is + @racket[(processor-count)], which typically uses all the machine's + processing cores. The @Flag{l} flag takes one or more collection names and restricts @exec{raco setup}'s action to those collections. @@ -92,7 +90,15 @@ The @exec{raco setup} command performs two main services: @filepath{zo-compile.rkt} module in that collection, and extracting its @racket[zo-compile] export. The @racket[zo-compile] export should be a function like @racket[compile]; see the - @filepath{errortrace} collection for an example.} + @filepath{errortrace} collection for an example. + + When building @exec{racket}, flags can be provided to @exec{raco + setup} as run by @exec{make install} by setting the + @as-index{@envvar{PLT_SETUP_OPTIONS}} environment variable. For + example, the following command line uses a single process to build + collections during an install: + + @commandline{env PLT_SETUP_OPTIONS="-j 1" make install}} @item{@bold{Unpacking @filepath{.plt} files:} A @filepath{.plt} file is a platform-independent distribution archive