6.1 Running raco setup

With no command-line arguments, raco setup finds all of the current collections—see Libraries and Collections—and compiles libraries in each collection. (Directories that are named ".git" or ".svn" are not treated as collections.)

To restrict raco setup to a set of collections, provide the collection names as arguments. For example, raco setup scribblings/raco would only compile and render the documentation for raco, which is implemented in a "scribblings/raco" collection.

An optional "info.rkt" within the collection can indicate specifically how the collection’s files are to be compiled and other actions to take in setting up a collection, such as creating executables or building documentation. See Controlling raco setup with "info.rkt" Files for more information.

The raco setup command accepts the following command-line flags:

• --jobs ‹n›, --workers ‹n›, or -j ‹n› — use up to ‹n› parallel processes. By default, raco setup uses (processor-count) jobs, which typically uses all of the machine’s processing cores.

• --only — restrict setup to specified collections and PLaneT packages, even if none are specified. This mode is the default if any collection is specified as a command-line argument, through the -l flag, or through the -P flag.

• -P ‹owner› ‹package-name› ‹maj› ‹min› — constrain setup actions to the specified PLaneT package, in addition to any other specified PLaneT packages or ‹collections›.

• --tidy — remove metadata cache information and documentation for non-existent collections (to clean up after removal) even when setup actions are otherwise confined to specified collections.

• --doc-index — builds collections that implement documentation indexes (when documentation building is enabled), in addition to specified collections.

• --clean or -c — delete existing ".zo" files, thus ensuring a clean build from the source files. The exact set of deleted files can be controlled by "info.rkt"; see clean for more information.

• --no-zo or -n — refrain from compiling source files to ".zo" files.

• --trust-zos — fix timestamps on ".zo" files on the assumption that they are already up-to-date.

• --no-launcher or -x — refrain from creating executables or installing man pages (as specified in "info.rkt"; see Controlling raco setup with "info.rkt" Files.

• --no-foreign-libs — refrain from installing foreign libraries (as specified in "info.rkt"; see Controlling raco setup with "info.rkt" Files).

• --no-install or -i — refrain from running pre-install actions (as specified in "info.rkt" files; see Controlling raco setup with "info.rkt" Files).

• --no-post-install or -I — refrain from running post-install actions (as specified in "info.rkt" files; see Controlling raco setup with "info.rkt" Files).

• --no-info-domain or -d — refrain from building a cache of metadata information from "info.rkt" files. This cache is needed by other tools. For example, raco itself uses the cache to locate plug-in tools.

• --no-docs or -D — refrain from building documentation.

• --doc-pdf ‹dir› — in addition to building HTML documentation, render documentation to PDF and place files in ‹dir›.

• --no-user or -U — refrain from any user-specific (as opposed to installation-specific) setup actions.

• --no-planet — refrain from any setup actions for PLaneT actions; this flags is implied by --no-user.

• --avoid-main — refrain from any setup actions that affect the installation, as opposed to user-specific actions.

• --no-pkg-deps or -K — refrain from checking whether dependencies among libraries are properly reflected by package-level dependency declarations. The check uses compiled bytecode and associated ".dep" files, and it checks only files are setup against only packages that include files that are setup.

• --fix-pkg-deps — attempt to correct dependency mismatches by adjusting package "info.rkt" files (which makes sense only for packages that are installed as links).

• --unused-pkg-deps — attempt to report dependencies that are declared but are unused. Beware that some package dependencies may be intentionally unused (e.g., declared to force installation of other packages as a convenience), and beware that package dependencies may be reported as unused only because compilation of relevant modules has been suppressed.

• --mode ‹mode› — use a ".zo" compiler other than the default compiler, and put the resulting ".zo" files in a subdirectory (of the usual place) named by ‹mode›. The compiler is obtained by using ‹mode› as a collection name, finding a "zo-compile.rkt" module in that collection, and extracting its zo-compile export. The zo-compile export should be a function like compile; see the "errortrace" collection for an example.

• --verbose or -v — more verbose output about raco setup actions.

• --make-verbose or -m — more verbose output about dependency checks.

• --compiler-verbose or -r — even more verbose output about dependency checks and compilation.

• --pause or -p — pause for user input if any errors are reported (so that a user has time to inspect output that might otherwise disappear when the raco setup process ends).

• -l ‹collection› ... — constrain setup actions to the specified ‹collection›s (i.e., the same as providing ‹collections›s without a flag, but with no possibility that a ‹collection› is interpreted as a flag.

• -A ‹archive› ... — Install each ‹archive›; see Installing ".plt" Archives.

• --force — for use with -A, treat version mismatches for archives as mere warnings.

• --all-users or -a — for use with -A, install archive into the installation instead of a user-specific location.

When building racket, flags can be provided to raco setup as run by make install by setting the PLT_SETUP_OPTIONS environment variable. For example, the following command line uses a single process to build collections during an install:

  env PLT_SETUP_OPTIONS="-j 1" make install