7.2 Package Management Functions
syntax
(with-pkg-lock body ...+)
syntax
(with-pkg-lock/read-only body ...+)
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 s) → void? s : string?
parameter
(current-pkg-lookup-version s) → void? s : string?
Added in version 6.0.1.7 of package base.
parameter
(current-pkg-error err) → void? err : procedure?
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?))
procedure
(pkg-config-catalogs) → (listof string?)
parameter
→ (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 max-files) → void? max-files : (or/c #f real?)
parameter
(current-pkg-download-cache-max-bytes max-bytes) → void? max-bytes : (or/c #f real?)
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?)
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?)
Added in version 6.3 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
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?))
procedure
(installed-pkg-names #:scope scope) → (listof string?)
scope :
(or/c #f 'installation 'user (and/c path? complete-path?))
procedure
(installed-pkg-table #:scope scope)
→ (hash/c string? pkg-info?)
scope :
(or/c #f 'installation 'user (and/c path? complete-path?))
procedure
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 'github 'clone) name : (or/c string? #f) checksum : (or/c string? #f) auto? : boolean? path : (or/c #f path-string?) = #f
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.
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
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?]) → void? set? : boolean? keys/vals : list? from-command-line? : boolean? = #f
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 'binary-lib 'built) dest-dir : (or/c (and/c path-string? complete-path?) #f) quiet? : boolean? = #f from-command-line? : boolean? = #f
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? 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
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
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—
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
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.
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.
procedure
name : path-string?
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
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
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-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
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
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))
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))
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
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
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? = ....
The default catalog-file is (current-pkg-catalog-file) if that file exists, otherwise a file in the racket installation is tried.
Added in version 6.1.0.5 of package base.
procedure
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)
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
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 : (symbol? (-> any/c) . -> . any/c) build-deps? : boolean? = #t filter? : boolean? = #f versions? : boolean? = #f
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)
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)
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.