6.17 Layered Installations

► |  | 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

top contents ← prev up next →

#### 6.17`` Layered Installations🔗ℹ

A typical Racket configuration includes two layers: an installation layer and a user layer. The intent is that the installation layer is read-only to all users of a system, while the user layer allows each individual user to install additional packages that extend the installation layer. The installation layer is intended not only to be read-only, but to not change after users start installing in their own layers.

In an environment where Racket itself is under development, the installation layer will change. In that setting, if the user layer is used at all, care must be taken to not create conflicts for the user layer when modifying the installation layer—or else the user layer must be repaired on occasion.

By default, raco setup updates both layers whenever it is run; if a user does not have write permission the installation, raco setup with no arguments is all but certain to report permission errors. The actions of raco setup can be constrained to the user layer by supplying the --avoid-main argument, or raco setup can be constrained to the installation layer by using the --no-user argument. When raco pkg performs setup actions, it effectively supplies one of the other of those based on the package’s scope (and raco pkg refuses to operate on both scopes/layers at once).

The user layer is always both user- and version-specific. More precisely, it is specific to the user and an installation’s name, where the installation’s name is typically its version number. However, the name of an installation can be changed through the 'installation setting in "config.rktd" (see Installation Configuration and Search Paths). Setting an installation name changes the directory where packages and executables reside within (find-system-path 'addon-dir). The result of (find-system-path 'addon-dir) itself can be changed through 'addon-dir in "config.rktd".

The installation and user configuration layers can be generalized to multiple layers by setting search paths in "config.rktd". These search paths essentially treat the layer closest to user as the installation layer that might be adjusted by raco setup and raco pkg, but search paths can chain to an existing (unchanging) implementation in much the same way that user chains to installation. To build a new layer, create new "config.rktd" that is like the underlying layer’s "config.rktd", but

- each of 'lib-dir, 'share-dir, 'links-file, 'pkgs-dir, 'bin-dir, 'gui-bin-dir, 'apps-dir, 'doc-dir, and 'man-dir is a new directory or file; and

- the corresponding search lists 'lib-search-dirs, 'share-search-dirs, 'links-search-files, 'pkgs-search-dirs, 'bin-search-dirs, 'gui-bin-search-dirs, (no 'apps-dir search needed), 'doc-search-dirs, and 'man-search-dirs each add the old directory or file to the search list just after #f; note that the default for each search list is (list #f).

There is no argument to raco setup that is analogous to --avoid-main to avoid modifying nested layer; instead, nested layers are expected to be fully set up so that raco setup need not change them. When raco setup would otherwise install an executable into the directory configured as 'bin-dir, it consults the 'bin-search-dirs list to check whether the executable is already installed in one of those directories, and if so, it will refrain from creating a copy in the new layer. The same search-list check also applies to native libraries, shared files, and man pages, but with the additional check that the file to install matches the one that is already installed.

The default path to "config.rktd" is hardwired within a racket executable. In some cases, it can make sense for the innermost layer’s configuration to point to another layer, perhaps because the filesystem provides an indirection. For example, on Unix, a Racket installation in "/usr" might reasonably configure the installation layer’s directories to be in "/usr/local" with "/usr" directories included in the search lists.

To use racket with a new "config.rktd", you can supply the --config or --G flag to racket or set the PLTCONFIGDIR environment variable to point to the directory containing "config.rktd". Alternatively, you can create a tethered layer that creates replacement executables like racket that are hardwired to the layer’s configuration directory.

top contents ← prev up next →