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-doc-search-url
get-doc-open-url
get-installation-name
get-build-stamp
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

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

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.

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.

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.

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.

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.

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

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.

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

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.

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

Added in version 8.1.0.6 of package base.

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.

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.

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.

Returns the current installation’s name, which is often (version) but can be configured via 'installation-name in "config.rktd" (see Installation Configuration and Search Paths).

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.

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

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.

]

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.