247 lines
8.6KB

  1. .. highlight:: yaml
  2. Library and Package Dependencies
  3. ################################
  4. ``dds`` considers that all libraries belong to a single *package*, but a single
  5. package may contain one or more *libraries*. For this reason, and to better
  6. interoperate with other build and packaging tools, we consider the issues of
  7. package dependencies and library dependencies separately.
  8. .. _deps.pkg-deps:
  9. Package Dependencies
  10. ********************
  11. Consider that we are creating a package ``acme-gadgets@4.3.6``. We declare the
  12. name and version in the ``package.json5`` in the package root:
  13. .. code-block:: js
  14. {
  15. name: 'acme-gadgets',
  16. version: '4.3.6',
  17. namespace: 'acme',
  18. }
  19. .. note::
  20. The ``namespace`` field is required, but will be addressed in the
  21. :ref:`deps.lib-deps` section.
  22. Suppose that our package's libraries build upon the libraries in the
  23. ``acme-widgets`` package, and that we require version ``1.4.3`` or newer, but
  24. not as new as ``2.0.0``. Such a dependency can be declared with the ``depends``
  25. array:
  26. .. code-block:: js
  27. :emphasize-lines: 5-7
  28. {
  29. name: 'acme-gadgets',
  30. version: '4.3.6',
  31. namespace: 'acme',
  32. depends: [
  33. 'acme-widgets^1.4.3',
  34. ],
  35. }
  36. .. seealso:: :ref:`deps.ranges`.
  37. If we wish to declare additional dependencies, we simply declare them with
  38. additional ``depends`` items:
  39. .. code-block::
  40. :emphasize-lines: 7-8
  41. {
  42. name: 'acme-gadgets',
  43. version: '4.3.6',
  44. namespace: 'acme',
  45. depends: [
  46. 'acme-widgets^1.4.3',
  47. 'acme-gizmos~5.6.5',
  48. 'acme-utils^3.3.0',
  49. ],
  50. }
  51. When ``dds`` attempts to build a project, it will first build the dependency
  52. solution by iteratively scanning the dependencies of the containing project and
  53. all transitive dependencies.
  54. .. _deps.ranges:
  55. Compatible Range Specifiers
  56. ===========================
  57. When specifying a dependency on a package, one will want to specify which
  58. versions of the dependency are supported.
  59. .. note::
  60. Unlike other packaging tools, ``dds`` will find a solution with the
  61. *lowest* possible version that satisfies the given requirements for each
  62. package. This decision is not incidental: It's entirely intentional.
  63. Refer to: :ref:`deps.ranges.why-lowest`.
  64. ``dds`` compatible-version ranges are similar to the shorthand range specifiers
  65. supported by ``npm`` and ``npm``-like tools. There are four version range kinds
  66. available, listed in order of most-to-least restrictive:
  67. Exact: ``@1.2.3``
  68. Specifies an *exact* requirement. The dependency must match the named
  69. version *exactly* or it is considered incompatible.
  70. Minor: ``~1.2.3``
  71. Specifies a *minor* requirement. The version of the dependency should be
  72. *at least* the given version, but not as new or newer than the next minor
  73. revision. In this example, it represents the half-open version range
  74. ``[1.2.3, 1.3.0)``.
  75. Major: ``^1.2.3``
  76. Specifies a *major* requirement. The version must be *at least* the same
  77. given version, but not any newer than the the next major version. In the
  78. example, this is the half-open range ``[1.2.3, 2.0.0)``.
  79. .. note::
  80. This is the recommended default option to reach for, as it matches the
  81. intended behavior of `Semantic Versioning <https://semver.org>`_.
  82. At-least: ``+1.2.3``
  83. Specifies an *at least* requirement. The version must be *at least* the
  84. given version, but any newer version is acceptable.
  85. A dependency string is simply the name of the package with the range suffix appended.
  86. .. _deps.ranges.why-lowest:
  87. Why Pull the *Lowest* Matching Version?
  88. ---------------------------------------
  89. When resolving dependencies, ``dds`` will pull the version of the dependency
  90. that is the lowest version that satisfies the given range. In most cases,
  91. this will be the same version that is the base of the version range.
  92. Imagine a scenario where we *did* select the "latest-matching-version":
  93. Suppose we are developing a library ``Gadgets``, and we wish to make use of
  94. ``Widgets``. The latest version is ``1.5.2``, and they promise Semantic
  95. Versioning compatibility, so we select a dependency statement of
  96. ``Widgets^1.5.2``.
  97. Suppose a month passes, and ``Widgets@1.6.0`` is published. A few things
  98. happen:
  99. #. Our CI builds now switch from ``1.5.2`` to ``1.6.0`` *without any code
  100. changes*. Should be okay, right? I mean... it's still compatible, yeah?
  101. #. Bugs in ``Widgets@1.6.0`` will now appear in all CI builds, and won't be
  102. reproducible locally unless we re-pull our dependencies and obtain the
  103. new version of ``Widgets``. This requires that we be conscientious enough to
  104. realize what is actually going on.
  105. #. Even if ``Widgets@1.6.0`` introduces no new bugs, a developer re-pulling
  106. their dependencies will suddenly be developing against ``1.6.0``, and may
  107. not even realize it. In fact, this may continue for weeks or months until
  108. *everyone* is developing against ``1.6.0`` without realizing that they
  109. actually only require ``1.5.2`` in their dependency declarations.
  110. #. Code in our project is written that presupposes features or bugfixes added
  111. in ``1.6.0``, and thus makes the dependency declaration on ``Widgets^1.5.2``
  112. a *lie*.
  113. Pulling the lowest-matching-version has two *huge* benefits:
  114. #. No automatic CI upgrades. The code built today will produce the same result
  115. when built a year from now.
  116. #. Using a feature/fix beyond our minimum requirement becomes a compile error,
  117. and we catch these up-front rather than waiting for a downstream user
  118. discovering them for us.
  119. *Isn't this what lockfiles are for?*
  120. """"""""""""""""""""""""""""""""""""
  121. Somewhat. Lockfiles will prevent automatic upgrades, but they will do nothing
  122. to stop accidental reliance on new versions. There are other useful features
  123. of lockfiles, but preventing automatic upgrades can be a non-issue by simply
  124. using lowest-matching-version.
  125. *So, if this is the case, why use ranges at all?*
  126. """""""""""""""""""""""""""""""""""""""""""""""""
  127. In short: *Your* compatibility ranges are not for *you*. They are for *your
  128. users*.
  129. Suppose package ``A`` requires ``B^1.0.0``, and ``B`` requires ``C^1.2.0``.
  130. Now let us suppose that ``A`` wishes to use a newer feature of ``C``, and thus
  131. declares a dependency on ``C^1.3.0``. ``B`` and ``A`` have different
  132. compatibility ranges on ``C``, but this will work perfectly fine **as long as
  133. the compatible version ranges of A and B have some overlap**.
  134. That final qualification is the reason we use compatibility ranges: To support
  135. our downstream users to form dependency graphs that would otherwise form
  136. conflicts if we required *exact* versions for everything. In the above example,
  137. ``C@1.3.0`` will be selected for the build of ``A``.
  138. Now, if another downstream user wants to use ``A``, they will get ``C@1.3.0``.
  139. But they discover that they actually need a bugfix in ``C``, so they place
  140. their own requirement on ``C ^1.3.1``. Thus, they get ``C@1.3.1``, which still
  141. satisfies the compatibility ranges of ``A`` and ``B``. Everyone gets along
  142. just fine!
  143. .. _deps.lib-deps:
  144. Library Dependencies
  145. ********************
  146. In ``dds``, library interdependencies are tracked separately from the packages
  147. that contain them. A library must declare its intent to use another library
  148. in the ``library.json5`` at its library root. The minimal content of a
  149. ``library.json5`` is the ``name`` key:
  150. .. code-block:: js
  151. {
  152. name: 'gadgets'
  153. }
  154. To announce that a library wishes to *use* another library, use the aptly-named
  155. ``uses`` key:
  156. .. code-block:: js
  157. :emphasize-lines: 3-7
  158. {
  159. name: 'gadgets',
  160. uses: [
  161. 'acme/widgets',
  162. 'acme/gizmos',
  163. 'acme/utils',
  164. ],
  165. }
  166. Here is where the package's ``namespace`` key comes into play: A library's
  167. qualified name is specified by joining the ``namespace`` of the containing
  168. package with the ``name`` of the library within that package with a ``/``
  169. between them.
  170. It is the responsibility of package authors to document the ``namespace`` and
  171. ``name`` of the packages and libraries that they distribute.
  172. .. note::
  173. The ``namespace`` of a package is completely arbitrary, and need not relate
  174. to a C++ ``namespace``.
  175. .. note::
  176. The ``namespace`` need not be unique to a single package. For example, a
  177. single organization (Like Acme Inc.) can share a single ``namespace`` for
  178. many of their packages and libraries.
  179. However, it is essential that the ``<namespace>/<name>`` pair be
  180. universally unique, so choose wisely!
  181. Once the ``uses`` key appears in the ``library.dds`` file of a library, ``dds``
  182. will make available the headers for the library being used, and will
  183. transitively propagate that usage requirement to users of the library.