On this page:
9.1 API for Collection Links

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


  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:

9.1 API for Collection Links

 (require setup/link) package: base


(links dir    
  [#:user? user?    
  #:user-version user-version    
  #:file file    
  #:name name    
  #:root? root?    
  #:static-root? static-root?    
  #:version-regexp version-regexp    
  #:error error-proc    
  #:remove? remove?    
  #:show? show?    
  #:repair? repair?    
  #:with-path? with-path?])  list?
  dir : path?
  user? : any/c = #t
  user-version : string? = (get-installation-name)
  file : (or/c path-string? #f) = #f
  name : (or/c string? #f) = #f
  root? : any/c = #f
  static-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
A function version of the raco link command that always works on a single file—either file if it is a path string, the user–specific collection links file if user? is true, or the installation-wide collection links file otherwise. If user? is true, then user-version determines the relevant installation name (defaulting to the current installation’s name).

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.