4 years ago · 8557fc2ab3
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,7 +9,7 @@ author = 'vector-of-bool'
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
 release = '0.1.0-alpha.3'
 release = '0.1.0-alpha.4'

 # -- General configuration ---------------------------------------------------
 extensions = []
@@ -21,7 +21,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 pygments_style = None

 # -- Options for HTML output -------------------------------------------------
 html_theme = 'pyramid'
 html_theme = 'nature'
 html_theme_options = {}
 html_static_path = []
 html_sidebars = {}
--- a/docs/dev/building.rst
+++ b/docs/dev/building.rst
@@ -62,9 +62,9 @@ interest:
 The ``ci.py`` script performs the following actions, in order:

 #. Prepare the build output directory
 #. Bootstrap the prior version of ``dds`` that will build the current version.
 #. Prepare the prior version of ``dds`` that will build the current version.
 #. Import the embedded ``catalog.json`` into a catalog database stored within
   ``_build/``. This will be used to resolve the third-party packages that
   ``_prebuilt/``. This will be used to resolve the third-party packages that
   ``dds`` itself uses.
 #. Invoke the build of ``dds`` using the prebuilt ``dds`` from the prior
   bootstrap phase. If ``--build-only`` was specified, the CI script stops
@@ -173,8 +173,8 @@ it:
 .. code-block:: bash

    $ _prebuilt/dds build -t [toolchain] \
        --catalog _build/catalog.db \
        --repo-dir _build/ci-repo
        --catalog _prebuilt/catalog.db \
        --repo-dir _prebuilt/ci-repo

 The ``--catalog`` and ``--repo-dir`` arguments are not strictly necessary, but
 help to isolate the ``dds`` dev environment from the user-local ``dds``
--- a/docs/err/invalid-config-key.rst
+++ b/docs/err/invalid-config-key.rst
@@ -1,17 +0,0 @@
 Error: Invalid configuration key
 ################################

 ``dds`` uses a very simple key-value-pair plaintext configuration file format.
 Receiving this error indicates that one of the keys in a configuration file is
 invalid.

 ..  .
  TODO: Create reference documentation for packages and libs, and include
  those links in the seealso below.

 .. seealso::

    - For defining a toolchain file, see :doc:`/guide/toolchains` and
      :ref:`toolchains.opt-ref`
    - For package and library configuration, see the :doc:`/guide/packages`
      page.
--- a/docs/guide/catalog.rst
+++ b/docs/guide/catalog.rst
@@ -19,64 +19,7 @@ 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.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.


 .. _catalog.adding.json:

 Bulk Imports via JSON
 =====================

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

 .. note::
@@ -89,35 +32,34 @@ The JSON file has the following structure:

  {
    // Import version spec.
    "version": 1,
    version: 1,
    // Packages section
    "packages": {
    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
          // `depends` is an array of dependency statements for this
          // particular version of the package. (Optional)
          "depends": {
            // A mapping of package names to version ranges
            "acme-widgets": "^1.4.1"
          },
          depends: [
            "acme-widgets^1.4.1"
          ],
          // `description` is an attribute to give a string to describe
          // the package. (Optional)
          "description": "A collection of useful gadgets.",
          description: "A collection of useful gadgets.",
          // Specify the Git remote information
          "git": {
          git: {
            // `url` and `ref` are required.
            "url": "http://example.com/git/repo/acme-gadgets.git",
            "ref": "v0.4.2-stable",
            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",
            // List of filesystem transformations to apply to the repository
            // (optional)
            "transform": [
            transform: [
              // ... (see below) ...
            ]
          }
@@ -132,7 +74,22 @@ The JSON file has the following structure:
 Filesystem Transformations
 **************************

 A catalog entry can have a set of filesystem transformations attached to its remote information (e.g. the ``git`` property). When ``dds`` is obtaining a copy of the code for the package, it will apply the associated transformations to the filesystem based in the directory of the downloaded/cloned directory. In this was, ``dds`` can effectively "patch" the filesystem structure of a project arbitrarily. This allows many software projects to be imported into ``dds`` without needing to patch/fork the original project to support the required filesystem structure.
 .. note::
  Filesystem transformations is a transitional feature that is likely to be
  removed in a future release, and replaced with a more robust system when
  ``dds`` has a better way to download packages. Its aim is to allow ``dds``
  projects to use existing libraries that might not meet the layout
  requirements that ``dds`` imposes, but can otherwise be consumed by ``dds``
  with a few tweaks.

 A catalog entry can have a set of filesystem transformations attached to its
 remote information (e.g. the ``git`` property). When ``dds`` is obtaining a
 copy of the code for the package, it will apply the associated transformations
 to the filesystem based in the directory of the downloaded/cloned directory. In
 this way, ``dds`` can effectively "patch" the filesystem structure of a project
 arbitrarily. This allows many software projects to be imported into ``dds``
 without needing to patch/fork the original project to support the required
 filesystem structure.

 .. important::
  While ``dds`` allows you to patch directories downloaded via the catalog, a
@@ -140,16 +97,11 @@ A catalog entry can have a set of filesystem transformations attached to its rem

  The intention of filesystem transformations is to act as a "bridge" that will allow ``dds`` projects to more easily utilize existing libraries.

 .. note::
  Filesystem transformations can only be added to catalog entries using the
  :ref:`JSON import method <catalog.adding.json>`. It is not available in the
  command-line import method.


 Available Transformations
 =========================

 At time of writing, there are four main transformations available to catalog entries:
 At time of writing, there are five transformations available to catalog entries:

 ``copy`` and ``move``
  Copies or moves a set of files/directories from one location to another. Allows the following options:
@@ -176,15 +128,37 @@ At time of writing, there are four main transformations available to catalog ent
  - ``path`` - The path of the file to write. **Required**
  - ``content`` - A string that will be written to the file. **Required**

  If the file exists and is not a directory, the file will be replaced. If the path names an existing directory, an error will be generated.
  If the file exists and is not a directory, the file will be replaced. If the
  path names an existing directory, an error will be generated.

 ``edit``
  Modifies the contents of the files in the package.

  - ``path`` - Path to the file to edit. **Required**
  - ``edits`` - An array of edit objects, applied in order, with the following
    keys:

    - ``kind`` - One of ``insert`` or ``delete`` to insert/delete lines,
      respectively. **Required**
    - ``line`` - The line at which to perform the insert/delete. The first line
      of the file is line one, *not* line zero. **Required**
    - ``content`` - For ``insert``, the string content to insert into the file.
      A newline will be appended after the content has been inserted.

 Transformations are added as a JSON array to the JSON object that specifies the remote information for the package. Each element of the array is an object, with one or more of the four keys listed above. If an object features more than one of the above keys, they are applied in the same order as they have been listed.
 Transformations are added as a JSON array to the JSON object that specifies
 the remote information for the package. Each element of the array is an
 object, with one or more of the keys listed above. If an object features more
 than one of the above keys, they are applied in the same order as they have
 been listed.


 Example: Crypto++
 =================

 The following catalog entry will build and import `Crypto++`_ for use by a ``dds`` project. This uses the unmodified Crypto++ repository, which ``dds`` doesn't know how to build immediately. With some simple moving of files, we end up with something ``dds`` can build directly:
 The following catalog entry will build and import `Crypto++`_ for use by a
 ``dds`` project. This uses the unmodified Crypto++ repository, which ``dds``
 doesn't know how to build immediately. With some simple moving of files, we
 end up with something ``dds`` can build directly:

 .. code-block:: javascript

@@ -224,7 +198,11 @@ The following catalog entry will build and import `Crypto++`_ for use by a ``dds
 Example: libsodium
 ==================

 For example, this catalog entry will build and import `libsodium`_ for use in a ``dds`` project. This uses the upstream libsodium repository, which does not meet the layout requirements needed by ``dds``. With a few simple transformations, we can allow ``dds`` to build and consume libsodium successfully:
 For example, this catalog entry will build and import `libsodium`_ for use in
 a ``dds`` project. This uses the upstream libsodium repository, which does not
 meet the layout requirements needed by ``dds``. With a few simple
 transformations, we can allow ``dds`` to build and consume libsodium
 successfully:

 .. code-block:: javascript

--- a/docs/guide/cmake.rst
+++ b/docs/guide/cmake.rst
@@ -11,7 +11,8 @@ package indices can be imported into other build systems that support the
 .. note::
    ``dds`` doesn't (yet) have a ready-made central repository of packages that
    can be downloaded. You'll need to populate the local package catalog
    appropriately.
    appropriately. The default catalog file contains a limited set of useful
    packages, but you may wish to add more for yourself.

    .. seealso:: Refer to :doc:`catalog` for information about remote packages.

@@ -39,8 +40,8 @@ an ``INDEX.lmi`` file that can be used to import the built results.
 Declaring Dependencies
 ======================

 ``dds build-deps`` accepts a list of dependencies as commnad line arguments,
 but it may be useful to specify those requirements in a file.
 ``dds build-deps`` accepts a list of dependency statements as commnad line
 arguments, but it may be useful to specify those requirements in a file.

 ``dds build-deps`` accepts a JSON5 file describing the dependencies of a
 project as well. This file is similar to a very stripped-down version of a
@@ -53,9 +54,9 @@ Here is a simple dependencies file that declares a single requirement:
    :caption: ``dependencies.json5``

    {
        depends: {
            'neo-sqlite3': '^0.2.0',
        }
        depends: [
            'neo-sqlite3^0.2.0',
        ]
    }


@@ -140,7 +141,7 @@ index that was generated by ``dds``: It will automatically ``import_packages()``
 any of the transitive dependencies required.


 Using Out Dependencies' Libraries
 Using Our Dependencies' Libraries
 =================================

 Like with ``dds``, CMake wants us to explicitly declare how our build targets
@@ -194,7 +195,7 @@ To start, pass the ``DDS`` argument to ``pmm()`` to use it::

    pmm(DDS)

 ..note::
 .. note::
    The ``_deps`` directory and ``INDEX.lmi`` file will be placed in the CMake
    build directory, out of the way of the rest of the project.

--- a/docs/guide/interdeps.rst
+++ b/docs/guide/interdeps.rst
@@ -20,7 +20,7 @@ name and version in the ``package.json5`` in the package root:
 .. code-block:: js

    {
        name: 'acme-widgets',
        name: 'acme-gadgets',
        version: '4.3.6',
        namespace: 'acme',
    }
@@ -31,8 +31,8 @@ name and version in the ``package.json5`` in the package root:

 Suppose that our package's libraries build upon the libraries in the
 ``acme-widgets`` package, and that we require version ``1.4.3`` or newer, but
 not as new as ``2.0.0``. Such a dependency can be declared with the ``Depends``
 key:
 not as new as ``2.0.0``. Such a dependency can be declared with the ``depends``
 array:

 .. code-block:: js
    :emphasize-lines: 5-7
@@ -41,15 +41,15 @@ key:
        name: 'acme-gadgets',
        version: '4.3.6',
        namespace: 'acme',
        depends: {
            'acme-widgets': '^1.4.3',
        },
        depends: [
            'acme-widgets^1.4.3',
        ],
    }

 .. seealso:: :ref:`deps.ranges`.

 If we wish to declare additional dependencies, we simply declare them with
 additional ``Depends`` keys
 additional ``depends`` items:

 .. code-block::
    :emphasize-lines: 7-8
@@ -58,11 +58,11 @@ additional ``Depends`` keys
        name: 'acme-gadgets',
        version: '4.3.6',
        namespace: 'acme',
        depends: {
            'acme-widgets': '^1.4.3',
            'acme-gizmos': '~5.6.5',
            'acme-utils': '^3.3.0',
        },
        depends: [
            'acme-widgets^1.4.3',
            'acme-gizmos~5.6.5',
            'acme-utils^3.3.0',
        ],
    }

 When ``dds`` attempts to build a project, it will first build the dependency
@@ -88,7 +88,7 @@ versions of the dependency are supported.
 supported by ``npm`` and ``npm``-like tools. There are five (and a half)
 version range formats available, listed in order of most-to-least restrictive:

 Exact: ``1.2.3`` and ``=1.2.3``
 Exact: ``@1.2.3``
    Specifies an *exact* requirement. The dependency must match the named
    version *exactly* or it is considered incompatible.

@@ -111,9 +111,7 @@ At-least: ``+1.2.3``
    Specifies an *at least* requirement. The version must be *at least* the
    given version, but any newer version is acceptable.

 Anything: ``*``
    An asterisk ``*`` represents than *any* version is acceptable. This is not
    recommended for most dependencies.
 A dependency string is simply the name of the package with the range suffix appended.


 .. _deps.ranges.why-lowest:
@@ -129,7 +127,8 @@ Imagine a scenario where we *did* select the "latest-matching-version":

 Suppose we are developing a library ``Gadgets``, and we wish to make use of
 ``Widgets``. The latest version is ``1.5.2``, and they promise Semantic
 Versioning compatibility, so we select a version range of ``^1.5.2``.
 Versioning compatibility, so we select a dependency statement of
 ``Widgets^1.5.2``.

 Suppose a month passes, and ``Widgets@1.6.0`` is published. A few things
 happen:
@@ -146,7 +145,7 @@ happen:
   *everyone* is developing against ``1.6.0`` without realizing that they
   actually only require ``1.5.2`` in their dependency declarations.
 #. Code in our project is written that presupposes features or bugfixes added
   in ``1.6.0``, and thus makes the dependency declaration on ``Widgets ^1.5.2``
   in ``1.6.0``, and thus makes the dependency declaration on ``Widgets^1.5.2``
   a *lie*.

 Pulling the lowest-matching-version has two *huge* benefits:
@@ -173,9 +172,9 @@ using lowest-matching-version.
 In short: *Your* compatibility ranges are not for *you*. They are for *your
 users*.

 Suppose package ``A`` requires ``B ^1.0.0``, and ``B`` requires ``C ^1.2.0``.
 Suppose package ``A`` requires ``B^1.0.0``, and ``B`` requires ``C^1.2.0``.
 Now let us suppose that ``A`` wishes to use a newer feature of ``C``, and thus
 declares a dependency on ``C ^1.3.0``. ``B`` and ``A`` have different
 declares a dependency on ``C^1.3.0``. ``B`` and ``A`` have different
 compatibility ranges on ``C``, but this will work perfectly fine **as long as
 the compatible version ranges of A and B have some overlap**.

--- a/docs/guide/packages.rst
+++ b/docs/guide/packages.rst
@@ -48,7 +48,8 @@ supported:
      * ``.cpp``, ``.c++``, ``.cc``, and ``.cxx``

    - * Not compiled
      * ``.H``, ``.H++``, ``.h``, ``.h++``, ``.hh``, ``.hpp``, ``.hxx``, and ``.inl``
      * ``.H``, ``.H++``, ``.h``, ``.h++``, ``.hh``, ``.hpp``, ``.hxx``,
        ``.ipp``, ``.inc``, and ``.inl``

 If a file's extension is not listed in the table above, ``dds`` will ignore it.

--- a/docs/guide/toolchains.rst
+++ b/docs/guide/toolchains.rst
@@ -94,7 +94,7 @@ The following pseudo-toolchains are also available:
 Providing a Default Toolchain File
 **********************************

 If you do not which to provide a new toolchain for every individual project,
 If you do not wish to provide a new toolchain for every individual project,
 and the built-in toolchains do not suit your needs, you can write a toolchain
 file to one of a few predefined paths, and ``dds`` will find and use it for the
 build. The following directories are searched, in order:
@@ -208,7 +208,7 @@ is equivalent to this one::

 Despite splitting strings as-if they were shell commands, ``dds`` does nothing
 else shell-like. It does not expand environment variables, nor does it expand
 globs.
 globs and wildcards.


 ``compiler_id``
@@ -271,18 +271,16 @@ Valid ``cxx_version`` values are:
 ``warning_flags``
 -----------------

 Override the compiler flags that should be used to enable warnings. This option
 is stored separately from ``flags``, as these options may be enabled/disabled
 separately depending on how ``dds`` is invoked.
 Provide *additional* compiler flags that should be used to enable warnings. This option is stored separately from ``flags``, as these options may be enabled/disabled separately depending on how ``dds`` is invoked.

 .. note::
    If ``compiler_id`` is provided, a default value will be used that enables
    common warning levels.
    If ``compiler_id`` is provided, a default set of warning flags will be provided when warnings are enabled.

    If you need to tweak warnings further, use this option.
    Adding flags to this toolchain option will *append* flags to the basis warning flag list rather than overwrite them.

 On GNU-like compilers, the default flags are ``-Wall -Wextra -Wpedantic
 -Wconversion``. On MSVC the default flag is ``/W4``.
 .. seealso::

    Refer to :ref:`toolchains.opts.base_warning_flags` for more information.


 ``flags``, ``c_flags``, and ``cxx_flags``
@@ -468,9 +466,26 @@ standard output is an ANSI-capable terminal.
 On GNU and Clang this will be ``-fdiagnostics-color`` by default.


 ``obj_prefix``, ``obj_suffix``, ``archive_prefix``, ``archive_suffix``,
 ``exe_prefix``, and ``exe_suffix``
 ----------------------------------
 ``obj_prefix``, ``obj_suffix``, ``archive_prefix``, ``archive_suffix``, ``exe_prefix``, and ``exe_suffix``
 ----------------------------------------------------------------------------------------------------------

 Set the filename prefixes and suffixes for object files, library archive files,
 and executable files, respectively.


 .. _toolchains.opts.base_warning_flags:

 ``base_warning_flags``
 ----------------------

 When you compile your project and request warning flags, ``dds`` will
 concatenate the warning flags from this option with the flags provided by
 ``warning_flags``. This option is "advanced," because it provides a set of
 defaults based on the ``compiler_id``.

 On GNU-like compilers, the base warning flags are ``-Wall -Wextra -Wpedantic
 -Wconversion``. On MSVC the default flag is ``/W4``.

 For example, if you set ``warning_flags`` to ``"-Werror"`` on a GNU-like
 compiler, the resulting command line will contain ``-Wall -Wextra -Wpedantic
 -Wconversion -Werror``.
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,14 +20,6 @@ the :doc:`tut/index` page.
    dev/index
    err/index

 .. Hide the link to the error reference since we don't want it cluttering our
    main toc, but we want Sphinx to not consider it "unreferenced." We'll generate
    our own link

 .. seealso::
    For in-depth error and troubleshooting information see: :doc:`err/index`.


 Indices and tables
 ==================

--- a/docs/tut/hello-world.rst
+++ b/docs/tut/hello-world.rst
@@ -16,8 +16,7 @@ contents therein will be significant.
   The term *package root* is further described in the :doc:`/guide/packages` page.

 From here on, this created directory will simply be noted as ``<root>``. In
 the examples, this will refer to the directory package root directory we have
 created.
 the examples, this will refer to the package root directory we have created.


 Creating the First *Source Root*
@@ -96,7 +95,7 @@ For example, if you are using ``gcc``, you would run the command as::

 > dds build -t :gcc

 If all successful, ``dds`` will emit information about the compile and link
 If all is successful, ``dds`` will emit information about the compile and link
 process, and then exit without error.

 By default, build results will be placed in a subdirectory of the package root
--- a/package.jsonc
+++ b/package.jsonc
@@ -1,7 +1,7 @@
 {
    "$schema": "./res/package-schema.json",
    "name": "dds",
    "version": "0.1.0-alpha.3",
    "version": "0.1.0-alpha.4",
    "namespace": "dds",
    "depends": {
        "spdlog": "1.4.2",
--- a/src/dds/error/errors.cpp
+++ b/src/dds/error/errors.cpp
@@ -51,8 +51,6 @@ std::string error_url_suffix(dds::errc ec) noexcept {
        return "invalid-version-string.html#range";
    case errc::invalid_version_string:
        return "invalid-version-string.html";
    case errc::invalid_config_key:
        return "invalid-config-key.html";
    case errc::invalid_lib_filesystem:
    case errc::invalid_pkg_filesystem:
        return "invalid-pkg-filesystem.html";
@@ -203,8 +201,6 @@ information.
 specification. Refer to the documentation and https://semver.org/ for more
 information.
 )";
    case errc::invalid_config_key:
        return R"(The `key' in a `key: value' pair was not recognized.)";
    case errc::invalid_lib_filesystem:
    case errc::invalid_pkg_filesystem:
        return R"(
@@ -303,8 +299,6 @@ std::string_view dds::default_error_string(dds::errc ec) noexcept {
        return "Attempted to parse an invalid version range string." BUG_STRING_SUFFIX;
    case errc::invalid_version_string:
        return "Attempted to parse an invalid version string." BUG_STRING_SUFFIX;
    case errc::invalid_config_key:
        return "Found an invalid configuration key." BUG_STRING_SUFFIX;
    case errc::invalid_lib_filesystem:
    case errc::invalid_pkg_filesystem:
        return "The filesystem structure of the package/library is invalid." BUG_STRING_SUFFIX;
--- a/src/dds/error/errors.hpp
+++ b/src/dds/error/errors.hpp
@@ -36,7 +36,6 @@ enum class errc {
    invalid_version_string,
    invalid_pkg_id,
    invalid_pkg_name,
    invalid_config_key,
    unknown_test_driver,
    dependency_resolve_failure,
    dup_lib_name,