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

For example, the command

  raco link maze

installs a user-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 both the 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.

• -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›. 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 collection-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, -i, and --installation.

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

2.1 API for Collection Links

(require setup/link)

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 false but root? is true, the result is a list of paths for collection roots. If remove? and root? are both false, the result is a list of top-level collection names (as strings) that are mapped by file and that apply to the running version of Racket.