6.2 Package Management Functions

6.0

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

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.

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
[ #:quiet? quiet?
#:from-command-line? from-command-line?]) → void?
  format : (or/c 'zip 'tgz 'plt 'MANIFEST)
  dir : path-string?
  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?
#: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
  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?
#: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
  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?
#:ignore-checksums? ignore-checksums?
#: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
  ignore-checksums? : 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-scope-version parameter determines the version included in the catalog query.

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

Implements pkg-catalog-copy-command.

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

procedure
(pkg-catalog-update-local
[ #:catalog-file catalog-file
#:quiet? quiet?
#:consult-packages? consult-packages?])
→ void?
  catalog-file : path-string? = (current-pkg-catalog-file)
  quiet? : boolean? = #f
  consult-packages? : boolean? = #f

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

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?])
→ (listof (or/c string? (cons/c string? list?)))
  info : (symbol? (-> any/c) . -> . any/c)
  build-deps? : boolean? = #f
  filter? : 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 strings.

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.

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

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