Skip to content

Improve configuration-related documentation #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mwoehlke wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve configuration-related documentation #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 27 additions & 69 deletions configurations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,42 @@
Package Configurations
======================

Configurations provide a mechanism
for a package to provide multiple configurations
from a single distribution.
Such configurations might include
separate debug and release libraries,
builds with and without thread safety,
and so forth.
Configurations allow packages to provide
multiple "flavors" of binary objects
in a single distribution,
which have been compiled using different options
to facilitate different use cases.
Nominally, such objects must be *type-homogeneous*,
meaning all configurations of a component
must be of the same `type`_.
(See `Multi-Axis Configurations`_
for a way to work around this restriction;
however, be aware of the caveats described therein.)

Typical configuration axes include
presence or omission of instrumentation code,
optimization level,
and selection of interchangeable implementations.
The possible configurations
are determined by each individual package,
and it is left to the consumer and build system
to decide when and how to select a non-default configuration.
Refer to `Configuration Use Cases`_ for guidance
on what should or should not be expressed as a configuration.

Like appendices, configurations support partial installation.
This allows a package to be built in several configurations,
while permitting users to install only one desired configuration.
Refer to `Description Merging`_ for additional information.

Configuration Selection
'''''''''''''''''''''''

When a consumer consumes a component,
the build system must determine the attribute values for that component
by selecting which configuration of the component to use
(if the component has multiple configurations).
Selection shall treat configuration names as case insensitive.
It is recommended that build systems select a configuration as follows:

- For each package, the consumer shall have a mechanism
Expand Down Expand Up @@ -60,68 +80,6 @@ otherwise, a value of :keyword:`null`
shall be treated as the attribute being unset
(and shall suppress falling back to the non-configuration-specific value).

Configuration Merging
'''''''''''''''''''''

Some build systems may desire to output
separate specifications per configuration,
and/or to output separate CPS files per component.
This is especially useful to permit piecemeal installation
of individual components and/or configurations
(for example, a "base" package
with release libraries and common components,
an optional package with debug libraries,
and another optional package with optional components).

When a tool locates a CPS file, :var:`name`\ :path:`.cps`,
the tool shall look in the same directory for any files
which match any of the patterns
(the asterisk (``*``) represents file globbing):

- :var:`name`\ :path:`:`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`-`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`@`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`:`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`-`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`

Patterns containing colon (``:``) shall be skipped
on platforms for which that character
is not permitted in file names (e.g. Windows).

If any such package specifications are found,
they shall be loaded at the same time,
and their contents appended to the information loaded from the base CPS.
(Note, however, that tools are permitted
to ignore the information in any such supplemental CPS file
as they may determine is not relevant to the user's needs.
In particular, see `Transitive Dependencies`_.)

A ``.cps`` file whose name contains ``@``
is a configuration-specific CPS.
The structure of a configuration-specific CPS
is the same as a common CPS, with three exceptions:

- The only defined :object:`package` keys are
`name`_, `configuration`_, and `components <components\ (package)>`_.
The first two are required.
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`).
Only :object:`configuration` attributes are allowed.

- An attribute on a :object:`component`
is considered to belong instead
to the component-configuration
identified by the configuration-specific CPS.

The order in which the data from multiple CPS files is appended
is implementation-defined.

.. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... ..

.. kate: hl reStructuredText
1 change: 1 addition & 0 deletions index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ Core Specification
components
configurations
searching
merging

Appendices
''''''''''
Expand Down
88 changes: 88 additions & 0 deletions merging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
Description Merging
===================

Some build systems may desire to output
separate specifications per configuration,
and/or to break a package's components into multiple output files,
often according to functional groups.
This is especially useful to permit piecemeal installation
of components and/or configurations
(for example, a "base" package
with release libraries and common components,
an optional package with debug libraries,
and another optional package with optional components).
This also allows build tools to import only those components
which are actually required by a consumer.

When a tool locates a CPS file, :var:`name`\ :path:`.cps`,
the tool shall look in the same directory for any files
which match any of the patterns
(the asterisk (``*``) represents file globbing):

- :var:`name`\ :path:`:`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`-`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`@`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`:`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`

- :var:`name`\ :path:`-`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`

.. note::

Patterns containing colon (``:``) shall be skipped
on platforms for which that character
is not permitted in file names (e.g. Windows).

If any such package specifications are found,
they shall be loaded at the same time,
and their contents appended to the information loaded from the base CPS.
However, tools are permitted and encouraged
to ignore the information in any such supplemental CPS files
as they may determine is not relevant to the user's needs.
In particular, see `Transitive Dependencies`_.)

A ``.cps`` file whose name contains ``@``
is a configuration-specific CPS.
The structure of a configuration-specific CPS
is the same as a base CPS, with three exceptions:

- The only defined :object:`package` keys are
`name`_, `cps_version`_, `configuration`_,
and `components <components\ (package)>`_.
The first three are required.
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`).
Only :object:`configuration` attributes are allowed.

- An attribute on a :object:`component`
is considered to belong instead
to the component-configuration
identified by the configuration-specific CPS.

A ``.cps`` file which supplements the components
of the package's base CPS
is known as an "appendix".
The structure of a CPS appendix
is the same as a base CPS, with two exceptions:

- The only defined :object:`package` keys are
`name`_, `requires <requires\ (package)>`_, `default_license`_
and `components <components\ (package)>`_.
The first is required.
Use of other attributes specified in the schema is ill-formed.

- An appendix may not specify components
which are described in the base CPS
or in any other appendix.

The order in which the data from multiple CPS files is collated
is implementation-defined.
Behavior when a supplemental CPS file's `cps_version`_
differs from the base CPS's version
is implementation-defined.
(However, for obvious reasons,
this is strongly discouraged.)
2 changes: 1 addition & 1 deletion overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Advantages of CPS

CPS allows a package to provide targets in multiple configurations,
with no restriction on the naming of configurations.
Use of interface targets (see `Configurations as Flags`_)
Use of interface targets (see `Multi-Axis Configurations`_)
allows consumers to select the appropriate configuration
by specifying target points along multiple axes.
This especially facilitates creation and use of packages
Expand Down
Loading