7.2 Package Management Functions

► |  | Package Management in Racket

1 | Getting Started with Packages
2 | Package Concepts
3 | Using raco pkg
4 | Package Metadata
5 | Source, Binary, and Built Packages
6 | Developing Packages with Git
7 | Package APIs
8 | Package Catalog Protocol
9 | PLane T Compatibility
10 | FAQ
11 | Future Plans
12 | How Package Installation and Distribution Works

▼ | 7 | Package APIs

7.1 | Functions for raco pkg
7.2 | Package Management Functions
7.3 | Package Paths and Database
7.4 | Package Source Parsing
7.5 | Package Catalog Database
7.6 | Package Directories Catalog
7.7 | Package Management Environment Variables

On this page:

with-pkg-lock
with-pkg-lock/ read-only
current-pkg-scope
current-pkg-scope-version
current-pkg-lookup-version
current-pkg-error
current-pkg-catalogs
pkg-config-catalogs
current-pkg-download-cache-dir
current-pkg-download-cache-max-files
current-pkg-download-cache-max-bytes
current-pkg-trash-max-packages
current-pkg-trash-max-seconds
current-pkg-network-retries
current-pkg-network-timeout
pkg-directory
default-pkg-scope
installed-pkg-names
installed-pkg-table
pkg-desc?
pkg-desc
pkg-stage
pkg-config
pkg-create
pkg-install
pkg-update
pkg-remove
pkg-new
pkg-show
pkg-migrate
pkg-migrate-available-versions
pkg-catalog-show
pkg-catalog-copy
pkg-catalog-archive
pkg-archive-pkgs
pkg-empty-trash
pkg-catalog-update-local
pkg-catalog-suggestions-for-module
get-all-pkg-scopes
get-all-pkg-names-from-catalogs
get-all-pkg-details-from-catalogs
get-pkg-details-from-catalogs
pkg-single-collection
get-pkg-content
extract-pkg-dependencies
pkg-directory->module-paths
pkg-directory->additional-installs
pkg-config-default-scope-scope
call-in-pkg-timeout-sandbox

9.2
Racket
top contents ← prev up next →

### 7.2 Package Management Functions🔗ℹ

(require pkg/lib) | package: base

The pkg/lib library provides building blocks on which the pkg library and raco pkg commands are built. It re-exports the bindings of pkg/path.

> syntax (with-pkg-lock body ...+)
> syntax (with-pkg-lock/read-only body ...+)

Evaluates the bodys while holding a lock to prevent concurrent modification to the package database for the current package scope. Use the with-pkg-lock/read-only form for read-only access. The lock is reentrant but not upgradable from read-only.

Use these form to wrap uses of functions from pkg/lib that are documented to require the lock. Other functions from pkg/lib take the lock as needed.

> > parameter
> > (current-pkg-scope) |  | → |  |
> > (or/c 'installation 'user
> > (and/c path? complete-path?))
> (current-pkg-scope scope) → void?
> | scope |  | : |  |
> (or/c 'installation 'user
> (and/c path? complete-path?))
> parameter (current-pkg-scope-version) → string?
> (current-pkg-scope-version s) → void?
> s : string?

Parameters that determine package scope for management operations and, in the case of 'user scope, the relevant installation name/version.

> parameter (current-pkg-lookup-version) → string?
> (current-pkg-lookup-version s) → void?
> s : string?

Parameter that determines the relevant Racket version for extracting package information from a catalog.

Added in version 6.0.1.7 of package base.

> parameter (current-pkg-error) → procedure?
> (current-pkg-error err) → void?
> err : procedure?

A parameter whose value is used to report errors that are normally intended for end uses. The arguments to the procedure are the same as for error, except that an initial symbol argument is omitted.

The default value uses error with 'pkg as the first argument. The raco pkg command sets this parameter to use raise-user-error with the sub-command name as its first argument.

> parameter (current-pkg-catalogs) → (or/c #f (listof url?))
> (current-pkg-catalogs catalogs) → void?
> catalogs : (or/c #f (listof url?))

A parameter that determines the package catalogs that are consulted to resolve a package name. If the parameter’s value is #f, then the result of pkg-config-catalogs is used.

> procedure (pkg-config-catalogs) → (listof string?)

Returns a list of URL strings for the user’s configured package catalogs.

> parameter (current-pkg-download-cache-dir)
> → (or/c #f (and/c path-string? complete-path?))
> (current-pkg-download-cache-dir dir) → void?
> dir : (or/c #f (and/c path-string? complete-path?))
> parameter (current-pkg-download-cache-max-files) → (or/c #f real?)
> (current-pkg-download-cache-max-files max-files) → void?
> max-files : (or/c #f real?)
> parameter (current-pkg-download-cache-max-bytes) → (or/c #f real?)
> (current-pkg-download-cache-max-bytes max-bytes) → void?
> max-bytes : (or/c #f real?)

Parameters that determine the download cache location and limits. If a parameter’s value is #f, then the user’s configuration is used.

> parameter (current-pkg-trash-max-packages) → (or/c #f real?)
> (current-pkg-trash-max-packages max-packages) → void?
> max-packages : (or/c #f real?)
> parameter (current-pkg-trash-max-seconds) → (or/c #f real?)
> (current-pkg-trash-max-seconds max-seconds) → void?
> max-seconds : (or/c #f real?)

Parameters that determine the trash-directory limits. If a parameter’s value is #f, then the user’s configuration is used.

Added in version 6.1.1.6 of package base.

> parameter (current-pkg-network-retries) → (or/c #f real?)
> (current-pkg-network-retries max-retries) → void?
> max-retries : (or/c #f real?)

A parameter that determines the number of times to retry a network communication that fails due to a connection error. If a parameter’s value is #f, then the user’s configuration is used.

Added in version 6.3 of package base.

> parameter (current-pkg-network-timeout) → (or/c #f real?)
> (current-pkg-network-timeout max-seconds) → void?
> max-seconds : (or/c #f real?)

A parameter that determines the number of seconds to wait for a network communication, such as a download or a checksum fetch. If a parameter’s value is #f, then the user’s configuration is used.

Added in version 9.0.0.2 of package base.

> procedure (pkg-directory name [#:cache cache]) → (or/c path-string? #f)
> name : string?
> cache : (or/c #f (and/c hash? (not/c immutable?))) = #f

Returns the directory that holds the installation of the installed (in any scope) package name, or #f if no such package is installed.

For multiple calls to pkg-directory, supply the same equal?-based mutable hash table (initially empty) as the cache argument. Otherwise, package-installation information must be re-parsed on every call to pkg-directory.

Changed in version 6.1.1.6 of package base: Added the #:cache argument.

> > procedure
> > (default-pkg-scope) |  | → |  |
> > (or/c 'installation 'user
> > (and/c path? complete-path?))

Returns the user’s configured default package scope.

> procedure (installed-pkg-names #:scope scope) → (listof string?)
> | scope |  | : |  |
> (or/c #f 'installation 'user
> (and/c path? complete-path?))

Returns a list of installed package names for the given package scope, where #f indicates the user’s default package scope.

> procedure (installed-pkg-table #:scope scope)
> → (hash/c string? pkg-info?)
> | scope |  | : |  |
> (or/c #f 'installation 'user
> (and/c path? complete-path?))

Returns a hash table of installed packages for the given package scope, where #f indicates the user’s default package scope.

> procedure (pkg-desc? v) → boolean?
> v : any/c
> > procedure
> > (pkg-desc |  | source |  |  |  |
> > |  | type |  |  |  |
> > |  | name |  |  |  |
> > |  | checksum |  |  |  |
> > |  | auto? |  |  |  |
> > | [ | #:path path]) |  | → |  | pkg-desc?
> source : string?
> | type |  | : |  |
> (or/c #f 'name 'file 'dir 'link 'static-link
> 'file-url 'dir-url 'git 'git-url 'github 'clone)
> name : (or/c string? #f)
> checksum : (or/c string? #f)
> auto? : boolean?
> path : (or/c #f path-string?) = #f

A pkg-desc value describes a package source plus details of its intended interpretation, where the auto? field indicates that the package is should be treated as installed automatically for a dependency.

The optional path argument is intended for use when type is 'clone, in which case it specifies a directory containing the repository clone (where the repository itself is a directory within path).

Changed in version 6.1.1.1 of package base: Added 'git as a type.
Changed in version 6.1.1.5: Added 'clone as a type.
Changed in version 8.0.0.13: Added 'git-url as a type.

> > procedure
> > (pkg-stage |  | desc |  |  |  |
> > | [ | #:checksum checksum |  |  |  |
> > |  | #:in-place? in-place? |  |  |  |
> > |  | #:namespace namespace |  |  |  |
> > |  | #:strip strip |  |  |  |
> > |  | #:force-strip? force-strip? |  |  |  |
> > |  | #:use-cache? use-cache? |  |  |  |
> > |  | #:quiet? quiet?]) |  | → |  |
> > string?
> > path?
> > (or/c #f string?)
> > boolean?
> > (set/c module-path?)
> desc : pkg-desc?
> checksum : (or/c #f string?) = #f
> in-place? : boolean? = #f
> namespace : namespace? = (make-base-namespace)
> strip : (or/c #f 'source 'binary 'binary-lib) = #f
> force-strip? : boolean? = #f
> use-cache? : boolean? = #f
> quiet? : boolean? = #t

Locates the implementation of the package specified by desc and downloads and unpacks it to a temporary directory (as needed).

If desc refers to an existing directory and in-place? is true, then the directory is used in place.

The namespace argument is passed along to get-info/full when the package’s "info.rkt" is loaded.

If strip is not #f, then files and directories are removed from the prepared directory the same as when creating the corresponding kind of package. A directory that is staged in-place cannot be stripped. If force-strip? is true, then a consistency check (intended to avoid stripping a source package as binary, for example) is skipped.

If use-cache? is true, then a local cache is consulted before downloading a particular package with a particular checksum. Note that the default for use-cache? is #f, while the default is #t for other functions that accept #:use-cache?.

The result is the package name, the directory containing the unpacked package content, the checksum (if any) for the unpacked package, whether the directory should be removed after the package content is no longer needed, and a list of module paths provided by the package.

> > procedure
> > (pkg-config |  | set? |  |  |  |
> > |  | keys/vals |  |  |  |
> > | [ | #:from-command-line? from-command-line? |  |  |  |
> > |  | #:default-scope-scope default-scope-scope]) |  | → |  | void?
> set? : boolean?
> keys/vals : list?
> from-command-line? : boolean? = #f
> | default-scope-scope |  | : |  | (or/c #f 'installation 'user (and/c path? complete-path?))
> |  |  | = |  | #f

Implements pkg-config-command.

If from-command-line? is true, error messages may suggest specific command-line flags for raco pkg config.

If default-scope-scope is not #f, then it specifies potentially narrower scope than (current-pkg-scope) where 'default-scope is configured. That information may trigger output to warn a user that a 'default-scope setting in a wider scope does not have any effect. See also pkg-config-default-scope-scope.

The package lock must be held (allowing writes if set? is true); see with-pkg-lock.

Changed in version 7.7.0.9 of package base: Added the #:default-scope-scope argument.

> > procedure
> > (pkg-create |  | format |  |  |  |
> > |  | dir |  |  |  |
> > |  | #:source source |  |  |  |
> > |  | #:mode mode |  |  |  |
> > |  | #:dest dest-dir |  |  |  |
> > | [ | #:original original-source |  |  |  |
> > |  | #:quiet? quiet? |  |  |  |
> > |  | #:from-command-line? from-command-line?]) |  | → |  | void?
> format : (or/c 'zip 'tgz 'plt 'MANIFEST)
> dir : path-string?
> source : (or/c 'dir 'name)
> mode : (or/c 'as-is 'source 'binary 'binary-lib 'built)
> dest-dir : (or/c (and/c path-string? complete-path?) #f)
> original-source : (or/c string? #f) = #f
> quiet? : boolean? = #f
> from-command-line? : boolean? = #f

Implements pkg-create-command.

Unless quiet? is true, information about the output is reported to the current output port. If from-command-line? is true, error messages may suggest specific command-line flags for raco pkg create.

Changed in version 8.14.0.2 of package base: Added the #:original argument.

> > procedure
> > (pkg-install |  | descs |
> > | [ | #:dep-behavior dep-behavior |
> > |  | #:update-deps? update-deps? |
> > |  | #:force? force? |
> > |  | #:ignore-checksums? ignore-checksums? |
> > |  | #:strict-doc-conflicts? strict-doc-conflicts? |
> > |  | #:use-cache? use-cache? |
> > |  | #:quiet? quiet? |
> > |  | #:use-trash? use-trash? |
> > |  | #:from-command-line? from-command-line? |
> > |  | #:strip strip |
> > |  | #:force-strip? force-strip? |
> > |  | #:multi-clone-mode multi-clone-mode |
> > |  | #:pull-mode pull-mode |
> > |  | #:link-dirs? link-dirs? |
> > |  | #:dry-run? dry-run?]) |
> | → |  |
> (or/c 'skip
> #f
> (listof (or/c path-string?
> (non-empty-listof path-string?))))
> descs : (listof pkg-desc?)
> | dep-behavior |  | : |  | (or/c #f 'fail 'force 'search-ask 'search-auto)
> |  |  | = |  | #f
> update-deps? : boolean? = #f
> force? : boolean? = #f
> ignore-checksums? : boolean? = #f
> strict-doc-conflicts? : boolean? = #f
> use-cache? : boolean? = #t
> quiet? : boolean? = #f
> use-trash? : boolean? = #f
> from-command-line? : boolean? = #f
> strip : (or/c #f 'source 'binary 'binary-lib) = #f
> force-strip? : boolean? = #f
> multi-clone-mode : (or/c 'fail 'force 'convert 'ask) = 'fail
> pull-mode : (or/c 'ff-only 'try 'rebase) = 'ff-only
> link-dirs? : boolean? = #f
> dry-run? : boolean? = #f

Implements pkg-install-command. The result indicates which collections should be setup via raco setup: 'skip means that no setup is needed, #f means all, and a list means only the indicated collections.

The link-dirs? argument determines whether package sources inferred to be directory paths should be treated as links or copied (like other package sources). Note that the default is #f, unlike the default built into pkg-install-command.

A pkg-desc can have the type 'clone and a source with the syntax of a package name, in which case it refers to a package name that must be mapped to a Git repository by the package catalog, and in will be installed as a clone.

Status information and debugging details are mostly reported to a logger named 'pkg, but information that is especially relevant to a user (such as a download action) is reported to the current output port, unless quiet? is true.

If from-command-line? is true, error messages may suggest specific command-line flags for raco pkg install.

The package lock must be held; see with-pkg-lock.

Changed in version 6.1.1.5 of package base: Added the #:multi-clone-mode and #:infer-clone-from-dir? arguments.
Changed in version 6.1.1.6: Added the #:use-trash? argument.
Changed in version 6.1.1.8: Added the #:pull-mode argument.
Changed in version 6.4.0.14: Added the #:dry-run argument.

> > procedure
> > (pkg-update |  | sources |
> > | [ | #:all? all? |
> > |  | #:dep-behavior dep-behavior |
> > |  | #:update-deps? update-deps? |
> > |  | #:force? force? |
> > |  | #:ignore-checksums? ignore-checksums? |
> > |  | #:strict-doc-conflicts? strict-doc-conflicts? |
> > |  | #:use-cache? use-cache? |
> > |  | #:skip-uninstalled? skip-uninstalled? |
> > |  | #:quiet? quiet? |
> > |  | #:use-trash? use-trash? |
> > |  | #:from-command-line? from-command-line? |
> > |  | #:strip strip |
> > |  | #:force-strip? force-strip? |
> > |  | #:lookup-for-clone? lookup-for-clone? |
> > |  | #:multi-clone-mode multi-clone-mode |
> > |  | #:pull-mode pull-mode |
> > |  | #:link-dirs? link-dirs? |
> > |  | #:infer-clone-from-dir? infer-clone-from-dir? |
> > |  | #:dry-run? dry-run?]) |
> | → |  |
> (or/c 'skip
> #f
> (listof (or/c path-string?
> (non-empty-listof path-string?))))
> sources : (listof (or/c string? pkg-desc?))
> all? : boolean? = #f
> | dep-behavior |  | : |  | (or/c #f 'fail 'force 'search-ask 'search-auto)
> |  |  | = |  | #f
> update-deps? : boolean? = #f
> force? : boolean? = #f
> ignore-checksums? : boolean? = #f
> strict-doc-conflicts? : boolean? = #f
> use-cache? : boolean? = #t
> skip-uninstalled? : boolean? = #t
> quiet? : boolean? = #f
> use-trash? : boolean? = #f
> from-command-line? : boolean? = #f
> strip : (or/c #f 'source 'binary 'binary-lib) = #f
> force-strip? : boolean? = #f
> lookup-for-clone? : boolean? = #f
> multi-clone-mode : (or/c 'fail 'force 'convert 'ask) = 'fail
> pull-mode : (or/c 'ff-only 'try 'rebase) = 'ff-only
> link-dirs? : boolean? = #f
> infer-clone-from-dir? : boolean? = #f
> dry-run? : boolean? = #f

Implements pkg-update-command. The result is the same as for pkg-install.

A string in sources refers to an installed package that should be checked for updates. A pkg-desc in sources indicates a package source that should replace the current installation; as an exception, if a pkg-desc has the type 'clone and a source with the syntax of a package name, it refers to an existing package installation that should be converted to a Git repository clone—unless lookup-for-clone? is true, in which case the package name is resolved through a catalog to locate a Git repository clone.

The link-dirs? and infer-clone-from-dir? arguments affect how directory paths in sources are treated. The link-dirs? argument is propagated to package-source->name+type, while infer-clone-from-dir? introduces a conversion from a directory source to a repository-clone source when the directory corresponds to an existing repository-clone installation.

If from-command-line? is true, error messages may suggest specific command-line flags for raco pkg update.

The package lock must be held; see with-pkg-lock.

Changed in version 6.1.1.5 of package base: Added the #:multi-clone-mode and #:infer-clone-from-dir? arguments.
Changed in version 6.1.1.6: Added the #:use-trash? argument.
Changed in version 6.1.1.8: Added the #:skip-uninstalled? and #:pull-mode arguments.
Changed in version 6.4.0.14: Added the #:dry-run argument.

> > procedure
> > (pkg-remove |  | names |
> > | [ | #:demote? demote? |
> > |  | #:auto? auto? |
> > |  | #:force? force? |
> > |  | #:quiet? quiet? |
> > |  | #:use-trash? boolean? |
> > |  | #:from-command-line? from-command-line? |
> > |  | #:dry-run? dry-run?]) |
> | → |  |
> (or/c 'skip
> #f
> (listof (or/c path-string?
> (non-empty-listof path-string?))))
> names : (listof string?)
> demote? : boolean? = #f
> auto? : boolean? = #f
> force? : boolean? = #f
> quiet? : boolean? = #f
> boolean? : use-trash? = #f
> from-command-line? : boolean? = #f
> dry-run? : boolean? = #f

Implements pkg-remove-command. The result is the same as for pkg-install, indicating collects that should be setup via raco setup.

If from-command-line? is true, the function pkg-remove may recommend additional instructions for removing automatically installed packages in the standard output. The error messages can also suggest specific command-line flags for raco pkg remove.

When quiet? is true, the messages in the standard output are suppressed.

The package lock must be held; see with-pkg-lock.

Changed in version 6.1.1.6 of package base: Added the #:use-trash? argument.
Changed in version 6.4.0.14: Added the #:dry-run argument.
Changed in version 8.6.0.7: Added the suggestion for removing automatically installed packages.

> procedure (pkg-new name) → (void?)
> name : path-string?

Implements pkg-new-command.

The name parameter is the name of the new package.

> > procedure
> > (pkg-show |  | indent |  |  |  |
> > |  | pkgs-or-patterns |  |  |  |
> > | [ | #:prefix-line prefix-line |  |  |  |
> > |  | #:auto? auto? |  |  |  |
> > |  | #:rx? rx? |  |  |  |
> > |  | #:long? long? |  |  |  |
> > |  | #:full-checksum? full-checksum? |  |  |  |
> > |  | #:directory show-dir?]) |  | → |  | void?
> indent : string?
> pkgs-or-patterns : (or/c #f (listof string?))
> prefix-line : (or/c #f string?) = #f
> auto? : boolean? = #f
> rx? : boolean? = #f
> long? : boolean? = #f
> full-checksum? : boolean? = #f
> show-dir? : boolean? = #f

Implements pkg-show-command for a single package scope, printing to the current output port. If prefix-lines is not #f, it is printed before the output. See also installed-pkg-names and installed-pkg-table.

If pkgs-or-patterns is #f, then information is shown for all installed packages, otherwise only matching packages are shown. In rx? is true, then elements of pkgs-or-patterns are treated as regular expression patterns, otherwise they are treated as package names.

The package lock must be held to allow reads; see with-pkg-lock/read-only.

Changed in version 6.1.1.5 of package base: Added the #:long? argument.
Changed in version 6.1.1.6: Added the #:full-checksum? and #:rx? arguments.
Changed in version 6.5.0.1: Added the #:prefix-line argument.

> > procedure
> > (pkg-migrate |  | from-version |
> > | [ | #:dep-behavior dep-behavior |
> > |  | #:force? force? |
> > |  | #:use-cache? use-cache? |
> > |  | #:ignore-checksums? ignore-checksums? |
> > |  | #:strict-doc-conflicts? strict-doc-conflicts? |
> > |  | #:quiet? quiet? |
> > |  | #:from-command-line? from-command-line? |
> > |  | #:strip strip |
> > |  | #:force-strip? force-strip? |
> > |  | #:dry-run? dry-run?]) |
> | → |  |
> (or/c 'skip
> #f
> (listof (or/c path-string?
> (non-empty-listof path-string?))))
> from-version : string?
> | dep-behavior |  | : |  | (or/c #f 'fail 'force 'search-ask 'search-auto)
> |  |  | = |  | #f
> force? : boolean? = #f
> use-cache? : boolean? = #t
> ignore-checksums? : boolean? = #f
> strict-doc-conflicts? : boolean? = #f
> quiet? : boolean? = #f
> from-command-line? : boolean? = #f
> strip : (or/c #f 'source 'binary 'binary-lib) = #f
> force-strip? : boolean? = #f
> dry-run? : boolean? = #f

Implements pkg-migrate-command. The result is the same as for pkg-install.

If from-command-line? is true, error messages may suggest specific command-line flags for raco pkg migrate.

The package lock must be held; see with-pkg-lock.

Changed in version 6.4.0.14 of package base: Added the #:dry-run argument.

> procedure (pkg-migrate-available-versions) → (listof string?)

Returns a list of versions that are suitable as arguments to pkg-migrate.

Added in version 8.11.1.7 of package base.

> > procedure
> > (pkg-catalog-show |  | names |  |  |  |
> > | [ | #:all? all? |  |  |  |
> > |  | #:only-names? only-names? |  |  |  |
> > |  | #:modules? modules?]) |  | → |  | void?
> names : (listof string?)
> all? : boolean? = #f
> only-names? : boolean? = #f
> modules? : boolean? = #f

Implements pkg-catalog-show-command. If all? is true, then names should be empty.

The current-pkg-lookup-version parameter determines the version included in the catalog query.

Changed in version 6.0.1.7 of package base: Use current-pkg-lookup-version instead of current-pkg-scope-version.

> > procedure
> > (pkg-catalog-copy |  | sources |
> > |  | dest |
> > | [ | #:from-config? from-config? |
> > |  | #:merge? merge? |
> > |  | #:force? force? |
> > |  | #:override? override? |
> > |  | #:relative-sources? relative-sources?]) |
> → void?
> sources : (listof path-string?)
> dest : path-string?
> from-config? : boolean? = #f
> merge? : boolean? = #f
> force? : boolean? = #f
> override? : boolean? = #f
> relative-sources? : boolean? = #f

Implements pkg-catalog-copy-command.

The current-pkg-lookup-version parameter determines the version for extracting existing catalog information.

Changed in version 6.0.1.7 of package base: Use current-pkg-lookup-version instead of current-pkg-scope-version.

> > procedure
> > (pkg-catalog-archive |
> > |  | dest-dir |
> > |  | sources |
> > | [ | #:from-config? from-config? |
> > |  | #:state-catalog state-catalog |
> > |  | #:relative-sources? relative-sources? |
> > |  | #:include includes |
> > |  | #:include-deps? include-deps? |
> > |  | #:include-deps-sys+subtype include-deps-sys+subtype |
> > |  | #:exclude excludes |
> > |  | #:fast-file-copy? fast-file-copy? |
> > |  | #:quiet? quiet? |
> > |  | #:package-exn-handler package-exn-handler]) |
> → void?
> dest-dir : path-string?
> sources : (listof path-string?)
> from-config? : boolean? = #f
> state-catalog : (or/c #f path-string?) = #f
> relative-sources? : boolean? = #f
> includes : (or/c #f (listof string?)) = #f
> include-deps? : boolean? = #f
> | include-deps-sys+subtype |  | : |  |
> (or/c #f (cons/c symbol?
> path-for-some-system?))
> |  |  | = |  | #f
> excludes : (listof string?) = '()
> fast-file-copy? : boolean? = #f
> quiet? : boolean? = #f
> | package-exn-handler |  | : |  | (string? exn:fail? . -> . any)
> |  |  | = |  | (lambda (pkg-name exn) (raise exn))

Implements pkg-catalog-archive-command.

The package-exn-handler argument handles any exception that is raised while trying to archive an individual package; the first argument is the package name, and the second is the exception. The default re-raises the exception, which aborts the archiving process, while a function that logs the exception message and returns would allow archiving to continue for other packages.

The current-pkg-lookup-version parameter determines the version for extracting existing catalog information.

Added in version 6.0.1.7 of package base.
Changed in version 6.0.1.13: Added the #:package-exn-handler argument.
Changed in version 7.7.0.1: Added the #:include, #:include-deps?, #:include-deps-platform, #:exclude, and #:fast-file-copy? arguments.

> > procedure
> > (pkg-archive-pkgs |  | dest-dir |
> > |  | pkgs |
> > | [ | #:include-deps? include-deps? |
> > |  | #:exclude exclude |
> > |  | #:relative-sources? relative-sources? |
> > |  | #:quiet? quiet? |
> > |  | #:package-exn-handler package-exn-handler]) |
> → void?
> dest-dir : path-string?
> pkgs : (listof path-string?)
> include-deps? : boolean? = #f
> exclude : (listof string?) = null
> relative-sources? : boolean? = #f
> quiet? : boolean? = #f
> | package-exn-handler |  | : |  | (string? exn:fail? . -> . any)
> |  |  | = |  | (lambda (pkg-name exn) (raise exn))

Implements pkg-archive-command.

The package-exn-handler argument handles any exception that is raised while trying to archive an individual package; the first argument is the package name, and the second is the exception. The default re-raises the exception, which aborts the archiving process, while a function that logs the exception message and returns would allow archiving to continue for other packages.

Added in version 6.1.0.8 of package base.

> > procedure
> > (pkg-empty-trash | [ | #:list? show-list? |  |  |  |
> > |  | #:quiet? quiet?]) |  | → |  | void?
> show-list? : boolean? = #f
> quiet? : boolean? = #t

Implements pkg-empty-trash.

Added in version 6.1.1.6 of package base.

> > procedure
> > (pkg-catalog-update-local |
> > | [ | #:catalogs catalogs |
> > |  | #:catalog-file catalog-file |
> > |  | #:quiet? quiet? |
> > |  | #:set-catalogs? set-catalogs? |
> > |  | #:consult-packages? consult-packages?]) |
> → void?
> catalogs : (listof string?) = (pkg-config-catalogs)
> catalog-file : path-string? = (current-pkg-catalog-file)
> quiet? : boolean? = #f
> set-catalogs? : boolean? = #t
> consult-packages? : boolean? = #f

Consults the package catalogs specified by catalogs (in the same way as pkg-catalog-copy) and the user’s configured package servers (if consult-packages? is true) to populate the database catalog-file with information about available packages and the modules that they implement.

The local catalog catalog-file records the set of source catalogs, including catalogs, from which its information is drawn. If set-catalogs? is true (which is the default), then catalogs is recorded as the set of sources, and information from any other catalog is discarded. If set-catalogs? is #f, then catalogs must be a subset of the source catalogs already recorded in catalog-file.

Changed in version 6.0.1.6 of package base: Added #:catalogs and #:set-catalogs? arguments.

> > procedure
> > (pkg-catalog-suggestions-for-module |
> > |  | module-path |
> > | [ | #:catalog-file catalog-file]) |
> → (listof string?)
> module-path : module-path?
> catalog-file : path-string? = ....

Consults catalog-file and returns a list of available packages that provide the module specified by module-path.

The default catalog-file is (current-pkg-catalog-file) if that file exists, otherwise a file in the racket installation is tried.

> procedure (get-all-pkg-scopes)
> → (listof (or/c 'installation 'user path?))

Obtains a list of all the currently-available package scopes.

Added in version 6.1.0.5 of package base.

> procedure (get-all-pkg-names-from-catalogs) → (listof string?)

Consults package catalogs to obtain a list of available package names.

> procedure (get-all-pkg-details-from-catalogs)
> → (hash/c string? (hash/c symbol? any/c))

Consults package catalogs to obtain a hash table of available package names mapped to details about the package. Details for a particular package are provided by a hash table that maps symbols such as 'source, 'checksum, and 'author.

> procedure (get-pkg-details-from-catalogs name)
> → (or/c #f (hash/c symbol? any/c))
> name : string?

Consults package catalogs to obtain information for a single package name, returning #f if the package name has no resolution. Details for the package are provided in the same form as from get-all-pkg-details-from-catalogs.

> > procedure
> > (pkg-single-collection |  | dir |
> > | [ | #:name name |
> > |  | #:namespace namespace]) |
> → (or/c #f string?)
> dir : path-string?
> name : string? = (elem "... from "(racket dir)" ...")
> namespace : namespace? = (make-base-namespapce)

Returns a string for a collection name if dir represents a single-collection package, or returns #f if dir represents a multi-collection package.

For some single-collection packages, the package’s single collection is the package name; if the package name is different from the directory name, supply name.

Determining a single-collection package’s collection name may require loading an "info.rkt" file, in which case namespace is passed on to get-info/full.

> > procedure
> > (get-pkg-content |  | desc |
> > | [ | #:extract-info extract-proc |
> > |  | #:namespace namespace |
> > |  | #:use-cache? use-cache? |
> > |  | #:quiet? quiet?]) |
> | → |  |
> (or/c #f string?)
> (listof module-path?)
> any/c
> desc : pkg-desc?
> | extract-proc |  | : |  |
> ((or/c #f
> ((symbol?) ((-> any)) . ->* . any))
> . -> . any)
> |  |  | = |  | (lambda (get-pkg-info) ...)
> namespace : namespace? = (make-base-namespace)
> use-cache? : boolean? = #f
> quiet? : boolean? = #t

Gets information about the content of the package specified by desc. The information is determined inspecting the package—resolving a package name, downloading, and unpacking into a temporary directory as necessary.

The results are as follows:

- The checksum, if any, for the downloaded package.

- A list of module paths that are provided by the package. Each module path is normalized in the sense of collapse-module-path.

- Information extracted from the package’s metadata. By default, this information is the package’s dependencies, but in general it is the result of extract-proc, which receives an information-getting function (or #f) as returned by get-info.

The namespace argument is effectively passed along to get-info/full and/or pkg-stage for reading package and collection "info.rkt" files.

The use-cache? and quiet? arguments are effectively passed to pkg-stage to control the use of a download cache and status reporting.

Changed in version 6.1.1.2 of package base: Added the #:use-cache? and #:quiet? arguments.

> > procedure
> > (extract-pkg-dependencies |  | info |
> > | [ | #:build-deps? build-deps? |
> > |  | #:filter? filter? |
> > |  | #:versions? versions?]) |
> → (listof (or/c string? (cons/c string? list?)))
> info : (or/c #f (symbol? (-> any/c) . -> . any/c))
> build-deps? : boolean? = #t
> filter? : boolean? = #f
> versions? : boolean? = #f

Returns packages dependencies reported by the info procedure (normally produced by get-info).

If build-deps? is true, then the result includes both run-time dependencies and build-time dependencies.

If filter? is true, then platform-specific dependencies are removed from the result list when they do not apply to the current platform, and other information is stripped so that the result list is always a list of either strings (when versions? is #f) or a two-element list containing a string and a version (when versions? is true).

If info is #f, the result is (list).

Changed in version 6.0.1.6 of package base: Added the #:versions? argument.

> > procedure
> > (pkg-directory->module-paths |  | dir |
> > |  | pkg-name |
> > | [ | #:namespace namespace]) |
> → (listof module-path?)
> dir : path-string?
> pkg-name : string
> namespace : namespace? = (make-base-namespace)

Returns a list of module paths (normalized in the sense of collapse-module-path) that are provided by the package represented by dir and named pkg-name.

> > procedure
> > (pkg-directory->additional-installs |
> > |  | dir |
> > |  | pkg-name |
> > | [ | #:namespace namespace |
> > |  | #:system-type sys-type |
> > |  | #:system-library-subpath sys-lib-subpath]) |
> → (listof (cons/c symbol? string?))
> dir : path-string?
> pkg-name : string
> namespace : namespace? = (make-base-namespace)
> sys-type : (or/c #f symbol?) = (system-type)
> | sys-lib-subpath |  | : |  | (or/c #f path-for-some-system?)
> |  |  | = |  | (system-library-subpath #f)

Returns a list of pairs for items that are installed by the package represented by dir and named pkg-name. Installed items can include documentation, executables, foreign libraries, other shared files, and man pages—all as specified by "info.rkt" files. The symbol for each item gives it a category, such as 'doc or 'exe, and the string part is a normalized name, such as the destination name for a document or a case-folded executable name without a file suffix.

The sys-type and sys-lib-subpath arguments are used in the same way as for matching-platform? to determine platform-specific installations as determined by install-platform definitions in "info.rkt" files.

Added in version 6.0.1.13 of package base.

> procedure (pkg-config-default-scope-scope)
> → (or/c #f 'user 'installation (and/c path? complete-path?))

Reports the narrowest scope that is at least as wide as current-pkg-scope and that has a configuration for 'default-scope. The result can be useful with pkg-config.

The package lock must be held; see with-pkg-lock. Note that pkg-config cannot necessarily call pkg-config-default-scope-scope itself, because it may be called with a lock that is wider than the narrowest relevant scope.

Added in version 7.7.0.9 of package base.

> > procedure
> > (call-in-pkg-timeout-sandbox |  | thunk |  |  |  |
> > | [ | #:make-exn make-exn]) |  | → |  | any
> thunk : (-> any)
> | make-exn |  | : |  | exn:fail
> |  |  | = |  | (string? continuation-mark-set? . -> . any/c)

Calls thunk in a thread and under a custodian that is shutdown when the thread terminates. If the thread does not terminate within the number of seconds indicated by current-pkg-network-timeout, the thread is forcibly terminated by shutting down its custodian.

The result of thunk is returned as the result of call-in-pkg-timeout-sandbox. If the thread raises an exception, the exception is re-raised by call-in-pkg-timeout-sandbox in the current thread.

The result of make-exn is raised if the thread terminates without returning a result or throwing an exception and if the timeout expires. If the thread terminates without returning a result or throwing an exception before the timeout, a “thread terminated” exception is raised.

Added in version 9.0.0.2 of package base.

top contents ← prev up next →