Finding Racket Paths

This package provides an API and raco command that consolidates support for finding paths significant to Racket.

1 API for Finding Racket Paths

The procedures provided by whereis return local filesystem paths corresponding to Racket modules, collections, packages, etc.

See also raco whereis: Finding Racket Paths.

If modpath cannot be resolved or resolves to a nonexistant file, an exception is raised. If modpath refers to a submodule, the path of the enclosing top-level module is returned.

In contrast to collection-path, this procedure returns returns all directories associated with collection.

If no directories are found for collection, an exception is raised.

Like (pkg-directory pkg), but simplifies the result path.

If pkg is not installed, an exception is raised.

An error is reported if the given raco command is not registered. If the command is implemented by a submodule, the path of the enclosing top-level module is returned.

If name is unknown or if the implementation returns #f, an exception is raised.

Note that this procedure does not see through contract-out. That is, contract-out defines and exports an auxiliary macro to perform contract checking, and this procedure reports the definition site of the macro (the site where contract-out is used) instead of the definition site of the binding being protected.

If id does not refer to a module export at phase phase, or if the binding was defined by a built-in module (such as '#%kernel), an error is reported. If id is defined in a submodule, the path of the enclosing top-level module is returned.

If providing-mod does not have an export named name, or if the binding was defined by a built-in module (such as '#%kernel), an error is reported. If id is defined in a submodule, the path of the enclosing top-level module is returned.

2 raco whereis: Finding Racket Paths

The raco whereis command prints the local filesystem path corresponding to Racket modules, collections, packages, etc.

Command-line flags:

• -m ‹module-path› or --module ‹module-path› — Prints the path containing the declaration of the given module. The ‹module-path› argument must contain exactly one readable S-expression, otherwise an error is reported.

  Examples:

  • raco whereis -m racket/list

  • raco whereis -m racket/draw

  • raco whereis -m '(submod racket reader)' — same as raco whereis -m racket

  An error is reported if ‹module-path› cannot be resolved or if it “resolves” to a nonexistant file. If ‹module-path› refers to a submodule, the path of the enclosing top-level module is printed.

• -c ‹collection› or --collect ‹collection› — Prints the directory paths corresponding to the given collection. Note that a collection may have multiple directories, depending on collection roots and installed packages.

  Examples:

  • raco whereis -c json

  • raco whereis -c racket/gui

  • raco whereis -c drracket

  An error is reported if ‹collection› is invalid (see collection-name?) or if no directories are found.

• -p ‹package› or --pkg ‹package› — Prints the path of the directory containing ‹package›, which must be installed in some scope.

  Examples:

  • raco whereis -p base

  • raco whereis -p pict-lib

  If ‹package› is not installed, an error is reported.

• -r ‹command› or --raco ‹command› — Prints the path of the module implementing the given raco command.

  Examples:

  • raco whereis -r exe

  • raco whereis -r whereis

  An error is reported if the given raco command is not registered. If ‹command› is implemented by a submodule, the path of the enclosing top-level module is printed.

• -s ‹name› or --system ‹name› — Prints the path or paths corresponding to the given system location.

  The following location names are supported:

  • home-dir, pref-dir, pref-file, temp-dir, init-dir, init-file, addon-dir, doc-dir, desk-dir, sys-dir — Same as (find-system-path name).

    Example: raco whereis -s temp-dir

  • exec-file, config-dir, host-config-dir, collects-dir, host-collects-dir — Like (find-system-path name), but relative paths are converted into absolute paths by interpreting them with respect to the path of the racket executable.

    Example: raco whereis -s config-dir.

  • the name of a procedure from setup/dirs that returns a path or list of paths.

    Example: raco whereis -s find-config-dir.

  If ‹name› is unknown or if the corresponding procedure returns #f, an error is reported.

• --all-system-paths — Prints all supported “system” locations (that is, valid arguments to --system) and their values. If a location’s corresponding procedure returns #f, instead of printing an error message like --system, the location is printed without any values.

• -b ‹providing-module› ‹name› or --binding ‹providing-module› ‹name› — Prints the path of the module that defines the binding exported by ‹providing-module› as ‹name›. Note that the defined name might be different due to renamings.

  Examples:

  • raco whereis -b racket define

  • raco whereis -b racket in-list

  Note that whereis does not see through contract-out. That is, contract-out defines and exports an auxiliary macro to perform contract checking, and whereis reports the definition site of the macro (the site where contract-out is used) instead of the definition site of the binding being protected.

  If ‹name› is not provided by ‹providing-module›, or if the binding was defined by a built-in module (such as '#%kernel), an error is reported. If ‹name› is defined in a submodule, the path of the enclosing top-level module is printed.