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 (Beta)), 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 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
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.
Enables repairs to the existing file content when the content is erroneous. The file is repaired by deleting individual links when possible.
dir : path? user? : any/c = #t file : (or/c path-string? #f) = #f name : (or/c string? #f) = #f root? : any/c = #f version-regexp : (or/c regexp? #f) = #f error-proc : (symbol? string? any/c ... . -> . any) = error remove? : any/c = #f show? : any/c = #f repair? : any/c = #f with-path? : any/c = #f
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.