| Error: Invalid library manifest | |||||
| ############################### | |||||
| Every ``dds`` package must contain a valid library manifest for each library | |||||
| that it exports. These manifests are stored in the library root to which they | |||||
| correspond, and are stored in JSON5 format in ``library.json5`` (or similarly | |||||
| named file). | |||||
| The contents of this file must follow a prescribed content, or ``dds`` will | |||||
| reject the manifest. Refer to the :ref:`pkgs.libs` documentation page for more | |||||
| information about how to declare libraries. |
| For exporting/generating a source distribution from a package, the *package | For exporting/generating a source distribution from a package, the *package | ||||
| root* requires a ``package.json5`` file and each *library root* requires a | root* requires a ``package.json5`` file and each *library root* requires a | ||||
| ``library.dds`` file. | |||||
| ``library.json5`` file. | |||||
| .. . | .. . | ||||
| TODO: Create are more detailed reference page for package and library layout, | TODO: Create are more detailed reference page for package and library layout, |
| ######################################### | ######################################### | ||||
| A library can declare that it *uses* or *links* to another library by using the | A library can declare that it *uses* or *links* to another library by using the | ||||
| ``Uses`` and ``Links`` keys in ``library.dds``, respectively. | |||||
| ``uses`` and ``links`` keys in ``library.json5``, respectively. | |||||
| These requirements are specified by using the ``namespace/name`` pair that | These requirements are specified by using the ``namespace/name`` pair that | ||||
| identifies a library. These are defined by both the project's dependencies and | identifies a library. These are defined by both the project's dependencies and | ||||
| the project itself. If a ``Uses`` or ``Links`` key does not correspond to a | |||||
| the project itself. If a ``uses`` or ``links`` key does not correspond to a | |||||
| known library, ``dds`` will not be able to resolve the usage requirements, and | known library, ``dds`` will not be able to resolve the usage requirements, and | ||||
| will generate an error. | will generate an error. | ||||
| ``--git-url <url>`` | ``--git-url <url>`` | ||||
| Specify a Git URL to clone from to obtain the package. The root of the | 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 | cloned repository must be a package root, but does not necessarily need to | ||||
| have the ``package.json5`` and ``library.dds`` files if relying on the | |||||
| have the ``package.json5`` and ``library.json5`` files if relying on the | |||||
| ``--auto-lib`` parameter. | ``--auto-lib`` parameter. | ||||
| ``--git-ref`` **must** be passed with ``--git-url``. | ``--git-ref`` **must** be passed with ``--git-url``. |
| In ``dds``, library interdependencies are tracked separately from the packages | In ``dds``, library interdependencies are tracked separately from the packages | ||||
| that contain them. A library must declare its intent to use another library | 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: | |||||
| in the ``library.json5`` at its library root. The minimal content of a | |||||
| ``library.json5`` is the ``Name`` key: | |||||
| .. code-block:: | |||||
| .. code-block:: js | |||||
| Name: gadgets | |||||
| { | |||||
| name: 'gadgets' | |||||
| } | |||||
| To announce that a library wishes to *use* another library, use the aptly-named | To announce that a library wishes to *use* another library, use the aptly-named | ||||
| ``Uses`` key: | |||||
| ``uses`` key: | |||||
| .. code-block:: js | .. code-block:: js | ||||
| :emphasize-lines: 3-5 | |||||
| :emphasize-lines: 3-7 | |||||
| Name: gadgets | |||||
| Uses: acme/widgets | |||||
| Uses: acme/gizmos | |||||
| Uses: acme/utils | |||||
| { | |||||
| name: 'gadgets', | |||||
| uses: [ | |||||
| 'acme/widgets', | |||||
| 'acme/gizmos', | |||||
| 'acme/utils', | |||||
| ], | |||||
| } | |||||
| Here is where the package's ``namespace`` key comes into play: A library's | 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 | qualified name is specified by joining the ``namespace`` of the containing | ||||
| However, it is essential that the ``<namespace>/<name>`` pair be | However, it is essential that the ``<namespace>/<name>`` pair be | ||||
| universally unique, so choose wisely! | universally unique, so choose wisely! | ||||
| Once the ``Uses`` key appears in the ``library.dds`` file of a library, ``dds`` | |||||
| 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 | will make available the headers for the library being used, and will | ||||
| transitively propagate that usage requirement to users of the library. | transitively propagate that usage requirement to users of the library. |
| dependencies of a header-only library. | dependencies of a header-only library. | ||||
| In order for ``dds`` to be able to distribute and interlink libraries, a | In order for ``dds`` to be able to distribute and interlink libraries, a | ||||
| ``library.dds`` file must be present at the corresponding library root. The | |||||
| only required key in a ``library.dds`` file is ``Name``: | |||||
| ``library.json5`` file must be present at the corresponding library root. The | |||||
| only required key in a ``library.json5`` file is ``Name``: | |||||
| .. code-block:: yaml | |||||
| Name: my-library | |||||
| .. code-block:: js | |||||
| { | |||||
| name: 'my-library' | |||||
| } | |||||
| .. seealso:: More information is discussed on the :ref:`deps.lib-deps` page | .. seealso:: More information is discussed on the :ref:`deps.lib-deps` page | ||||
| $ ls ./spdlog@1.4.2/ | $ ls ./spdlog@1.4.2/ | ||||
| include/ | include/ | ||||
| src/ | src/ | ||||
| library.dds | |||||
| library.json5 | |||||
| package.json5 | package.json5 | ||||
| )"; | )"; | ||||
| case errc::unknown_usage_name: | case errc::unknown_usage_name: | ||||
| return R"( | return R"( | ||||
| A `Uses` or `Links` field for a library specifies a library of an unknown name. | |||||
| A `uses` or `links` field for a library specifies a library of an unknown name. | |||||
| Check your spelling, and check that the package containing the library is | Check your spelling, and check that the package containing the library is | ||||
| available, either from the `package.json5` or from the `INDEX.lmi` that was used | available, either from the `package.json5` or from the `INDEX.lmi` that was used | ||||
| for the build. | for the build. | ||||
| case errc::dup_lib_name: | case errc::dup_lib_name: | ||||
| return "More than one library has claimed the same name."; | return "More than one library has claimed the same name."; | ||||
| case errc::unknown_usage_name: | case errc::unknown_usage_name: | ||||
| return "A `Uses` or `Links` field names a library that isn't recognized."; | |||||
| return "A `uses` or `links` field names a library that isn't recognized."; | |||||
| case errc::none: | case errc::none: | ||||
| break; | break; | ||||
| } | } |
| Name: dummy | |||||
| Uses: nlohmann/json |
| { | |||||
| name: "dummy", | |||||
| uses: [ | |||||
| 'nlohmann/json', | |||||
| ] | |||||
| } |
| Name: spdlog-user | |||||
| Uses: spdlog/spdlog |
| { | |||||
| name: 'spdlog-user', | |||||
| uses: [ | |||||
| 'spdlog/spdlog', | |||||
| ] | |||||
| } |
| Name: foo |
| { | |||||
| "name": "foo" | |||||
| } |