9 raco link: Library Collection Links

The raco link command inspects and modifies a collection links file to display, add, or remove mappings from collection names to filesystem directories.

Managing links directly is somewhat discouraged. Instead, use the package manager (see Package Management in Racket), which installs and manages links (i.e., it builds on raco link) in a way that more gracefully leads to sharing collections with others. Nevertheless, raco link is available for direct use.

For example, the command

  raco link maze

installs a user-specific and version-specific link for the "maze" collection, mapping it to the "maze" subdirectory of the current directory. Supply multiple directory paths to create multiple links at once, especially with a command-shell wildcard:

  raco link *

By default, the linked collection name is the same as each directory’s name, but the collection name can be set separately for a single directory with the --name flag.

To remove the link created by the first example above, use

  raco link --remove maze

or

  raco link -r maze

Like link-adding mode, removing mode accepts multiple directory paths to remove multiple links, and all links that match any directory are removed. If --name is used with --remove, then only links matching both the collection name and directory are removed.

Full command-line options:

• -l or --list — Shows the current link table. If any other command-line arguments are provided that modify the link table, the table is shown after modifications. If no directory arguments are provided, and if none of -u, --user, -i, --installation, -f, or --file are specified, then the link table is shown for all user-specific and installation-wide collection links files.

• -n ‹name› or --name ‹name› — Sets the collection name for adding a single link or removing matching links. By default, the collection name for an added link is derived from the directory name. When the -r or --remove flag is also used, only links with a collection name matching ‹name› are removed, and if no directory arguments are provided, all links with a match to ‹name› are removed. This flag is mutually exclusive with -d and --root.

• -d or --root — Treats each directory as a collection root that contains collection directories, instead of a directory for a specific collection. When the -r or --remove flag is also used, only collection-root links that match a directory are removed. This flag is mutually exclusive with -n and --name.

• -D or --static-root — Like -d or --root, but each directory is assumed to have a constant set of subdirectories (to improve the use of collection-search caches) as long as the links file itself does not change.

• -x ‹regexp› or --version-regexp ‹regexp› — Sets a version regexp that limits the link to use only by Racket versions (as reported by version) matching ‹regexp›. This flag is normally used with -u or --user with installations that have different versions but the same installation name. When the -r or --remove flag is also used, only links with a version regexp matching ‹regexp› are removed.

• -r or --remove — Selects remove mode instead of add mode.

• -u or --user — Limits listing and removal of links to the user-specific collection links file and not the installation-wide collection links file. This flag is mutually exclusive with -i, --installation, -f, and --file.

• -i or --installation — Reads and writes links in installation-wide collection links file and not the user-specific collection links file. This flag is mutually exclusive with -u, --user, -f, and --file.

• -f ‹file› or --file ‹file› — Reads and writes links in ‹file› instead of the user-specific collection links file. This flag is mutually exclusive with -u, --user, -s, --shared, -i, and --installation.

• -v ‹vers› or --version ‹vers› — Selects ‹vers› as relevant installation name for operations on the user-specific collection links file.

• --repair — Enables repairs to the existing file content when the content is erroneous. The file is repaired by deleting individual links when possible.

9.1 API for Collection Links

The static-root? flag value is ignored unless root? is true and remove? is false, in which case each given dir is added as a static root if static-root? is true.

The error-proc argument is called to raise exceptions that would be fatal to the raco link command.

If remove? is true, the result is a list of entries that were removed from the file. If remove? is #f but root? is true, the result is a list of paths for collection roots. If remove? and root? are both #f, the result is a list for top-level collections that are mapped by file and that apply to the running version of Racket; the list is a list of strings for collection names if with-path? is #f, or it is a list of pairs of collection-name strings and complete paths if with-path? is true.