125 lines
4.1KB

  1. How Do I Use Other Libraries as Dependencies?
  2. #############################################
  3. Of course, fundamental to any build system is the question of consuming
  4. dependencies. ``dds`` takes an approach that is both familiar and novel.
  5. The *Familiar*:
  6. Dependencies are listed in a project's package manifest file
  7. (``package.json5``, for ``dds``).
  8. A range of acceptable versions is provided in the package manifest, which
  9. tells ``dds`` and your consumers what versions of a particular dependency are
  10. allowed to be used with your package.
  11. Transitive dependencies are resolved and pulled the same as if they were
  12. listed in the manifest as well.
  13. The *Novel*:
  14. ``dds`` does not have a separate "install" step. Instead, whenever a ``dds
  15. build`` is executed, the dependencies are resolved, downloaded, extracted,
  16. and compiled. Of course, ``dds`` caches every step of this process, so you'll
  17. only see the download, extract, and compilation when you add a new dependency,
  18. Additionally, changes in the toolchain will necessitate that all the
  19. dependencies be re-compiled. Since the compilation of dependencies happens
  20. alongside the main project, the same caching layer that provides incremental
  21. compilation to your own project will be used to perform incremental
  22. compilation of your dependencies as well.
  23. .. seealso:: :doc:`/guide/interdeps`
  24. Listing Package Dependencies
  25. ****************************
  26. Suppose you have a project and you wish to use
  27. `spdlog <https://github.com/gabime/spdlog>`_ for your logging. To begin, we need
  28. to find a ``spdlog`` package. We can search via ``dds pkg search``::
  29. $ dds pkg search spdlog
  30. Name: spdlog
  31. Versions: 1.4.0, 1.4.1, 1.4.2, 1.5.0, 1.6.0, 1.6.1, 1.7.0
  32. From: repo-1.dds.pizza
  33. No description
  34. .. note::
  35. If you do not see any results, you may need to add the main repository to
  36. your package database. Refer to :doc:`/guide/remote-pkgs`.
  37. In the output above, we can see one ``spdlog`` group with several available
  38. versions. Let's pick the newest available, ``1.7.0``.
  39. If you've followed at least the :doc:`Hello, World tutorial </tut/hello-world>`,
  40. you should have at least a ``package.json5`` file present. Dependencies are
  41. listed in the ``package.json5`` file under the ``depends`` key as an array of
  42. dependency statement strings:
  43. .. code-block:: js
  44. :emphasize-lines: 5-7
  45. {
  46. name: 'my-application',
  47. version: '1.2.3',
  48. namespace: 'myself',
  49. depends: [
  50. "spdlog^1.7.0"
  51. ]
  52. }
  53. The string ``"spdlog^1.7.0"`` is a *dependency statement*, and says that we want
  54. ``spdlog``, with minimum version ``1.7.0``, but less than version ``2.0.0``.
  55. Refer to :ref:`deps.ranges` for information on the version range syntax.
  56. This is enough that ``dds`` knows about our dependency, but there is another
  57. step that we need to take:
  58. Listing Usage Requirements
  59. **************************
  60. The ``depends`` is a package-level dependency, but we need to tell ``dds`` that
  61. we want to *use* a library from that package. For this, we need to provide a
  62. ``library.json5`` file alongside the ``package.json5`` file.
  63. .. seealso::
  64. The ``library.json5`` file is discussed in :ref:`pkgs.libs` and
  65. :ref:`deps.lib-deps`.
  66. We use the aptly-named ``uses`` key in ``library.json5`` to specify what
  67. libraries we wish to use from our package dependencies. In this case, the
  68. library from ``spdlog`` is named ``spdlog/spdlog``:
  69. .. code-block:: js
  70. {
  71. name: 'my-application',
  72. uses: [
  73. 'spdlog/spdlog'
  74. ]
  75. }
  76. Using Dependencies
  77. ******************
  78. We've prepared our ``package.json5`` and our ``library.json5``, so how do we get
  79. the dependencies and use them in our application?
  80. Simply *use them*. There is no separate "install" step. Write your application
  81. as normal:
  82. .. code-block:: cpp
  83. :caption: src/app.main.cpp
  84. #include <spdlog/spdlog.h>
  85. int main() {
  86. spdlog::info("Hello, dependency!");
  87. }
  88. Now, when you run ``dds build``, you'll see ``dds`` automatically download
  89. ``spdlog`` *as well as* ``fmt`` (a dependency of ``spdlog``), and then build all
  90. three components *simultaneously*. The result will be an ``app`` executable that
  91. uses ``spdlog``.