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.

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

  • --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 or -F — 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-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. Dependency checking uses ".zo" files, associated ".dep" files, and the documentation index. Unless --check-pkg-deps is specified, dependency checking is disabled if any collection is specified for raco setup, and missing dependencies are not treated as an error for a package that has no dependency declarations.

  • --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. Currently, dependency checking related to documentation cross-referencing is constrained to documents among specified collections.

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

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

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

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

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

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

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

Changed in version 1.2: Added the --pkgs, --check-pkg-deps, and --fail-fast flags.