6.6 API for Setup

► |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

▼ | 6 | raco setup: Installation Management

6.1 | Running raco setup
6.2 | Installing ".plt" Archives
6.3 | Controlling raco setup with "info.rkt" Files
6.4 | "info.rkt" File Format
6.5 | Package Dependency Checking
6.6 | API for Setup
6.7 | API for Installing ".plt" Archives
6.8 | API for Finding Installation Directories
6.9 | API for Reading "info.rkt" Files
6.10 | API for Relative Paths
6.11 | API for Collection Names
6.12 | API for Collection Searches
6.13 | API for Platform Specifications
6.14 | API for Cross-Platform Configuration
6.15 | API for Cross-References for Installed Manuals
6.16 | API for Materializing User-Specific Documentation
6.17 | Layered Installations
6.18 | Tethered Installations

► | 6.6 | API for Setup

6.6.1 | raco setup Unit
6.6.2 | Options Unit
6.6.3 | Options Signature
6.6.4 | Setup Start Module

On this page:

setup
6.6.1`` raco setup Unit
setup@
6.6.2`` Options Unit
setup: option@
6.6.3`` Options Signature
setup-option^
setup-program-name
setup-compiled-file-paths
verbose
make-verbose
compiler-verbose
clean
compile-mode
make-zo
make-info-domain
make-launchers
make-foreign-lib
make-docs
make-user
make-planet
avoid-main-installation
make-tidy
call-install
call-post-install
pause-on-errors
parallel-workers
fail-fast
force-unpacks
specific-collections
specific-planet-dirs
make-only
archives
archive-implies-reindex
current-target-directory-getter
current-target-plt-directory-getter
6.6.4`` Setup Start Module

top contents ← prev up next →

#### 6.6`` API for Setup🔗ℹ

(require setup/setup) | package: base

> > procedure
> > (setup | [ | #:file file |  |  |  |
> > |  | #:collections collections |  |  |  |
> > |  | #:pkgs pkgs |  |  |  |
> > |  | #:planet-specs planet-specs |  |  |  |
> > |  | #:make-user? make-user? |  |  |  |
> > |  | #:avoid-main? avoid-main? |  |  |  |
> > |  | #:make-docs? make-docs? |  |  |  |
> > |  | #:make-doc-index? make-doc-index? |  |  |  |
> > |  | #:force-user-docs? force-user-docs? |  |  |  |
> > |  | #:check-pkg-deps? check-pkg-deps? |  |  |  |
> > |  | #:fix-pkg-deps? fix-pkg-deps? |  |  |  |
> > |  | #:unused-pkg-deps? unused-pkg-deps? |  |  |  |
> > |  | #:clean? clean? |  |  |  |
> > |  | #:tidy? tidy? |  |  |  |
> > |  | #:recompile-only? recompile-only? |  |  |  |
> > |  | #:jobs jobs |  |  |  |
> > |  | #:fail-fast? fail-fast? |  |  |  |
> > |  | #:get-target-dir get-target-dir]) |  | → |  | boolean?
> file : (or/c #f path-string?) = #f
> collections : (or/c #f (listof (listof path-string?))) = #f
> pkgs : (or/c #f (listof string?)) = #f
> | planet-specs |  | : |  |
> (or/c #f
> (listof (list/c string?
> string?
> exact-nonnegative-integer?
> exact-nonnegative-integer?)))
> |  |  | = |  | #f
> make-user? : any/c = #t
> avoid-main? : any/c = #f
> make-docs? : any/c = #t
> make-doc-index? : any/c = #f
> force-user-docs? : any/c = #f
> check-pkg-deps? : any/c = #f
> fix-pkg-deps? : any/c = #f
> unused-pkg-deps? : any/c = #f
> clean? : any/c = #f
> tidy? : any/c = #f
> recompile-only? : any/c = #f
> jobs : exact-nonnegative-integer? = #f
> fail-fast? : any/c = #f
> get-target-dir : (or/c #f (-> path-string?)) = #f

Runs raco setup with various options:

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

- collections — if not #f, constrains setup to the named collections (along with pkgs and planet-specs, if any)

- pkgs — if not #f, constrains setup to the named packages (along with collections and planet-specs, if any)

- planet-spec — if not #f, constrains setup to the named PLaneT packages (along with collections and pkgs, 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

- check-pkg-deps? — if true, enables package-dependency checking even when collections, pkgs, or planet-specs is non-#f.

- fix-pkg-deps? — if true, implies check-pkg-deps? and attempts to automatically correct discovered package-dependency problems

- unused-pkg-deps? — if true, implies check-pkg-deps? and also reports dependencies that appear to be unused

- 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

- recompile-only? — if true, disallows compilation from source, allowing only timestamp adjustments and recompilation from machine-independent form

- 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.
Changed in version 7.2.0.7: Added the check-pkg-deps?, fix-pkg-deps? , and unused-pkg-deps? arguments.
Changed in version 7.2.0.8: Added the recompile-only? argument.

##### 6.6.1`` raco setup Unit🔗ℹ

(require setup/setup-unit) | package: compiler-lib

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

> value setup@ : unit?

Imports

- setup-option^

- compiler^

- compiler:option^

- launcher^

- dynext:file^

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

##### 6.6.2`` Options Unit🔗ℹ

(require setup/option-unit) | package: compiler-lib

> value setup:option@ : unit?

Imports nothing and exports setup-option^.

##### 6.6.3`` Options Signature🔗ℹ

(require setup/option-sig) | package: compiler-lib

> signature setup-option^ : signature

Provides parameters used to control raco setup in unit form.

> > 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 (setup-compiled-file-paths)
> > → (or/c #f (listof (and/c path? relative-path?)))
> > (setup-compiled-file-paths paths) → void?
> > paths : (or/c #f (listof (and/c path? relative-path?)))

> If not #f, supplies a value like the one for use-compiled-file-paths to control operations such as cleaning, where use-compiled-file-paths may have been set to null to avoid loading bytecode.

> Added in version 1.7 of package compiler-lib.

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

##### 6.6.4`` Setup Start Module🔗ℹ

(require setup) | package: base

The setup library implements raco setup, including the part that bootstraps raco setup if its own implementation needs to be compiled.

When running setup via racket, supply the -N raco to ensure that command-line arguments are parsed the same way as for raco setup, as opposed to a legacy command-line mode.

top contents ← prev up next →