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 https://example.org/path/to/sdist.tar.gz
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.
Note
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.