Browse Source

Update tests and docs to refer to library.json5

default_compile_flags
vector-of-bool 4 years ago
parent
commit
5565294072
14 changed files with 56 additions and 31 deletions
  1. +11
    -0
      docs/err/invalid-lib-manifest.rst
  2. +1
    -1
      docs/err/invalid-pkg-filesystem.rst
  3. +2
    -2
      docs/err/unknown-usage.rst
  4. +1
    -1
      docs/guide/catalog.rst
  5. +17
    -12
      docs/guide/interdeps.rst
  6. +6
    -5
      docs/guide/packages.rst
  7. +1
    -1
      docs/guide/repo.rst
  8. +2
    -2
      src/dds/error/errors.cpp
  9. +0
    -3
      tests/deps/use-remote/library.dds
  10. +6
    -0
      tests/deps/use-remote/library.json5
  11. +0
    -3
      tests/deps/use-spdlog/project/library.dds
  12. +6
    -0
      tests/deps/use-spdlog/project/library.json5
  13. +0
    -1
      tests/sdist/create/library.dds
  14. +3
    -0
      tests/sdist/create/library.jsonc

+ 11
- 0
docs/err/invalid-lib-manifest.rst View File

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.

+ 1
- 1
docs/err/invalid-pkg-filesystem.rst View File



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,

+ 2
- 2
docs/err/unknown-usage.rst View File

######################################### #########################################


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.



+ 1
- 1
docs/guide/catalog.rst View File

``--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``.

+ 17
- 12
docs/guide/interdeps.rst View File



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.

+ 6
- 5
docs/guide/packages.rst View File

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



+ 1
- 1
docs/guide/repo.rst View File

$ ls ./spdlog@1.4.2/ $ ls ./spdlog@1.4.2/
include/ include/
src/ src/
library.dds
library.json5
package.json5 package.json5





+ 2
- 2
src/dds/error/errors.cpp View File

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

+ 0
- 3
tests/deps/use-remote/library.dds View File

Name: dummy

Uses: nlohmann/json

+ 6
- 0
tests/deps/use-remote/library.json5 View File

{
name: "dummy",
uses: [
'nlohmann/json',
]
}

+ 0
- 3
tests/deps/use-spdlog/project/library.dds View File

Name: spdlog-user

Uses: spdlog/spdlog

+ 6
- 0
tests/deps/use-spdlog/project/library.json5 View File

{
name: 'spdlog-user',
uses: [
'spdlog/spdlog',
]
}

+ 0
- 1
tests/sdist/create/library.dds View File

Name: foo

+ 3
- 0
tests/sdist/create/library.jsonc View File

{
"name": "foo"
}

Loading…
Cancel
Save