.. highlight:: yaml Library and Package Dependencies ################################ ``dds`` considers that all libraries belong to a single *package*, but a single package may contain one or more *libraries*. For this reason, and to better interoperate with other build and packaging tools, we consider the issues of package dependencies and library dependencies separately. .. _deps.pkg-deps: Package Dependencies ******************** Consider that we are creating a package ``acme-gadgets@4.3.6``. We declare the name and version in the ``package.dds`` in the package root: .. code-block:: Name: acme-gadgets Version: 4.3.6 Namespace: acme .. note:: The ``Namespace`` field is required, but will be addressed in the :ref:`deps.lib-deps` section. 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: .. code-block:: :emphasize-lines: 5 Name: acme-gadgets Version: 4.3.6 Namespace: acme 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 .. code-block:: :emphasize-lines: 5-7 Name: acme-gadgets Version: 4.3.6 Namespace: acme Depends: acme-widgets ^1.4.3 Depends: acme-gizmos ~5.6.5 Depends: acme-utils ^3.3.0 When ``dds`` attempts to build a project, it will first build the dependency solution by iteratively scanning the dependencies of the containing project and all transitive dependencies. .. _deps.ranges: Compatible Range Specifiers =========================== When specifying a dependency on a package, one will want to specify which versions of the dependency are supported. .. note:: Unlike other packaging tools, ``dds`` will find a solution with the *lowest* possible version that satisfies the given requirements for each package. This decision is not incidental: It's entirely intentional. Refer to: :ref:`deps.ranges.why-lowest`. ``dds`` compatible-version ranges are similar to the shorthand range specifiers 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`` Specifies an *exact* requirement. The dependency must match the named version *exactly* or it is considered incompatible. Minor: ``~1.2.3`` Specifies a *minor* requirement. The version of the dependency should be *at least* the given version, but not as new or newer than the next minor revision. In this example, it represents the half-open version range ``[1.2.3, 1.3.0)``. Major: ``^1.2.3`` Specifies a *major* requirement. The version must be *at least* the same given version, but not any newer than the the next major version. In the example, this is the half-open range ``[1.2.3, 2.0.0)``. .. note:: This is the recommended default option to reach for, as it matches the intended behavior of `Semantic Versioning `_. 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. .. _deps.ranges.why-lowest: Why Pull the *Lowest* Matching Version? --------------------------------------- When resolving dependencies, ``dds`` will pull the version of the dependency that is the lowest version that satisfies the given range. In most cases, this will be the same version that is the base of the version range. 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``. Suppose a month passes, and ``Widgets@1.6.0`` is published. A few things happen: #. Our CI builds now switch from ``1.5.2`` to ``1.6.0`` *without any code changes*. Should be okay, right? I mean... it's still compatible, yeah? #. Bugs in ``Widgets@1.6.0`` will now appear in all CI builds, and won't be reproducible locally unless we re-pull our dependencies and obtain the new version of ``Widgets``. This requires that we be conscientious enough to realize what is actually going on. #. Even if ``Widgets@1.6.0`` introduces no new bugs, a developer re-pulling their dependencies will suddenly be developing against ``1.6.0``, and may not even realize it. In fact, this may continue for weeks or months until *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`` a *lie*. Pulling the lowest-matching-version has two *huge* benefits: #. No automatic CI upgrades. The code built today will produce the same result when built a year from now. #. Using a feature/fix beyond our minimum requirement becomes a compile error, and we catch these up-front rather than waiting for a downstream user discovering them for us. *Isn't this what lockfiles are for?* """""""""""""""""""""""""""""""""""" Somewhat. Lockfiles will prevent automatic upgrades, but they will do nothing to stop accidental reliance on new versions. There are other useful features of lockfiles, but preventing automatic upgrades can be a non-issue by simply using lowest-matching-version. *So, if this is the case, why use ranges at all?* """"""""""""""""""""""""""""""""""""""""""""""""" 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``. 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 compatibility ranges on ``C``, but this will work perfectly fine **as long as the compatible version ranges of A and B have some overlap**. That final qualification is the reason we use compatibility ranges: To support our downstream users to form dependency graphs that would otherwise form conflicts if we required *exact* versions for everything. In the above example, ``C@1.3.0`` will be selected for the build of ``A``. Now, if another downstream user wants to use ``A``, they will get ``C@1.3.0``. But they discover that they actually need a bugfix in ``C``, so they place their own requirement on ``C ^1.3.1``. Thus, they get ``C@1.3.1``, which still satisfies the compatibility ranges of ``A`` and ``B``. Everyone gets along just fine! .. _deps.lib-deps: Library Dependencies ******************** In ``dds``, library interdependencies are tracked separately from the packages that contain them. A library must declare its intent to use another library in the ``library.dds`` at its library root. The minimal content of a ``library.dds`` is the ``Name`` key: .. code-block:: Name: gadgets To announce that a library wishes to *use* another library, use the aptly-named ``Uses`` key: .. code-block:: :emphasize-lines: 3-5 Name: gadgets Uses: acme/widgets Uses: acme/gizmos Uses: acme/utils Here is where the package's ``Namespace`` key comes into play: A library's qualified name is specified by joining the ``Namespace`` of the containing package with the ``Name`` of the library within that package with a ``/`` between them. It is the responsibility of package authors to document the ``Namespace`` and ``Name`` of the packages and libraries that they distribute. .. note:: The ``Namespace`` of a package is completely arbitrary, and need not relate to a C++ ``namespace``. .. note:: The ``Namespace`` need not be unique to a single package. For example, a single organization (Like Acme Inc.) can share a single ``Namespace`` for many of their packages and libraries. However, it is essential that the ``/`` pair be universally unique, so choose wisely! Once the ``Uses`` key appears in the ``library.dds`` file of a library, ``dds`` will make available the headers for the library being used, and will transitively propagate that usage requirement to users of the library.