2 Managing Packages

The Racket package manager has two user interfaces: a command line raco sub-command and a library. They have the exact same capabilities, as the command line interface invokes the library functions and reprovides all their options.

2.1 Command Line

The raco pkg sub-command provides the following sub-sub-commands:

• raco pkg install ‹option› ... ‹pkg-source› ... — Installs the given package sources with the given ‹option›s:

  • --type ‹type› or -t ‹type› — specifies an interpretation of the package source, where ‹type› is either file, dir, file-url, dir-url, github, or name.

  • --name ‹pkg› or -n ‹pkg› — specifies the name of the package, which makes sense only when a single ‹pkg-source› is provided. The name is normally inferred for each ‹pkg-source›.

  • --deps ‹behavior› — Selects the behavior for dependencies, where ‹behavior› is one of

    • fail — Cancels the installation if dependencies are version requirements are unmet (default for most packages)

    • force — Installs the package(s) despite missing dependencies or version requirements (unsafe)

    • search-ask — Looks for the dependencies or updates via the configured package name resolvers (default if the dependency is an indexed name) but asks if you would like it installed or updated.

    • search-auto — Like search-ask, but does not ask for permission to install or update.

  • --force — Ignores conflicts (unsafe)

  • --ignore-checksums — Ignores errors verifying package checksums (unsafe).

  • --no-setup — Does not run raco setup after installation. This behavior is also the case if the environment variable PLT_PKG_NOSETUP is set to any non-empty value.

  • --link — Implies --type dir (and overrides any specified type), and links the existing directory as an installed package.

  • --scope ‹scope› — Selects the package scope for installation, where ‹scope› is one of

    • installation — Install packages for all users of a Racket installation, rather than user-specific.

    • user — Install packages as user-specific and Racket version-specific.

    • shared — Install packages as user-specific, but for all Racket versions.

    The default package scope is normally user, but it can be configured with raco pkg config -i --set default-scope ‹scope›.

  • -i or --installation — Shorthand for --scope installation.

  • -u or --user — Shorthand for --scope user.

  • -s or --shared — Shorthand for --scope shared.

• raco pkg update ‹option› ... ‹pkg› ... — Checks the specified packages for package updates. If an update is found, but it cannot be installed (e.g. it conflicts with another installed package), then this command fails without installing any of the ‹pkg›s (or their dependencies). The update sub-command accepts the following ‹option›s:

  • --deps ‹behavior› — Same as for raco pkg install.

  • --all or -a — Update all packages, if no packages are given in the argument list.

  • --update-deps — Checks the named packages, and their dependencies (transitively) for updates.

  • --no-setup — Same as for raco pkg install.

  • --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

  • -i or --installation — Shorthand for --scope installation.

  • -u or --user — Shorthand for --scope user.

  • -s or --shared — Shorthand for --scope shared.

• raco pkg remove ‹option› ... ‹pkg› ... — Attempts to remove the given packages. If a package is the dependency of another package that is not listed, this command fails without removing any of the ‹pkg›s. It accepts the following ‹option›s:

  • --force — Ignore dependencies when removing packages.

  • --no-setup — Same as for raco pkg install.

  • --auto — Remove packages that were installed by the search-auto or search-ask dependency behavior and are no longer required.

  • --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

  • -i or --installation — Shorthand for --scope installation.

  • -u or --user — Shorthand for --scope user.

  • -s or --shared — Shorthand for --scope shared.

• raco pkg show ‹option› ... — Print information about currently installed packages. By default, packages are shown for all installation modes (installation-wide, user- and Racket-version-specific, and user-specific all-version). The command accepts the following ‹option›s:

  • -d — Adds a column in the output for the directory the package is installed to.

  • --scope ‹scope› — Shows only packages in ‹scope›, which is one of

    • installation — Show only installation-wide packages.

    • user — Show only user-specific, version-specific packages.

    • shared — Show only user-specific, all-version packages.

    The default is to show packages for all package scopes.

  • -i or --installation — Shorthand for --scope installation.

  • -u or --user — Shorthand for --scope user.

  • -s or --shared — Shorthand for --scope shared.

  • --version ‹vers› or -v ‹vers› — Show only user-specific packages for Racket version ‹vers›.

• raco pkg config ‹option› ... ‹key› ‹val› ... — View and modify package configuration options. It accepts the following ‹option›s:

  • --set — Sets an option, rather than printing it.

  • --scope ‹scope› — Selects a package scope, the same as for raco pkg install.

  • -i or --installation — Shorthand for --scope installation.

  • -u or --user — Shorthand for --scope user.

  • -s or --shared — Shorthand for --scope shared.

  The valid keys are:

  • indexes — A list of URLs for package name resolvers.

  • default-scope — Either installation, user, or shared. This configuration option exists only with the installation scope (i.e., it’s an installation-wide configuration of the default package scope for raco pkg commands).

• raco pkg create ‹option› ... ‹package-directory› — Bundles a package directory into a package archive. It accepts the following ‹option›s:

  • --format ‹format› — Specifies the archive format. The allowed ‹format›s are: zip (the default), tgz, and plt. This option must be specified if --manifest is not present.

  • --manifest — Creates a manifest file for a directory, rather than an archive.

2.2 Programmatic

The pkg module provides a programmatic interface to the command sub-sub-commands.

Each long form option of the command-line interface is keyword argument. An argument corresponding to --type, --deps, --format, or --scope accepts its argument as a symbol. All other options accept booleans, where #t is equivalent to the presence of the option.