The Package Catalog

dds stores a catalog of available packages, along with their dependency statements and information about how a source distribution thereof may be maintained.

Viewing Catalog Contents

The default catalog database is stored in a user-local location, and the package IDs available can be listed with dds catalog list. This will only list the IDs of the packages, but none of the additional metadata about them.

Adding Packages to the Catalog

There are two primary ways to add entries to the package catalog.

Adding Individual Packages

A single package can be added to the catalog with the dds catalog add command:

dds catalog add <package-id>
    [--depends <requirement> [--depends <requirement> [...]]]
    [--git-url <url> --git-ref <ref>]
    [--auto-lib <namespace>/<name>]

The <package-id> positional arguments is the name@version package ID that will be added to the catalog. The following options are supported:

--depends <requirement>

This argument, which can be specified multiple times to represent multiple dependencies, sets the dependencies of the package within the catalog. If the obtained package root contains a package.json5, then the dependencies listed here must be identical to those listed in package.json5, or dependency resolution may yield unexpected results.

--git-url <url>

Specify a Git URL to clone from to obtain the package. The root of the cloned repository must be a package root, but does not necessarily need to have the package.json5 and library.json5 files if relying on the --auto-lib parameter.

--git-ref must be passed with --git-url.

--git-ref <ref>

Specify a Git ref to clone. The remote must support cloning by the ref that is specified here. Most usually this should be a Git tag.

dds will perform a shallow clone of the package at the specified Git reference.

--auto-lib

This option must be provided if the upstream does not already contain the dds files that are necessary to export the library information. This can only be specified for packages that contain a single library root at the package root.

The form of the argument is that of <namespace>/<name>, where namespace and name are the usage requirement keys that should be generated for the library.

Bulk Imports via JSON

The dds catalog import supports a --json flag that specifies a JSON file from which catalog entries will be generated.

Note

The --json flag can be passed more than once to import multiple JSON files at once.

The JSON file has the following structure:

{
  // Import version spec.
  "version": 1,
  // Packages section
  "packages": {
    // Subkeys are package names
    "acme-gadgets": {
      // Keys within the package names are the versions that are
      // available for each package.
      "0.4.2": {
        // `depends` is an object of dependencies for this
        // particular version of the package. (Optional)
        "depends": {
          // A mapping of package names to version ranges
          "acme-widgets": "^1.4.1"
        },
        // `description` is an attribute to give a string to describe
        // the package. (Optional)
        "description": "A collection of useful gadgets.",
        // Specify the Git remote information
        "git": {
          // `url` and `ref` are required.
          "url": "http://example.com/git/repo/acme-gadgets.git",
          "ref": "v0.4.2-stable",
          // The `auto-lib` is optional, to specify an automatic
          // library name/namespace pair to generate for the
          // root library
          "auto-lib": "Acme/Gadgets"
        }
      }
    }
  }
}