6.6 API for Setup

• file — if not #f, installs file as a ".plt" archive.

• collections — if not #f, constrains setup to the named collections, along with planet-specs, if any

• planet-spec — if not #f, constrains setup to the named PLaneT packages, along with collections, if any

• make-user? — if #f, disables any user-specific setup actions

• avoid-main? — if true, avoids setup actions that affect the main installation, as opposed to user directories

• make-docs? — if #f, disables any documentation-specific setup actions

• make-doc-index? — if true, builds documentation index collections in addition to collections, assuming that documentation is built

• force-user-docs? — if true, then when building documentation, creates a user-specific documentation entry point even if it has the same content as the installation

• clean? — if true, enables cleaning mode instead of setup mode

• tidy? — if true, enables global tidying of documentation and metadata indexes even when collections or planet-specs is non-#f

• jobs — if not #f, determines the maximum number of parallel tasks used for setup

• fail-fast? — if true, breaks the current thread as soon as an error is discovered

• get-target-dir — if not #f, treated as a value for current-target-directory-getter

The result is #t if raco setup completes without error, #f otherwise.

Instead of using PLT_COMPILED_FILE_CHECK, setup is sensitive to the use-compiled-file-check parameter.

Changed in version 6.1 of package base: Added the fail-fast? argument.
Changed in version 6.1.1: Added the force-user-docs? argument.

6.6.1 raco setup Unit

The setup/setup-unit library provides raco setup in unit form. The associated setup/option-sig and setup/option-unit libraries provides the interface for setting options for the run of raco setup.

For example, to unpack a single ".plt" archive "x.plt", set the archives parameter to (list "x.plt") and leave specific-collections as null.

Link the options and setup units so that your option-setting code is initialized between them, e.g.:

(compound-unit

...

(link ...

[((OPTIONS : setup-option^)) setup:option@]

[() my-init-options@ OPTIONS]

[() setup@ OPTIONS ...])

...)

• setup-option^

• compiler^

• compiler:option^

• launcher^

• dynext:file^

and exports nothing. Invoking setup@ starts the setup process.

6.6.2 Options Unit

6.6.3 Options Signature

parameter (setup-program-name) → string?

(setup-program-name name) → void?

name : string?

The prefix used when printing status messages. The default is "raco setup".

parameter (verbose) → boolean?

(verbose on?) → void?

on? : any/c

If on, prints messages from make to stderr. The default is #f.

parameter (make-verbose) → boolean?

(make-verbose on?) → void?

on? : any/c

If on, verbose make. The default is #f.

parameter (compiler-verbose) → boolean?

(compiler-verbose on?) → void?

on? : any/c

If on, verbose compiler. The default is #f.

parameter (clean) → boolean?

(clean on?) → void?

on? : any/c

If on, delete ".zo" and ".so"/".dll"/".dylib" files in the specified collections. The default is #f.

parameter (compile-mode) → (or/c path? #f)

(compile-mode path) → void?

path : (or/c path? #f)

If a path is given, use a ".zo" compiler other than plain compile, and build to (build-path "compiled" (compile-mode)). The default is #f.

parameter (make-zo) → boolean?

(make-zo on?) → void?

on? : any/c

If on, compile ".zo". The default is #t.

parameter (make-info-domain) → boolean?

(make-info-domain on?) → void?

on? : any/c

If on, update "info-domain/compiled/cache.rkt" for each collection path. The default is #t.

parameter (make-launchers) → boolean?

(make-launchers on?) → void?

on? : any/c

If on, make collection "info.rkt"-specified launchers and man pages. The default is #t.

parameter (make-foreign-lib) → boolean?

(make-foreign-lib on?) → void?

on? : any/c

If on, install collection "info.rkt"-specified libraries. The default is #t.

parameter (make-docs) → boolean?

(make-docs on?) → void?

on? : any/c

If on, build documentation. The default is #t.

parameter (make-user) → boolean?

(make-user on?) → void?

on? : any/c

If on, build the user-specific collection tree. The default is #t.

parameter (make-planet) → boolean?

(make-planet on?) → void?

on? : any/c

If on, build the planet cache. The default is #t.

parameter (avoid-main-installation) → boolean?

(avoid-main-installation on?) → void?

on? : any/c

If on, avoid building bytecode in the main installation tree when building other bytecode (e.g., in a user-specific collection). The default is #f.

parameter (make-tidy) → boolean?

(make-tidy on?) → void?

on? : any/c

If on, remove metadata cache information and documentation for non-existent collections (to clean up after removal) even when specific-collections or specific-planet-dirs is non-'() or make-only is true. The default is #f.

parameter (call-install) → boolean?

(call-install on?) → void?

on? : any/c

If on, call collection "info.rkt"-specified setup code. The default is #t.

parameter (call-post-install) → boolean?

(call-post-install on?) → void?

on? : any/c

If on, call collection "info.rkt"-specified post-install code. The default is #t.

parameter (pause-on-errors) → boolean?

(pause-on-errors on?) → void?

on? : any/c

If on, in the event of an error, prints a summary error and waits for stdin input before terminating. The default is #f.

parameter (parallel-workers) → exact-nonnegative-integer?

(parallel-workers num) → void?

num : exact-nonnegative-integer?

Determines the number of places to use for compiling bytecode and for building the documentation. The default is (min (processor-count) 8).

parameter (fail-fast) → boolean?

(fail-fast on?) → void?

on? : any/c

If on, breaks the original thread as soon as an error is discovered. The default is #f.

Added in version 1.2 of package compiler-lib.

parameter (force-unpacks) → boolean?

(force-unpacks on?) → void?

on? : any/c

If on, ignore version and already-installed errors when unpacking a ".plt" archive. The default is #f.

parameter (specific-collections) → (listof (listof path-string?))

(specific-collections colls) → void?

colls : (listof (listof path-string?))

A list of collections to set up; the empty list means set-up all collections if the archives list and specific-planet-dirs is also '(). The default is '().

parameter (specific-planet-dirs)

→   (listof (list/c string?                 string?                 exact-nonnegative-integer?                 exact-nonnegative-integer?))

(specific-planet-dirs dir) → void?

dir   :   (listof (list/c string?                 string?                 exact-nonnegative-integer?                 exact-nonnegative-integer?))

A list of planet package version specs to set up; the empty list means to set-up all planet collections if the archives list and specific-collections is also '(). The default is '().

parameter (make-only) → boolean?

(make-only on?) → void?

on? : any/c

If true, set up no collections if specific-collections and specific-planet-dirs are both '().

parameter (archives) → (listof path-string?)

(archives arch) → void?

arch : (listof path-string?)

A list of ".plt" archives to unpack; any collections specified by the archives are set-up in addition to the collections listed in specific-collections. The default is null.

parameter (archive-implies-reindex) → boolean?

(archive-implies-reindex on?) → void?

on? : any/c

If on, when archives has a non-empty list of packages, if any documentation is built, then suitable documentation start pages, search pages, and master index pages are rebuilt. The default is #t.

parameter (current-target-directory-getter) → (-> path-string?)

(current-target-directory-getter thunk) → void?

thunk : (-> path-string?)

A thunk that returns the target directory for unpacking a relative ".plt" archive; when unpacking an archive, either this or the procedure in current-target-plt-directory-getter will be called. The default is current-directory.

parameter (current-target-plt-directory-getter)

→   (path-string?  path-string?  (listof path-string?) . -> . path-string?)

(current-target-plt-directory-getter proc) → void?

proc   :   (path-string?  path-string?  (listof path-string?) . -> . path-string?)

A procedure that takes a preferred path, a path to the parent of the main "collects" directory, and a list of path choices; it returns a path for a "plt-relative" install; when unpacking an archive, either this or the procedure in current-target-directory-getter will be called, and in the former case, this procedure may be called multiple times. The default is (lambda (preferred main-parent-dir choices) preferred).