6.8 API for Finding Installation Directories

package: base

The setup/dirs library provides several procedures for locating installation directories. Many of these paths can be configured through the configuration directory (see Installation Configuration and Search Paths).

In cross-platform build mode (see API for Cross-Platform Configuration), the functions provided by setup/dirs generally report target-system paths, instead of current-system paths. The exceptions are get-lib-search-dirs and find-dll-dir, which report current-system paths while get-cross-lib-search-dirs and find-cross-dll-dir report target-system paths.

procedure
(find-collects-dir) → (or/c path? #f)

Returns a path to the installation’s main "collects" directory, or #f if none can be found. A #f result is likely only in a stand-alone executable that is distributed without libraries.

procedure
(find-user-collects-dir) → path?

Returns a path to the user-specific "collects" directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-collects-search-dirs) → (listof path?)

Returns the same result as (current-library-collection-paths), which means that this result is not sensitive to the value of the use-user-specific-search-paths parameter.

procedure
(get-main-collects-search-dirs) → (listof path?)

Returns a list of paths to installation "collects" directories, normally including the result of find-collects-dir. These directories are normally included in the result of (current-library-collection-paths), but a PLTCOLLECTS setting or change to the parameter may cause them to be omitted. Any other path in (current-library-collection-paths) is treated as user-specific. The directories indicated by the returned paths may or may not exist.

The main-collections search path can be configured via 'collects-search-dirs in "config.rktd" (see Installation Configuration and Search Paths).

procedure
(find-config-dir) → (or/c path? #f)

Returns a path to the installation’s "etc" directory, which contains configuration and package information—including configuration of some of the other directories (see Installation Configuration and Search Paths). A #f result indicates that no configuration directory is available.

procedure
(find-links-file) → (or/c path? #f)

Returns a path to the installation’s collection links file. The file indicated by the returned path may or may not exist. A #f result indicates that no links file is available.

See also 'links-file in Installation Configuration and Search Paths.

procedure
(find-user-links-file [vers]) → path?
vers : string? = (get-installation-name)

Returns a path to the user’s collection links file. The file indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and vers.

procedure
(get-links-search-files) → (listof path?)

Returns a list of paths to installation collection links files to search in order. (Normally, the result includes the result of (find-links-file), which is where new installation-wide links are installed by raco link or links.) The result of find-user-links-file is not added to the returned list. The files indicated by the returned paths may or may not exist.

See also 'links-search-files in Installation Configuration and Search Paths.

procedure
(find-pkgs-dir) → (or/c path? #f)

Returns a path to the directory containing packages with installation scope; the directory indicated by the returned path may or may not exist. A #f result indicates that no package-installation directory is available.

See also 'pkgs-dir in Installation Configuration and Search Paths.

procedure
(find-user-pkgs-dir [vers]) → path?
vers : string? = (get-installation-name)

Returns a path to the directory containing packages with user-specific scope for installation name vers; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and vers.

procedure
(get-pkgs-search-dirs) → (listof path?)

Returns a list of paths to the directories containing packages in installation scope. (Normally, the result includes the result of (find-pkgs-dir), which is where new packages are installed by raco pkg install.) The result of find-user-pkgs-dir is not added to the returned list. The directories indicated by the returned paths may or may not exist.

See also 'pkgs-search-dirs in Installation Configuration and Search Paths.

procedure
(find-doc-dir) → (or/c path? #f)

Returns a path to the installation’s "doc" directory. The result is #f if no such directory is available.

See also 'doc-dir in Installation Configuration and Search Paths.

procedure
(find-user-doc-dir) → path?

Returns a path to a user-specific "doc" directory. The directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-doc-search-dirs) → (listof path?)

Returns a list of paths to search for documentation, not including documentation stored in individual collections. Unless it is configured otherwise, the result includes any non-#f result of (find-doc-dir) and (find-user-doc-dir)—but the latter is included only if the value of the use-user-specific-search-paths parameter is #t.

See also 'doc-search-dirs in Installation Configuration and Search Paths.

procedure
(get-doc-extra-search-dirs) → (listof path?)

Like get-doc-search-dirs, but refrains from adding (find-doc-dir) and (find-user-doc-dir) to the underlying 'doc-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(find-lib-dir) → (or/c path? #f)

Returns a path to the installation’s "lib" directory, which contains libraries and other build information. The result is #f if no such directory is available.

See also 'lib-dir in Installation Configuration and Search Paths.

procedure
(find-user-lib-dir) → path?

Returns a path to a user-specific "lib" directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-lib-search-dirs) → (listof path?)

Returns a list of paths to search for foreign libraries.

Unless it is configured otherwise, and except in cross-platform build mode, the result includes any non-#f result of (find-lib-dir) and (find-user-lib-dir)—but the latter is included only if the value of the use-user-specific-search-paths parameter is #t.

In cross-platform build mode (see API for Cross-Platform Configuration), get-lib-search-dirs reports a result suitable for the current system, instead of the target system. See also get-cross-lib-search-dirs.

See also 'lib-search-dirs in Installation Configuration and Search Paths.

Changed in version 6.1.1.4 of package base: Dropped (find-dll-dir) from the set of paths to explicitly include in the default.
Changed in version 6.9.0.1: Changed behavior in cross-platform build mode.

procedure
(get-cross-lib-search-dirs) → (listof path?)

Like get-lib-search-dirs, but in cross-platform build mode, reports directories for the target system (including any non-#f result of (find-lib-dir), etc.) instead of the current system.

Added in version 6.9.0.1 of package base.

procedure
(get-cross-lib-extra-search-dirs) → (listof path?)

Like get-cross-lib-search-dirs, but refrains from adding (find-lib-dir) and (find-user-lib-dir) to the underlying 'lib-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(find-dll-dir) → (or/c path? #f)

Returns a path to the directory that contains DLLs for use with the current executable (e.g., "libracket.dll" on Windows). The result is #f if no such directory is available, or if no specific directory is available (i.e., other than the platform’s normal search path).

In cross-platform build mode (see API for Cross-Platform Configuration), find-dll-dir reports a result suitable for the current system, instead of the target system. See also find-cross-dll-dir.

Changed in version 6.9.0.1 of package base: Changed behavior in cross-platform build mode.

procedure
(find-cross-dll-dir) → (or/c path? #f)

Like find-dll-dir, but in cross-platform build mode, reports a directory for the target system instead of the current system.

Added in version 6.9.0.1 of package base.

procedure
(find-share-dir) → (or/c path? #f)

Returns a path to the installation’s "share" directory, which contains installed packages and other platform-independent files. The result is #f if no such directory is available.

See also 'share-dir in Installation Configuration and Search Paths.

procedure
(find-user-share-dir) → path?

Returns a path to a user-specific "share" directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-share-search-dirs) → (listof path?)

Returns a list of paths to search for files that are normally in a "share" directory.

Unless it is configured otherwise, the result includes any non-#f result of (find-share-dir) and (find-user-share-dir)—but the latter is included only if the value of the use-user-specific-search-paths parameter is #t.

See also 'share-search-dirs in Installation Configuration and Search Paths.

Added in version 8.1.0.6 of package base.

procedure
(get-share-extra-search-dirs) → (listof path?)

Like get-share-search-dirs, but refrains from adding (find-share-dir) and (find-user-share-dir) to the underlying 'share-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(find-include-dir) → (or/c path? #f)

Returns a path to the installation’s "include" directory, which contains ".h" files for building Racket extensions and embedding programs. The result is #f if no such directory is available.

See also 'include-dir in Installation Configuration and Search Paths.

procedure
(find-user-include-dir) → path?

Returns a path to a user-specific "include" directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-include-search-dirs) → (listof path?)

Returns a list of paths to search for ".h" files. Unless it is configured otherwise, the result includes any non-#f result of (find-include-dir) and (find-user-include-dir)—but the latter is included only if the value of the use-user-specific-search-paths parameter is #t.

See also 'include-search-dirs in Installation Configuration and Search Paths.

procedure
(find-console-bin-dir) → (or/c path? #f)

Returns a path to the installation’s executable directory, where the stand-alone Racket executable resides. The result is #f if no such directory is available.

See also 'bin-dir in Installation Configuration and Search Paths.

procedure
(find-gui-bin-dir) → (or/c path? #f)

Returns a path to the installation’s executable directory, where the stand-alone GRacket executable resides. The result is #f if no such directory is available.

See also 'gui-bin-dir in Installation Configuration and Search Paths.

procedure
(find-user-console-bin-dir) → path?

Returns a path to the user’s executable directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(find-user-gui-bin-dir) → path?

Returns a path to the user’s executable directory for graphical programs; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-console-bin-search-dirs) → (listof path?)

Analogous to get-share-search-dirs, but for paths to search for executables such as racket.

See also 'bin-search-dirs in Installation Configuration and Search Paths.

Added in version 8.1.0.6 of package base.

procedure
(get-console-bin-extra-search-dirs) → (listof path?)

Analogous to get-share-extra-search-dirs for the underlying 'bin-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(get-gui-bin-search-dirs) → (listof path?)

Analogous to get-share-search-dirs, but for paths to search for executables such as gracket.

See also 'gui-bin-search-dirs in Installation Configuration and Search Paths.

Added in version 8.1.0.6 of package base.

procedure
(get-gui-bin-extra-search-dirs) → (listof path?)

Analogous to get-share-extra-search-dirs for the underlying 'gui-bin-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(find-apps-dir) → (or/c path? #f)

Returns a path to the installation’s directory ".desktop" files (for Unix). The result is #f if no such directory exists.

See also 'apps-dir in Installation Configuration and Search Paths.

procedure
(find-user-apps-dir) → path?

Returns a path to the user’s directory for ".desktop" files (for Unix); the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(find-man-dir) → (or/c path? #f)

Returns a path to the installation’s man-page directory. The result is #f if no such directory exists. See also 'man-dir in Installation Configuration and Search Paths.

procedure
(find-user-man-dir) → path?

Returns a path to the user’s man-page directory; the directory indicated by the returned path may or may not exist.

The user-specific path depends on at least (find-system-path 'addon-dir) and (get-installation-name).

procedure
(get-man-search-dirs) → (listof path?)

Analogous to get-share-search-dirs, but for paths to search for man pages.

See also 'man-search-dirs in Installation Configuration and Search Paths.

Added in version 8.1.0.6 of package base.

procedure
(get-man-extra-search-dirs) → (listof path?)

Analogous to get-share-extra-search-dirs for the underlying 'man-search-dirs configuration.

Added in version 8.1.0.6 of package base.

procedure
(get-doc-search-url) → string?

Returns a string that is used by the documentation system, augmented with a version and search-key query, for remote documentation links.

See also 'doc-search-url in Installation Configuration and Search Paths.

procedure
(get-doc-open-url) → (or/c string? #f)

Returns #f or a string for a root URL to be used as an alternative to opening a local file for documentation. A non-#f configuration means that DrRacket, for example, performs keyword searches for documentation via the specified URL instead of from locally installed documentation.

See also 'doc-open-url in Installation Configuration and Search Paths.

Added in version 6.0.1.6 of package base.

procedure
(get-installation-name config) → string?
config : (read-installation-configuration-table)

Returns the current installation’s name, which is often (version), but an installation name can be set through a combination of a 'installation-name value in config plus a user-specific directory state if (use-user-specific-search-paths) is #t.

A user-specific result depends on whether a directory "other-version" exists within (find-system-path 'addon-dir). If that directory exists, and it no directory with the installation’s configured name exists, then "other-version" is used as the installation name. So, by creating the "other-version" directory, a user can opt into sharing of packages and collections across installations/versions, while opting out for a specific installation/version by creating a directory with that installation’s name.

Changed in version 8.4.0.3 of package base: Added the config argument and support for a user-specific installation name.

procedure
(get-build-stamp) → (or/c #f string?)

Returns a string that identifies an installation build, which can be used to augment the Racket version number to more specifically identify the build. An empty string is normally produced for a release build. The result is #f if no build stamp is available.

procedure
(get-absolute-installation?) → boolean?

Returns #t if this installation uses absolute path names for executable and library references, #f otherwise.

procedure
(find-addon-tethered-console-bin-dir) → (or/c #f path?)
procedure
(find-addon-tethered-gui-bin-dir) → (or/c #f path?)
procedure
(find-addon-tethered-apps-dir) → (or/c #f path?)

Returns a path to a user-specific directory to hold an extra copy of each installed executable and ".desktop" file (for Unix), where the extra copy is created by raco setup and tethered to a particular result for (find-system-path 'addon-dir) and (find-config-dir).

Unlike other directories, which are configured via "config.rktd" in the (find-config-dir) directory (see Installation Configuration and Search Paths), these paths are configured via 'addon-tethered-console-bin-dir, 'addon-tethered-gui-bin-dir, and 'addon-tethered-apps-dir entries in "config.rktd" in (build-path (find-system-path 'addon-dir) "etc"). If no configuration is present, the result from the corresponding function, find-addon-tethered-console-bin-dir, find-addon-tethered-gui-bin-dir, or find-addon-tethered-apps-dir, is #f instead of a path.

See Tethered Installations for more information.

Added in version 6.5.0.2 of package base.
Changed in version 8.3.0.11: Added find-addon-tethered-apps-dir.

]

procedure
(find-config-tethered-console-bin-dir) → (or/c #f path?)
procedure
(find-config-tethered-gui-bin-dir) → (or/c #f path?)
procedure
(find-config-tethered-apps-dir) → (or/c #f path?)

Similar to find-addon-tethered-console-bin-dir, find-addon-tethered-gui-bin-dir, and find-addon-tethered-apps-dir, but configured via "config.rktd" in the (find-config-dir) directory (see Installation Configuration and Search Paths) and triggers executables that are tethered only to a particular value of (find-config-dir).

See Tethered Installations for more information.

Added in version 6.5.0.2 of package base.
Changed in version 8.3.0.11: Added find-addon-tethered-apps-dir.

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