Source Distributions

Source Distributions

A source distribution (often abbreviated as “sdist”) is dds’s primary format for consuming and distributing packages. A source distribution, in essence, is a package root that contains only the files necessary for dds to reproduce the full build of all libraries in the package. The source distribution retains the directory structure of every source root of the original package, and thus retains the header structure thereof. In this way, the #include directives to use a library in a source distribution are identical to if the libraries therein were directly part of the consuming project.

Generating a Source Distribution

Generating a source distribution from a project directory is done with the sdist subcommand:

> dds pkg create

The above command can be executed within a package root, and the result will be a gzip’d tar archive that reproduces the package’s filesystem structure, but only maintaining the files that are necessary for dds to reproduce a build of that package.

The --project=<dir> flag can be provided to override the directory that dds will use as the package root. The default is the current working directory.

The --out=<path> flag can be provided to override the destination path of the archive. The path should not name an existing file or directory. By default, dds will generate a source distribution in the working directory with the pattern <name>@<version>.tar.gz. If the --replace flag is provided, then dds will overwrite the destination if it names an existing file or directory.

Importing a Source Distribution

Given a source distribution archive, one can import the package into the local package cache with a single command:

> dds pkg import some-package@1.2.3.tar.gz

You can also specify an HTTP or HTTPS URL to download a source distribution archive to import without downloading it separately:

> dds pkg import

Alternatively, if a directory correctly models a source distribution, then that directory can be imported in the same manner:

> dds pkg import /path/to/some/project

Importing a package will allow projects on the system to use the imported package as a dependency.


If one tries to import a package root into the cache that already contains a package with a matching identifier, dds will issue an error. This behavior can be overridden by providing --if-exists=replace on the command-line.