6.8 API for Finding Installation Directories

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

On this page:

find-collects-dir
find-user-collects-dir
get-collects-search-dirs
get-main-collects-search-dirs
find-config-dir
find-links-file
find-user-links-file
get-links-search-files
find-pkgs-dir
find-user-pkgs-dir
get-pkgs-search-dirs
find-doc-dir
find-user-doc-dir
get-doc-search-dirs
get-doc-extra-search-dirs
find-lib-dir
find-user-lib-dir
get-lib-search-dirs
get-cross-lib-search-dirs
get-cross-lib-extra-search-dirs
find-dll-dir
find-cross-dll-dir
find-share-dir
find-user-share-dir
get-share-search-dirs
get-share-extra-search-dirs
find-include-dir
find-user-include-dir
get-include-search-dirs
find-console-bin-dir
find-gui-bin-dir
find-user-console-bin-dir
find-user-gui-bin-dir
get-console-bin-search-dirs
get-console-bin-extra-search-dirs
get-gui-bin-search-dirs
get-gui-bin-extra-search-dirs
find-apps-dir
find-user-apps-dir
find-man-dir
find-user-man-dir
get-man-search-dirs
get-man-extra-search-dirs
get-info-domain-root
get-doc-search-url
get-doc-open-url
get-installation-name
get-build-stamp
get-main-language-family
get-base-documentation-packages
get-distribution-documentation-packages
get-absolute-installation?
find-addon-tethered-console-bin-dir
find-addon-tethered-gui-bin-dir
find-addon-tethered-apps-dir
find-config-tethered-console-bin-dir
find-config-tethered-gui-bin-dir
find-config-tethered-apps-dir

top contents ← prev up next →

#### 6.8`` API for Finding Installation Directories🔗ℹ

(require setup/dirs) | 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-info-domain-root) → (or/c #false path?)

Returns #f or a path to be used as a prefix to redirect the paths used for recording and finding "info.rkt" information via find-relevant-directories.

Added in version 8.10.0.4 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.

See also 'build-stamp in Installation Configuration and Search Paths.

> procedure (get-main-language-family) → string?

Returns a string that names the installation’s main language family. A language family is a classification used in documentation, and the main language family configuration affects the way that documentation search results are printed. A language family is not merely a module-based language, but instead stands for a set of languages that share a module-naming convention; as a rule of thumb, a language family is distinct enough that it might have its own downloadable distribution. The default is "Racket".

See also 'main-language-family in Installation Configuration and Search Paths.

Added in version 8.14.0.5 of package base.

}

> procedure (get-base-documentation-packages) → (listof string?)
> procedure (get-distribution-documentation-packages) → (listof string?)

Returns a list of package names that represent a distribution’s base-language documentation and all of the documentation that is part of the distribution, respectively. These lists are used to classify and sort documentation search results. If a package is part of the base documentation, that classification takes precedence over distribution documentation.

See also 'base-documentation-packages and 'distribution-documentation-packages in Installation Configuration and Search Paths.

Added in version 8.14.0.5 of package base.

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

top contents ← prev up next →