►Package Management in Racket
▼7 Package APIs
On this page:
pkg
current-pkg-catalog-file
call-with-pkgs-transaction
get-catalogs
set-catalogs!
get-pkgs
set-pkgs!
set-pkg!
get-pkg-tags
set-pkg-tags!
get-pkg-ring
set-pkg-ring!
get-pkg-dependencies
set-pkg-dependencies!
get-pkg-modules
set-pkg-modules!
get-module-pkgs
get-pkgs-without-modules
8.15
  top  contents    up   

7.5 Package Catalog Database🔗ℹ

 (require pkg/db) package: base
The pkg/db library provides tools for storing and retrieving package catalog information in a local database.

The functions provided by pkg/db do not actually manage packages; they do not change or consult the local database of installed modules in any package scope. The functions provided by pkg/db simply reflect a local copy of the information that a package catalog and individual package might provide (but with no guarantee of being in sync with an actual package catalog or package).

The database is implemented as an SQLite database with its own locking, so no additional locks are needed for database access, but beware of concurrent database changes that could break your program logic.

struct

(struct pkg (name catalog author source checksum desc)
    #:extra-constructor-name make-pkg
    #:transparent)
  name : string?
  catalog : string?
  author : string?
  source : string?
  checksum : string?
  desc : string?
Represents a package implementation in the database. The name (package name) and catalog (package catalog, normally a URL) fields are always nonempty strings. Otherwise, unknown fields are represented by empty strings.

parameter

(current-pkg-catalog-file) → path-string?

(current-pkg-catalog-file file) → void?
  file : path-string?
A parameter that determines the file path used to hold the SQLite database. The default value is in the user’s add-on directory as determined by (find-system-path 'addon-dir) and within a subdirectory determined by get-installation-name.

procedure

(call-with-pkgs-transaction proc) → any

  proc : (-> any)
Calls proc so that multiple calls to other pkg/db functions are grouped as a database transaction, which avoids the overhead of making each individual call its own transaction.

Added in version 6.1.1.5 of package base.

procedure

(get-catalogs) → (listof string?)

procedure

(set-catalogs! catalogs) → void?

  catalogs : (listof string?)
Returns or sets the list of strings for all package catalog represented in the database. (Within the database, each package catalog gets its own identifying number.) The order of indices in the list represents a search order.

The set-catalogs! function removes information for any other package catalogs from the database.

procedure

(get-pkgs [#:name name #:catalog catalog]) → (listof pkg?)

  name : (or/c #f string?) = #f
  catalog : (or/c #f string?) = #f
Gets a list of package descriptions. If name or catalog is not #f (or if both are not #f), then the result includes only matching packages.

The result list is ordered by precedence of the package catalog.

procedure

(set-pkgs! catalog 
  pkgs 
  #:clear-other-checksums? clear-other-checksums?) 
 → void?
  catalog : string?
  pkgs : (listof (or/c string? pkg?))
  clear-other-checksums? : #t
Sets the list of all packages that are recognized by the package catalog catalog.

Information about any other package for catalog is removed from the database. If a string is provided for pkgs, it is treated as a package name; if additional information is already recorded in the database for the package name, then the additional information is preserved.

If clear-other-checksums? is true, then for each element of pkgs that has a given checksum other than "", any information in the database specific to another checksum (such as a list of module paths) is removed from the database.

procedure

(set-pkg! name 
  catalog 
  author 
  source 
  checksum 
  desc 
  #:clear-other-checksums? clear-other-checksums?) 
 → void?
  name : string?
  catalog : string?
  author : string?
  source : string?
  checksum : string?
  desc : string?
  clear-other-checksums? : (not (equal? checksum ""))
Sets the information for a specific package name as recognized by the package catalog catalog.

If clear-other-checksums? is true, then information (such as a list of module paths) is removed from the database when it is specific to a checksum other than checksum.

procedure

(get-pkg-tags name catalog) → (listof string?)

  name : string?
  catalog : string?

procedure

(set-pkg-tags! name catalog module-paths) → void?

  name : string?
  catalog : string?
  module-paths : (listof string?)
Gets or sets a list of tags for the package name as recognized by the package catalog catalog.

procedure

(get-pkg-ring name catalog)

 → (or/c #f exact-nonnegative-integer?)
  name : string?
  catalog : string?

procedure

(set-pkg-ring! name catalog ring) → void?

  name : string?
  catalog : string?
  ring : (or/c #f exact-nonnegative-integer?)
Gets or sets a ring number for the package name as recognized by the package catalog catalog.

The PLT-supported package catalog reports a curated ring number to reflect advice on package preference and conflicts, where the set of ring-0 and ring-1 packages are expected to have no conflicts (that is, no multiply defined modules, document names, etc.). The raco pkg tool does not pay attention to a package’s ring number, but other uses of a catalog may consult ring numbers.

Added in version 6.10.0.3 of package base.

procedure

(get-pkg-dependencies name catalog checksum) → (listof list?)

  name : string?
  catalog : string?
  checksum : string?

procedure

(set-pkg-dependencies! name    
  catalog    
  checksum    
  dependencies) → void?
  name : string?
  catalog : string?
  checksum : string?
  dependencies : (listof any/c)
Gets or sets a list of dependencies for the package name as recognized by the package catalog catalog and for a specific checksum.

The list of dependencies must have the shape described for a deps "info.rkt" field as described in Package Metadata. The result from get-pkg-dependencies is normalized: each dependency is represented by a list, a version in a dependency is always preceded by '#:version, and if both version and platform specification are included, '#:version appears before '#:platform.

procedure

(get-pkg-modules name catalog checksum) → (listof module-path?)

  name : string?
  catalog : string?
  checksum : string?

procedure

(set-pkg-modules! name    
  catalog    
  checksum    
  module-paths) → void?
  name : string?
  catalog : string?
  checksum : string?
  module-paths : (listof module-path?)
Gets or sets a list of module paths that are provided for the package name as recognized by the package catalog catalog and for a specific checksum. The module paths should be normalized in the sense of collapse-module-path.

procedure

(get-module-pkgs module-path) → (listof pkg?)

  module-path : module-path?
Reports a list of packages that implement the given module-path, which should be normalized in the sense of collapse-module-path.

procedure

(get-pkgs-without-modules [#:catalog catalog]) → (listof pkg?)

  catalog : (or/c #f string?) = #f
Returns a list of packages (optionally constrained to catalog) for which the database has no modules recorded.

Each resulting pkg has its name, catalog, and checksum field set, but other fields may be "".

  top  contents    up