3 Using raco pkg

The raco pkg command provides package-management tools via sub-commands.

3.1 raco pkg install

raco pkg install ‹option› ... ‹pkg-source› ... — Installs the given package sources (eliminating exact-duplicate ‹pkg-source›s). If a given ‹pkg-source› is “auto-installed” (to satisfy some other package’s dependency), then it is promoted to explicitly installed.

If no ‹pkg-source›s are supplied, the current directory is installed as a link. See the --link flag below for more details.

The install sub-command accepts the following ‹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›.

• --checksum ‹checksum› — specifies a checksum for the package, which normally makes sense only when a single ‹pkg-source› is provided. The use of ‹checksum› depends on ‹pkg-source›: for a GitHub source, ‹checksum› selects a checksum; for a package name, file path, or remote URL as a source, ‹checksum› specifies an expected checksum; for a directory path (including a remote directory URL without a ".CHECKSUM" file) as a source, ‹checksum› assigns a checksum.

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

  • fail — Cancels the installation if dependencies are uninstalled or version requirements are unmet. This behavior is the default for a ‹pkg-source› that is not a package name.

  • force — Installs the package(s) despite missing dependencies or version requirements. Forcing an installation may leave package content in an inconsistent state.

  • search-ask — Looks for dependencies (when uninstalled) or updates (when version requirements are unmet) via the configured package catalogs, but asks if you would like the packages installed or updated. This behavior is the default for a ‹pkg-source› that is a package name.

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

• --auto — Shorthand for --deps search-auto.

• --update-deps — With search-ask or search-auto dependency behavior, checks already-installed dependencies transitively for updates (even when not forced by version requirements), asking or automatically updating a package when an update is available. When a package is updated or installed, unless --skip-implies is specified, any package that it implies (see Package Metadata) is automatically updated independent of the behavior requested via --update-deps and --deps.

• --skip-implies — Disables special treatment of dependencies that are listed in implies (see Package Metadata) for an installed or updated package.

• --link — Implies --type dir (and overrides any specified type), and links the existing directory as an installed package, instead of copying the directory’s content to install. Directory package sources are treated as links by default, unless --copy is specified.

  The package is identified as a single-collection package or a multi-collection package at the time that it is installed, and that categorization does not change even if the collection definition in "info.rkt" is changed (i.e., he package must be removed and re-installed for the change to take effect).

• --static-link — Implies --link, and also indicates that subdirectories of the given directory will not change for each given directory that implements a multi-collection package.

• --pkgs — Disables default installation of the current directory when no ‹pkg-source›s are supplied.

• --copy — Disables default handling of directory package sources as links, and instead treats them like other sources: package content is copied to install.

• --binary — Strips source elements of a package before installing, and implies --copy.

• --source — Strips built elements of a package before installing, and implies --copy.

• --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 for the current user and current installation’s name/version.

  The default package scope is normally user, but it can be configured with raco pkg config --set default-scope ‹scope›. The default installation name is normally the Racket version, but it can be configured with raco pkg config --set name ‹name›.

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

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

• --scope-dir ‹dir› — Select ‹dir› as the package scope.

• --catalog ‹catalog› — Use ‹catalog› instead of of the currently configured package catalogs.

• --skip-installed — Ignore any ‹pkg-source› whose name corresponds to an already-installed package, except for promoting auto-installed packages to explicitly installed.

• --all-platforms — Considers package dependencies independent of the current platform (instead of filtering dependencies to platforms other than the current one).

• --force — Ignores module conflicts, including conflicts due to installing a single package in multiple scopes. Forcing an installation may leave package content in an inconsistent state.

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

• --strict-doc-conflicts — Refuses to install in user package scope when documentation-directory names would conflict with other packages. “Conflicting” documentation names are normally allowed for installation in user package scope, but strict checking ensures that installation would succeed in other package scopes.

• --no-cache — Disables use of the download cache.

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

• --jobs ‹n› or -j ‹n› — Install and setup with ‹n› parallel jobs.

• --fail-fast — Breaks raco setup as soon as any error is encountered.

3.2 raco pkg update

raco pkg update ‹option› ... ‹pkg-source› ... — Checks the specified package names for package updates or replaces existing package installations with the given sources. If an update or replacement cannot be installed (e.g. it conflicts with another installed package), then this command fails without installing any of the ‹pkg-source›s (or their dependencies).

If a package scope is not specified, the scope is inferred from the given ‹pkg-source›s.

The update sub-command accepts the following ‹option›s:

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

• --lookup — Checks Causes a package name as a ‹pkg-source› to be used as a replacement, instead of the name of a installed package that may have updates. (If the named package was installed through a package name, then there’s effectively no difference.)

• --type ‹type› or -t ‹type› — Same as for raco pkg install.

• --name ‹pkg› or -n ‹pkg› — Same as for raco pkg install.

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

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

• --auto — Shorthand for --deps search-auto plus --update-deps.

• --update-deps — Same as for raco pkg install, but implied by --auto only for raco pkg update.

• --skip-implies — Same as for raco pkg install.

• --link — Same as for raco pkg install.

• --static-link — Same as for raco pkg install.

• --binary — Same as for raco pkg install.

• --copy — Same as for raco pkg install.

• --source — 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.

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

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

• --all-platforms — Same as for raco pkg install.

• --force — Same as for raco pkg install.

• --ignore-checksums — Same as for raco pkg install.

• --strict-doc-conflicts — Same as for raco pkg install.

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

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

• --jobs ‹n› or -j ‹n› — Same as for raco pkg install.

3.3 raco pkg remove

raco pkg remove ‹option› ... ‹pkg› ... — Attempts to remove the given packages. By default, if a package is the dependency of another package that is not listed, this command fails without removing any of the ‹pkg›s.

If a package scope is not specified, the scope is inferred from the given ‹pkg›s.

The remove sub-command accepts the following ‹option›s:

• --demote — “Remove” explicitly installed packages by demoting them to auto-installed (leaving auto-installed packages as such). Combined with --auto, removes packages for which there are no dependencies.

• --force — Ignore dependencies when removing packages.

• --auto — In addition to removing each ‹pkg›, remove auto-installed packages (i.e., installed by the search-auto or search-ask dependency behavior, or demoted via --demote) that are no longer required by any explicitly installed package.

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

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

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

• --jobs ‹n› or -j ‹n› — Same as for raco pkg install.

3.4 raco pkg show

raco pkg show ‹option› ... — Print information about currently installed packages. By default, packages are shown for all package scopes, but only for packages not marked as auto-installed to fulfill dependencies.

The show sub-command accepts the following ‹option›s:

• -a or --all — Includes auto-installed packages in the listing.

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

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

  • installation — Show only installation-wide packages.

  • user — Show only user-specific packages for the current installation’s name/version or the name/version specified with --version or -v.

  The default is to show packages for all package scopes.

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

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

• --scope-dir ‹dir› — Shows only packages installed in ‹dir›.

• --version ‹vers› or -v ‹vers› — Show only user-specific packages for the installation name/version ‹vers›.

3.5 raco pkg migrate

raco pkg migrate ‹option› ... ‹from-version› — Installs packages that were previously installed in user package scope for ‹from-version›, where ‹from-version› is an installation name/version.

3.6 raco pkg create

raco pkg create ‹option› ... ‹directory-or-package› — Bundles a package into an archive. Bundling is not needed for a package that is provided directly from a GitHub repository or other non-archive formats. The create sub-command can create an archive from a directory (the default) or from an installed package. It can also adjust the archive’s content to include only sources, only compiled bytecode and rendered documentation, or both—but packages are normally provided as source and converted to binary form by an automatic service, instead of by a package author.

The create sub-command accepts the following ‹option›s:

• --from-dir — Treat ‹directory-or-package› as a directory path; this is the default mode.

• --from-install — Treat ‹directory-or-package› as the name of an installed package (instead of a directory).

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

• --as-is — Bundle all content of the package directory as is, with no filtering of sources, compiled files, or repository elements.

• --source — Bundle only sources in the package directory; see Source, Binary, and Built Packages.

• --binary — Bundle compiled bytecode and rendered documentation in the package directory; see Source, Binary, and Built Packages.

• --built — Bundle compiled sources, bytecode, and rendered documentation in the package directory, filtering repository elements; see Source, Binary, and Built Packages.

• --dest ‹dest-dir› — Writes generated bundles to ‹dest-dir›.

3.7 raco pkg config

raco pkg config ‹option› ... [‹key›] ‹val› ... — View and modify the configuration of the package manager. If ‹key› is not provided, the values for all recognized keys are shown. The ‹val› arguments are allowed only when --set is used, in which case the ‹val›s are used as the new values for ‹key›.

The config sub-command accepts with 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. A configuration value set at installation scope serves as the default value at user scope.

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

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

• --scope-dir ‹dir› — Same as for raco pkg install.

3.8 raco pkg catalog-show

raco pkg catalog-show ‹option› ... ‹package-name› ... — Consults package catalogs for a package (that is not necessarily installed) and displays the catalog’s information for the package, such as its source URL and a checksum.

The catalog-show sub-command accepts the following ‹option›s:

• --all — Show information for all available packages. When using this flag, supply no ‹packaee-name›s.

• --only-names — Show only package names. This option is mainly useful with --all, but when a ‹packaee-name› is provided, catalogs are consulted to ensure that he package is available.

• --modules — Show the modules that are implemented by a package.

• --catalog ‹catalog› — Query ‹catalog› instead of the currently configured package catalogs.

• --version ‹version› or -v ‹version› — Query catalogs for a result specific to ‹version›, instead of the installation’s Racket version.

3.9 raco pkg catalog-copy

raco pkg catalog-copy ‹option› ... ‹src-catalog› ... ‹dest-catalog› — Copies information from the package catalog named by ‹src-catalog›s to a local database or directory ‹dest-catalog›, which can be used as a new package catalog.

The ‹src-catalog›s can be remote or local, while ‹dest-catalog› must be local (i.e., a directory path or a SQLite database path, as inferred from the path). If a ‹src-catalog› or ‹dest-catalog› does not start with a URL scheme, it is treated as a filesystem path. Information from multiple ‹src-catalog›s is merged, with information from earlier ‹src-catalog›s taking precedence over later ‹src-catalog›s.

The catalog-copy sub-command accepts the following ‹option›s:

• --from-config — Adds the currently configured package catalogs to the end of the ‹src-catalog›s list.

• --force — Replaces ‹dest-catalog› if it exists already.

• --merge — Adds to ‹dest-catalog› if it exists already. By default, information already in ‹dest-catalog› takes precedence over new information.

• --override — Changes merging so that new information takes precedence over information already in ‹dest-catalog›.

• --relative — Write package sources to ‹dest-catalog› in relative-path form, when possible.

• --version ‹version› or -v ‹version› — Copy catalog results specific to ‹version› (for catalogs that make a distinction), instead of the installation’s Racket version.

3.10 raco pkg catalog-archive

raco pkg catalog-archive ‹option› ... ‹dest-dir› ‹src-catalog› ... — Copies information from the package catalog named by ‹src-catalog›s to a "catalog" directory catalog in ‹dest-dir›, and also copies all package sources to a "pkgs" directory in ‹dest-dir›.

Packages sources are downloaded and repacked as needed, so that all packages are written to the "pkgs" directory as ".zip" archives. This conversion may change the checksum on each archived package.

The catalog-archive sub-command accepts the following ‹option›s:

• --from-config — Adds the currently configured package catalogs to the end of the ‹src-catalog›s list.

• --state ‹state-database› — To enable incremental updating, Reads and writes the database ‹state-database›, which must have the suffix ".sqlite", as the current state of ‹dest-dir›.

• --relative — Write package sources to ‹dest-catalog› in relative-path form.

• --version ‹version› or -v ‹version› — Copy catalog results specific to ‹version› (for catalogs that make a distinction), instead of the installation’s Racket version.

Added in version 6.0.17.

3.11 raco pkg archive

raco pkg archive ‹option› ... ‹dest-dir› ‹pkg› ... — Copies information from installed packages named by ‹pkgs›s to a "catalog" directory catalog in ‹dest-dir›, and also copies all package sources to a "pkgs" directory in ‹dest-dir›.

Packages sources are copied and repacked as needed, so that all packages are written to the "pkgs" directory as ".zip" archives. This conversion may change the checksum on each archived package.

The archive sub-command accepts the following ‹option›s:

• --include-deps — Includes the dependencies of the specified packages in the resulting catalog.

• --exclude ‹pkg› — Omits the specified ‹pkg› from the resulting catalog. This also causes the dependencies of ‹pkg› to be omitted if --include-deps is specified. This flag can be provided multiple times.

• --relative — Write package sources to ‹dest-catalog› in relative-path form.

Added in version 6.1.0.8.