More docs

docs/guide/catalog.rst

@@ -0,0 +1,116 @@
+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:
+
+.. code-block:: text
+
+    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.dds``, then the dependencies
+    listed here must be identical to those listed in ``package.dds``, 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.dds`` and ``library.dds`` 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 ``<Namespapce>/<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:
+
+.. code-block:: jsonc
+
+  {
+    // 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.
+          "depends": {
+            // A mapping of package names to version ranges
+            "acme-widgets": "^1.4.1"
+          },
+          // 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"
+          }
+        }
+      }
+    }
+  }

docs/guide/index.rst

@@ -9,3 +9,5 @@ User Guide
     design
     packages
     toolchains
+    source-dists
+    catalog

docs/guide/packages.rst

@@ -164,6 +164,8 @@ Consumers only need to update the path of the *include search path* in a single
 location rather than modifying their source code.
 
 
+.. _pkgs.source-root:
+
 Source Roots in ``dds``
 =======================
 
@@ -237,6 +239,8 @@ In order for ``dds`` to be able to distribute and interlink libraries, a
 ``library.dds`` file must be present at the corresponding library root.
 
 
+.. _pkgs.pkg-root:
+
 Package Roots
 *************
 
@@ -257,4 +261,12 @@ Packages
 
 A package is defined by some *package root*, and contains some number of
 *libraries*. In order for a package to be exported by ``dds`` it must have a
-``package.dds`` file at its package root.
+``package.dds`` file at its package root.
+
+The primary distribution format of packages that is used by ``dds`` is the
+*source distribution*. Refer to the page :doc:`source-dists`.
+
+Packages are identified by a name/version pair, joined together by an ``@``
+symbol. The version of a package must be a semantic version string. Together,
+the ``name@version`` string forms the *package ID*, and it must be unique
+within a repository or package catalog.

docs/guide/repo.rst

@@ -0,0 +1,63 @@
+The Local Package Repository
+############################
+
+``dds`` maintains a local repository of packages that it has obtained at the
+request of a user. The packages themselves are stored as
+:doc:`source distributions <source-dists>` (``dds`` does not store the binaries
+that it builds within the repository).
+
+
+Reading Repository Contents
+***************************
+
+Most times, ``dds`` will manage the repository content silently, but it may be
+useful to see what ``dds`` is currently storing away.
+
+The content of the repostiory can be seen with the ``repo`` subcommand::
+
+> dds repo ls
+
+This will print the names of packages that ``dds`` has downloaded, as well as
+the versions of each.
+
+
+Obtaining Packages
+******************
+
+When ``dds`` builds a package, it will also build the dependency libraries of
+that package. In order for the dependency build to succeed, it must have a
+local copy of the source distribution of that dependency.
+
+When ``dds`` performs dependency resolution, it will consider both existing
+packages in the local repository, as well as packages that are available from
+the :doc:`package catalog <catalog>`. If the dependency solution requires any
+packages that are not in the local repository, it will use the information in
+the catalog to obtain a source distribution for each missing package. The
+source distributions will automatically be added to the local repository, and
+later dependency resolutions will not need to download that package again.
+
+
+.. _repo.export-local:
+
+Exporting a Project into the Repository
+***************************************
+
+``dds`` can only use packages that are available in the local repository. For
+packages that have a listing in the catalog, this is not a problem. If one is
+developing a local package and wants to allow it to be used in another local
+package, that can be done by exporting a source distribution from the package
+root::
+
+> dds sdist export
+
+This command will create a source distribution and put it into the local
+repository. The package available to other projects on the local system.
+
+.. note::
+    This doesn't export in "editable" mode: A snapshot of the package root
+    will be taken and exported to the local repository.
+
+If one tries to export a package root into a repository that already contains
+a package with a matching identifier, ``dds`` will issue an error. If the
+``--replace`` flag is specified with ``sdist export``, then ``dds`` will
+forcibly replace the package in the local repository with a new copy.

docs/guide/source-dists.rst

@@ -0,0 +1,43 @@
+Source Distributions
+####################
+
+A *source distribution* is ``dds``'s primary format for consuming and
+distributing packages. A source distribution, in essence, is a
+:ref:`package root <pkgs.pkg-root>` directory 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 sdist create
+
+The above command can be executed within any package root, and the result will
+be a new directory that reproduces the package's filesystem structure, but
+only maintaining the files that are necessary for ``dds`` to reproduce the
+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 working directory of
+the project.
+
+The ``--out=<path>`` flag can be provided to override the destination path of
+the resulting source distribution. The path should not name an existing file or
+directory. By default, ``dds`` will generate a source distribution in the
+working directory with the name ``project.dsd/`` (The output is itself a
+directory, not an archive). If the ``--replace`` flag is provided, then ``dds``
+will overwrite the destination if it names an existing file or directory.
+
+
+Exporting a Package to the Local Repository
+*******************************************
+
+.. seealso:: :ref:`repo.export-local`