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