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:

• Constraining to specified collections or PLaneT packages:

  • --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 or through the -l, --pkgs, or -P flag.

  • -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).

  • --pkgs ‹pkg› ... — constrain setup actions to collections that are within (or partially within) the named ‹pkg›s.

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

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

  • --tidy — remove metadata cache information and documentation for non-existent collections or documentation to clean up after removal, even when setup actions are otherwise confined to specified collections. Although tidying is not confined to specified collections, it can be constrained with --avoid-main or --no-user.

• Constraining to specific tasks:

  • --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. Unless --no-info-domain or -d is also specified, the "info.rkt" cache is cleared. Unless --no-docs or -D is also specified, the documentation-index database is reset.

  • --fast-clean — like --clean, but without forcing a bootstrap of raco setup from source (which means that --fast-clean cannot clean corruption that affects raco setup itself).

  • --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 (unless the PLT_COMPILED_FILE_CHECK environment variable is set to exists, in which case timestamps are ignored).

  • --recompile-only — disallow recompilation of modules from source, imposing the constraint that each ".zo" file is up-to-date, needs only a timestamp adjustment, or can be recompiled from an existing ".zo" in machine-independent format (when compiling to a machine-dependent format).

  • --sync-docs-only — synchronize or move documentation into place to “build” it, but do not run or render documentation sources.

  • --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 or -F — refrain from installing foreign libraries (as specified in "info.rkt"; see Controlling raco setup with "info.rkt" Files).

  • --only-foreign-libs — disable actions other than installing foreign libraries; equivalent to -nxiIdD, except that --only-foreign-libs doesn’t reject (redundant) specification of those individual flags.

  • --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-pkg-deps or -K — refrain from checking whether dependencies among libraries are properly reflected by package-level dependency declarations, whether modules are declared by multiple packages, and whether package version dependencies are satisfied. See Package Dependency Checking for more information.

  • --check-pkg-deps — checks package dependencies (unless explicitly disabled) even when specific collections are provided to raco setup, and even for packages that have no dependency declarations. See Package Dependency Checking for more information.

  • --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). See Package Dependency Checking for more information.

  • --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. See Package Dependency Checking for more information.

• Constraining user versus installation setup:

  • --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 flag is implied by --no-user.

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

  • --force-user-docs — when building documentation, create a user-specific documentation entry point even if it has the same content as the main installation.

• Selecting parallelism and other build modes:

  • --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.

  • --places — use Racket places for parallel jobs; this mode is the default if Racket places run in parallel.

  • --processes — use separate processes for parallel jobs; this mode is the default if Racket places cannot run in parallel.

  • --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.

  • --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.

  • --fail-fast — attempt to break as soon as any error is discovered.

  • --error-out ‹file› — handle survivable errors by writing ‹file› and exiting as successful, which facilitates chaining multiple raco setup invocations in combination with --error-in. If there are no errors and ‹file› already exists, it is deleted.

  • --error-in ‹file› — treat the existence of ‹file› as a “errors were reported by a previous process” error. Typically, ‹file› is created by previous raco setup run using --error-out. A file for --error-in is detected before creating a file via --error-out, so the same file can be used to chain a sequence of raco setup steps.

  • --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).

• Unpacking ".plt" archives:

  • -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.

• Bootstrapping:

  • --boot ‹module-file› ‹build-dir› — For use by directly running setup instead of through raco setup, loads ‹module-file› in the same way that raco setup normally loads itself, auto-detecting the need to start from sources and rebuild the compiled files—even for the compilation manager itself. The ‹build-dir› path is installed as the only path in current-compiled-file-roots, so all compiled files go there.

  • --chain ‹module-file› ‹build-dir› — Like --boot, but adds ‹build-dir› to the start of current-compiled-file-roots instead of replacing the current value, which means that libraries already built in the normal location (including the compilation manager itself) will be used instead of rebuilt. This mode makes sense for cross-compilation.

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

Running raco setup is sensitive to the PLT_COMPILED_FILE_CHECK environment variable in the same way as raco make. Specifically, if PLT_COMPILED_FILE_CHECK is set to exists, then raco make does not attempt to update a compiled file’s timestamp if the file is not recompiled.

Some additional environment variables are useful for performance debugging:

• PLT_SETUP_DMS_ARGS triggers a call to dump-memory-stats after each collection is compiled, where the environment variable’s value is parsed with read to obtain a list of arguments to dump-memory-stats.

• PLT_SETUP_LIMIT_CACHE (set to anything) avoids caching compiled-file information across different collections, which is useful to reduce noise when looking for memory leaks.

• PLT_SETUP_NO_FORCE_GC (set to anything) suppresses a call to collect-garbage that is issued by default for non-parallel builds after each collection is compiled and after each document is run or rendered.

• PLT_SETUP_SHOW_TIMESTAMPS (set to anything) appends the current process time after  @  for each status message printed by raco setup.

Changed in version 6.1: Added the --pkgs, --check-pkg-deps, and --fail-fast flags.
Changed in version 6.1.1: Added the --force-user-docs flag.
Changed in version 6.1.1.6: Added the --only-foreign-libs flag.
Changed in version 6.6.0.3: Added support for PLT_COMPILED_FILE_CHECK.
Changed in version 7.0.0.19: Added --places and --processes.
Changed in version 7.2.0.7: Added --error-in and --error-out.
Changed in version 7.2.0.8: Added --recompile-only.
Changed in version 7.9.0.3: Added PLT_SETUP_NO_FORCE_GC, PLT_SETUP_SHOW_TIMESTAMPS, and --sync-docs-only.