|
- How Do I Use Other Libraries as Dependencies?
-
-
- Of course, fundamental to any build system is the question of consuming
- dependencies. ``dds`` takes an approach that is both familiar and novel.
-
- The *Familiar*:
- Dependencies are listed in a project's package manifest file
- (``package.json5``, for ``dds``).
-
- A range of acceptable versions is provided in the package manifest, which
- tells ``dds`` and your consumers what versions of a particular dependency are
- allowed to be used with your package.
-
- Transitive dependencies are resolved and pulled the same as if they were
- listed in the manifest as well.
-
- The *Novel*:
- ``dds`` does not have a separate "install" step. Instead, whenever a ``dds
- build`` is executed, the dependencies are resolved, downloaded, extracted,
- and compiled. Of course, ``dds`` caches every step of this process, so you'll
- only see the download, extract, and compilation when you add a new dependency,
-
- Additionally, changes in the toolchain will necessitate that all the
- dependencies be re-compiled. Since the compilation of dependencies happens
- alongside the main project, the same caching layer that provides incremental
- compilation to your own project will be used to perform incremental
- compilation of your dependencies as well.
-
- .. seealso:: :doc:`/guide/interdeps`
-
-
- Listing Package Dependencies
- ****************************
-
- Suppose you have a project and you wish to use
- `spdlog <https://github.com/gabime/spdlog>`_ for your logging. To begin, we need
- to find a ``spdlog`` package. We can search via ``dds pkg search``::
-
- $ dds pkg search spdlog
- Name: spdlog
- Versions: 1.4.0, 1.4.1, 1.4.2, 1.5.0, 1.6.0, 1.6.1, 1.7.0
- From: repo-1.dds.pizza
- No description
-
- .. note::
- If you do not see any results, you may need to add the main repository to
- your package database. Refer to :doc:`/guide/remote-pkgs`.
-
- In the output above, we can see one ``spdlog`` group with several available
- versions. Let's pick the newest available, ``1.7.0``.
-
- If you've followed at least the :doc:`Hello, World tutorial </tut/hello-world>`,
- you should have at least a ``package.json5`` file present. Dependencies are
- listed in the ``package.json5`` file under the ``depends`` key as an array of
- dependency statement strings:
-
- .. code-block:: js
- :emphasize-lines: 5-7
-
- {
- name: 'my-application',
- version: '1.2.3',
- namespace: 'myself',
- depends: [
- "spdlog^1.7.0"
- ]
- }
-
- The string ``"spdlog^1.7.0"`` is a *dependency statement*, and says that we want
- ``spdlog``, with minimum version ``1.7.0``, but less than version ``2.0.0``.
- Refer to :ref:`deps.ranges` for information on the version range syntax.
-
- This is enough that ``dds`` knows about our dependency, but there is another
- step that we need to take:
-
-
- Listing Usage Requirements
- **************************
-
- The ``depends`` is a package-level dependency, but we need to tell ``dds`` that
- we want to *use* a library from that package. For this, we need to provide a
- ``library.json5`` file alongside the ``package.json5`` file.
-
- .. seealso::
- The ``library.json5`` file is discussed in :ref:`pkgs.libs` and
- :ref:`deps.lib-deps`.
-
- We use the aptly-named ``uses`` key in ``library.json5`` to specify what
- libraries we wish to use from our package dependencies. In this case, the
- library from ``spdlog`` is named ``spdlog/spdlog``:
-
- .. code-block:: js
-
- {
- name: 'my-application',
- uses: [
- 'spdlog/spdlog'
- ]
- }
-
-
- Using Dependencies
- ******************
-
- We've prepared our ``package.json5`` and our ``library.json5``, so how do we get
- the dependencies and use them in our application?
-
- Simply *use them*. There is no separate "install" step. Write your application
- as normal:
-
- .. code-block:: cpp
- :caption: src/app.main.cpp
-
- #include <spdlog/spdlog.h>
-
- int main() {
- spdlog::info("Hello, dependency!");
- }
-
- Now, when you run ``dds build``, you'll see ``dds`` automatically download
- ``spdlog`` *as well as* ``fmt`` (a dependency of ``spdlog``), and then build all
- three components *simultaneously*. The result will be an ``app`` executable that
- uses ``spdlog``.
|