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" | |||||
} |