6.2 Package Management Functions

6.1

6.2 Package Management Functions

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.

procedure
(pkg-directory name) → (or/c path-string? #f)
name : string?

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

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?) → pkg-desc?
  source : string?
   type :
(or/c #f 'file 'dir 'link 'static-link
      'file-url 'dir-url 'github 'name)
  name : (or/c string? #f)
  checksum : (or/c string? #f)
  auto? : boolean?

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.

procedure
(pkg-stage desc
[ #:checksum checksum
#:in-place? in-place?
#:namespace namespace
#:strip strip
#:use-cache? use-cache?
#:quiet? quiet?]) →
string?
path?
(or/c #f string?)
boolean?
(listof 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) = #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 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?]) → void?
  set? : boolean?
  keys/vals : list?
  from-command-line? : boolean? = #f

Implements pkg-config-command.

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

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

procedure
(pkg-create format
dir
#:source source
#:mode mode
#:dest dest-dir
[ #: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 'built)
  dest-dir : (or/c (and/c path-string? complete-path?) #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.

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? boolean?
#:from-command-line? from-command-line?
#:strip strip
#:link-dirs? link-dirs?])
→
(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
  boolean? : quiet? = #f
  from-command-line? : boolean? = #f
  strip : (or/c #f 'source 'binary) = #f
  link-dirs? : 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.

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.

procedure
(pkg-update names
[ #: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?
#:quiet? boolean?
#:from-command-line? from-command-line?
#:strip strip
#:link-dirs? link-dirs?])
→
(or/c 'skip
      #f
      (listof (or/c path-string?
                    (non-empty-listof path-string?))))
  names : (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? : quiet? = #t
  boolean? : quiet? = #f
  from-command-line? : boolean? = #f
  strip : (or/c #f 'source 'binary) = #f
  link-dirs? : boolean? = #f

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

A string in names refers to an installed package that should be checked for updates. A pkg-desc in names indicates a package source that should replace the current 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.

procedure
(pkg-remove names
[ #:demote? demote?
#:auto? auto?
#:force? force?
#:quiet? boolean?
#:from-command-line? from-command-line?])
→
(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
  boolean? : quiet? = #f
  from-command-line? : 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, error messages may suggest specific command-line flags for raco pkg remove.

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

procedure
(pkg-show indent [#:directory show-dir?]) → void?
indent : string?
show-dir? : boolean? = #f

Implements pkg-show-command for a single package scope, printing to the current output port. See also installed-pkg-names and installed-pkg-table.

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

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? boolean?
#:from-command-line? from-command-line?
#:strip strip])
→
(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
  boolean? : quiet? = #f
  from-command-line? : boolean? = #f
  strip : (or/c #f 'source 'binary) = #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.

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?
#: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
  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.

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-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])
→
(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) ...)

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.

procedure
(extract-pkg-dependencies info
[ #:build-deps? build-deps?
#:filter? filter?
#:versions? versions?])
→ (listof (or/c string? (cons/c string? list?)))
  info : (symbol? (-> any/c) . -> . any/c)
  build-deps? : boolean? = #f
  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 true) or a two-element list containing a string and a version (when versions? is #f).

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?)
= (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.

top ← prev up next →

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

6.1	Functions for raco pkg
6.2	Package Management Functions
6.3	Package Paths and Database
6.4	Package Source Parsing
6.5	Package Catalog Database