From 72b9a68bbcf4f402a8d7ead5ce5f2f3d435ae36f Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Mon, 8 Jun 2026 10:53:00 -0400 Subject: [PATCH] Add `embeds`, file sets Add attributes to support the C/C++ `#embed` directive which was recently standardized. Introduce a 'file set' object to the schema, with corresponding `file_sets` attribute. These are being combined mostly for the sake of the corresponding schema version bump, but 'embeds' are one of the supported file set types. For now, file sets are primarily informative, offering a way for certain tools to match `#include`/`#embed` directives in consumer's sources to specific components, which is useful for various sorts of correctness validation ("linting"). --- conf.py | 2 +- configurations.rst | 3 +- schema.rst | 104 ++++++++++++++++++++++++++++++++++++++++++--- searching.rst | 2 +- 4 files changed, 102 insertions(+), 9 deletions(-) diff --git a/conf.py b/conf.py index 92493b9..de7d09a 100644 --- a/conf.py +++ b/conf.py @@ -13,7 +13,7 @@ project = 'Common Package Specification' copyright = '2026, The CPS Authors' -version_info = (0, 14, 1) +version_info = (0, 15, 0) release = '.'.join(map(str, version_info)) version = '.'.join(map(str, version_info[:2])) diff --git a/configurations.rst b/configurations.rst index 1e6ab74..757496b 100644 --- a/configurations.rst +++ b/configurations.rst @@ -112,7 +112,8 @@ is the same as a common CPS, with three exceptions: Use of other attributes specified in the schema is ill-formed. - The per-configuration specification may not specify - any :object:`component` attributes (e.g. :attribute:`type`). + any :object:`component` attributes + (e.g. :attribute:`~component.type`). Only :object:`configuration` attributes are allowed. - An attribute on a :object:`component` diff --git a/schema.rst b/schema.rst index 2b86303..53db850 100644 --- a/schema.rst +++ b/schema.rst @@ -33,6 +33,12 @@ Objects A |configuration| holds attributes that are specific to a particular configuration of a |component|. +.. ---------------------------------------------------------------------------- +.. cps:object:: fileset + + A |fileset| describes a set of files + which are associated with a |component|. + Attributes '''''''''' @@ -244,7 +250,7 @@ Attribute names are case sensitive. (which will be known by the tool). See also `Prefix Determination`_ for details. - Exactly **one** of :attribute:`!cps_path` or :attribute:`prefix` + Exactly **one** of :attribute:`!cps_path` or :attribute:`~package.prefix` is required. .. ---------------------------------------------------------------------------- @@ -340,6 +346,53 @@ Attribute names are case sensitive. may also be required to successfully link components, if the linker demands that all library references can be resolved. +.. ---------------------------------------------------------------------------- +.. cps:attribute:: embeds + :type: list(string)|map(list(string)) + :context: component configuration + + Specifies a list of directories + which should be added to the embed search path + when compiling code that consumes the component. + If a path starts with ``@prefix@``, + the package's prefix is substituted + (see `Package Searching`_). + This is recommended, as it allows packages to be relocatable. + + A map may be used instead to give different values + depending on the language of the consuming source file. + Handling of such shall be the same as for :attribute:`definitions`. + +.. ---------------------------------------------------------------------------- +.. cps:attribute:: file_sets + :type: list(fileset) + :context: component + + Specifies sets of files which are associated with a |component|. + + Note that a component may have several |fileset|\ s + of the same :attribute:`~fileset.type`, + and that files may appear in more than one |fileset|. + +.. ---------------------------------------------------------------------------- +.. cps:attribute:: files + :type: list(string) + :context: fileset + :required: + + Specifies a list of partial paths + to files belonging to a |fileset|. + The canonical location of each file + shall be the path concatenation + of the |fileset|\ ’s :attribute:`~fileset.prefix` + and the partial path expressed in :attribute:`!files`. + + For files belonging to + :string:`"embeds"` or :string:`"includes"` |fileset|\ s, + the partial path shall match the partial path + as intended to appear in embed/include directives + in consuming source files. + .. ---------------------------------------------------------------------------- .. cps:attribute:: hints :type: list(string) @@ -448,8 +501,8 @@ Attribute names are case sensitive. :context: component configuration :default: ["c"] - Specifies the ABI language or languages of a static library - (:attribute:`type` :string:`"archive"`). + Specifies the ABI language or languages of a static library component + (:attribute:`~component.type` :string:`"archive"`). Officially supported (case-insensitive) values are :string:`"c"` (no special handling required) and :string:`"cpp"` (consuming the static library @@ -485,7 +538,7 @@ Attribute names are case sensitive. This is recommended, as it allows packages to be relocatable. This attribute is typically required - for |component|\ s of :string:`"dylib"` :attribute:`type` + for |component|\ s of :string:`"dylib"` :attribute:`~component.type` which have separate link-time and run-time artifacts. .. ---------------------------------------------------------------------------- @@ -523,7 +576,7 @@ Attribute names are case sensitive. This is recommended, as it allows packages to be relocatable. This attribute is required for |component|\ s - that are not of :string:`"interface"` :attribute:`type`. + that are not of :string:`"interface"` :attribute:`~component.type`. .. ---------------------------------------------------------------------------- .. cps:attribute:: name @@ -564,6 +617,7 @@ Attribute names are case sensitive. .. cps:attribute:: prefix :type: string :context: package + :overload: Specifies the package's prefix for non-relocatable package. @@ -572,6 +626,21 @@ Attribute names are case sensitive. Exactly **one** of :attribute:`cps_path` or :attribute:`!prefix` is required. +.. ---------------------------------------------------------------------------- +.. cps:attribute:: prefix + :type: string + :context: fileset + :required: + :overload: + + Specifies the base path of files in the file set. + For :string:`"embeds"` and :string:`"includes"` |fileset|\ s, + this path should match one of the paths specified in the component's + :attribute:`embeds` or :attribute:`includes` attributes, + such that the :attribute:`files` paths + exactly match how the path to those files + is intended to appear in consuming sources. + .. ---------------------------------------------------------------------------- .. cps:attribute:: requires :type: list(string) @@ -606,6 +675,7 @@ Attribute names are case sensitive. :type: string :context: component :required: + :overload: Specifies the type of a component. The component type affects how the component may be used. @@ -616,7 +686,7 @@ Attribute names are case sensitive. :string:`"module"` (CABI plugin library), :string:`"jar"` (Java Archive), :string:`"interface"` and :string:`"symbolic"`. - If the type is not recognized by the parser, + If the :attribute:`!type` is not recognized by the parser, the component shall be ignored. (Parsers are permitted to support additional types as a conforming extension.) @@ -645,6 +715,26 @@ Attribute names are case sensitive. may use a symbolic component to indicate availability of the feature to users. +.. ---------------------------------------------------------------------------- +.. cps:attribute:: type + :type: string + :context: fileset + :required: + :overload: + + Specifies the type of files + which are enumerated by the |fileset|. + Officially supported values are + :string:`"embeds"` and :string:`"includes"`, + which describe files intended to be referenced + via ``embed`` and ``include`` directives, respectively. + If the :attribute:`!type` is not recognized by the parser, + the component shall be ignored. + (Parsers are permitted to support additional types + as a conforming extension.) + + See also :attribute:`embeds` and :attribute:`includes`. + .. ---------------------------------------------------------------------------- .. cps:attribute:: version :type: string @@ -787,6 +877,8 @@ please refer to our `Development Process`_.) .. |configuration| replace:: :object:`configuration` +.. |fileset| replace:: :object:`fileset` + .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. .. kate: hl reStructuredText diff --git a/searching.rst b/searching.rst index 2718ced..de03187 100644 --- a/searching.rst +++ b/searching.rst @@ -127,7 +127,7 @@ it is necessary to know the package's prefix as :var:`prefix`, above). This is accomplished in one of two ways: -- If a package specifies :attribute:`prefix`, +- If a package specifies :attribute:`~package.prefix`, that value is used. - If a package specifies :attribute:`cps_path`,