dds/docs/guide/source-dists.rst

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 :ref:`package root <pkgs.pkg-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
:ref:`source root <pkgs.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.


.. _sdist.import:

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.