►raco:   Racket Command-Line Tools
▼6 raco setup:   Installation Management
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
find-lib-dir
find-user-lib-dir
get-lib-search-dirs
get-cross-lib-search-dirs
find-dll-dir
find-cross-dll-dir
find-share-dir
find-user-share-dir
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
find-apps-dir
find-user-apps-dir
find-man-dir
find-user-man-dir
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-config-tethered-console-bin-dir
find-config-tethered-gui-bin-dir
  top  ← 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, 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.

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

(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

(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

(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

(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-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) → string?

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.

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

Returns a path to a user-specific directory to hold an extra copy of each installed executable, 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 and 'addon-tethered-gui-bin-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 or find-addon-tethered-gui-bin-dir, is #f instead of a path.

The intent of this protocol is to support a kind of sandbox: an installation that is more specific than user-specific, and where copies of executables such as racket serve as entry points into the sandbox. Assuming that the addon directory is set to a directory other than the user’s default addon directory when raco setup creates the executable copies, then further package build and setup operations through the entry points will be confined to the sandbox and not affect a user’s default environment.

Added in version 6.5.0.2 of package base.

procedure

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

procedure

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

Similar to find-addon-tethered-console-bin-dir and find-addon-tethered-gui-bin-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).

Added in version 6.5.0.2 of package base.

  top  ← prev  up  next →