Common Package Specification

The root of a CPS document is a package object. A package object describes a single package.

A platform describes the platform on which a package's components may run.

A requirement describes the specifics of a package dependency.

A component is a consumable part of a package. Typical components include libraries and executables.

A configuration holds attributes that are specific to a particular configuration of a component.

Specifies that the package's CABI components require the specified C standard/runtime library. Typical (case-insensitive) values include "bsd" (libc), "gnu" (glibc), "mingw" and "microsoft".

Specifies the minimum C standard/runtime library version required by the package's CABI components.

Specifies that the package's CLR (.NET) components require the specified Common Language Runtime vendor. Typical (case-insensitive) values include "microsoft" and "mono".

Specifies the minimum Common Language Runtime version required to use the package's CLR (.NET) components.

Specifies the oldest version of the package with which this version is compatible. This information is used when a consumer requests a specific version. If the version requested is equal to or newer than the compat_version, the package may be used.

If not specified, the package is not compatible with previous versions (i.e. compat_version is implicitly equal to version).

Specifies a list of Compiler Features that must be enabled or disabled when compiling code that consumes the component.

Specifies a list of additional flags that must be supplied to the compiler when compiling code that consumes the component. Note that compiler flags may not be portable; use of this attribute is discouraged.

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

Specifies additional components required by a component which are needed only at the compile stage. Unlike requires (component), only the required components' compilation-related attributes should be applied transitively; link requirements of the required component(s) should be ignored.

This is especially useful for libraries whose interfaces rely on the data types of a dependency but do not expose linkable symbols of that dependency, or which dynamically load the dependency at run-time.

Specifies the components which the package provides. Keys are the component names.

Specifies a list of components which must be present in the required package in order for the requirement to be satisfied. Although the build tool will generally produce an error if a consumer uses a component which in turn requires a component that was not found, early specification via this attribute may help build tools to diagnose such issues earlier and/or produce better diagnostics.

This may also be used to specify dependencies that are not expressed in component level dependencies, such as a package's requirement that a dependency includes a certain symbolic component, or if a dependency is only expressed at run-time.

Specifies the name of the configuration described by a configuration-specific .cps (see Configuration Merging). This attribute is required in a configuration-specific .cps, and shall be ignored otherwise.

Specifies the configurations that are preferred. See Package Configurations for a description of how configurations are used.

Specifies a set of configuration-specific attributes for a component. Keys are the configuration names.

Specifies that the package's CABI components require the specified C++ standard/runtime library. Typical (case-insensitive) values include "gnu" (libstdc++), "llvm" (libc++) and "microsoft".

Specifies the minimum C++ standard/runtime library version required by the package's CABI components.

Specifies the path to a C++ module metadata file (also known as a "P3286" file) necessary for consuming C++ interface units for pre-built libraries.

Specifies the directory portion location of the .cps file. This shall be an "absolute" path which starts with @prefix@. This provides a mechanism by which the tool may deduce the prefix of a relocatable package from the absolute location of the .cps file (which will be known by the tool). See also Prefix Determination for details.

Exactly one of cps_path or prefix is required.

Specifies the version of the CPS to which this .cps file conforms. This may be used by tools to provide backwards compatibility in case of compatibility-breaking changes in the CPS.

CPS version numbering follows semver. That is, tools that support CPS version . are expected to be able to read files with cps_version ., even for Z > Y (with the understanding that, in such cases, the tool may miss non-critical information that the CPS provided).

Specifies a list of components that should be inferred if a consumer specifies a dependency on a package, but not a specific component.

Specifies a collection of compile definitions that must be defined when compiling code that consumes the component. Each key in the inner map(s) is the name of a compile definition, such that e.g. -Dkey=value is passed to the compiler. A value may be null, indicating a definition with no value (e.g. -Dkey is passed to the compiler). Note that an empty string indicates -Dkey=, which may have a different effect than -Dkey.

The outer map is used to describe language-specific definitions. The build tool shall include only those definitions whose language matches (case-sensitive) that of the (lower case) language of the source file being compiled. Recognized languages shall include "c", "cpp", and "fortran". Additionally, the value "*" indicates that the corresponding definitions apply to all languages.

If a definition name is repeated in both "*" and a specific language, the latter, when applicable to the source being compiled, shall have precedence.

Specifies additional components required by a component which are needed only by the dynamic library loader. Unlike requires (component) or link_requires, these are not used to resolve symbol references of the consumer, but represent "private" implementation requirements of the component on which this attribute appears.

Typically, such requirements represent a need to ensure that the required component can be found at run time. This is usually accomplished in one of three ways:

Ensuring that the component resides in a default / "system" search path.

Encoding the component path in the binary in a way that influences the dynamic library loader (e.g. "RPATH").

Providing the component path in an environment variable which influences the dynamic library loader's search paths.

The last case requires external information to be provided; this attribute facilitates tools generating that information. In some instances, this external library search information may also be required to successfully link components, if the linker demands that all library references can be resolved.

Specifies a list of paths where a required dependency might be located. When given, this will usually provide the location of the dependency as it was consumed by the package when the package was built, so that consumers can easily find (correct) dependencies if they are in a location that is not searched by default.

Specifies a list of directories which should be added to the include 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 definitions.

Specifies that the package's CABI components require the specified Instruction Set Architecture. The value is case insensitive and should follow the output of uname -m.

Specifies that the package's Java components require the specified Java vendor. Typical (case-insensitive) values include "oracle" and "openjdk".

Specifies the minimum Java Virtual Machine version required to use the package's Java components.

Specifies the name of the operating system kernel required by the package's components. The value is case insensitive and should follow the output of uname -s. Typical values include "windows", "cygwin", "linux" and "darwin".

Specifies the minimum operating system kernel version required by the package's components.

Specifies a list of Linker Features that must be enabled or disabled when linking code that consumes the component.

Specifies a list of additional flags that must be supplied to the linker when linking code that consumes the component. Note that linker flags may not be portable; use of this attribute is discouraged.

Specifies the ABI language or languages of a static library (type "archive"). Officially supported (case-insensitive) values are "c" (no special handling required) and "cpp" (consuming the static library also requires linking against the C++ standard runtime).

Specifies a list of additional libraries (as paths, not components) that must be linked against when linking code that consumes the component. (Note that packages should avoid using this attribute if at all possible. Use requires (component) instead whenever possible.)

Specifies an alternate location of the component that should be used when linking against the component. This attribute typically applies only to "dylib" components on platforms where the library is separated into multiple file components. For example, on Windows, this attribute shall give the location of the .lib, while location shall give the location of the .dll.

If the path starts with @prefix@, the package's prefix is substituted (see Package Searching). This is recommended, as it allows packages to be relocatable.

This attribute is typically required for components of "dylib" type which have separate link-time and run-time artifacts.

Specifies additional components required by a component which are needed only at the link stage. Unlike requires (component), only the required components' link dependencies should be applied transitively; additional properties such as compile and include attributes of the required component(s) should be ignored.

Specifies the location of the component. The exact meaning of this attribute depends on the component type, but typically it provides the path to the component's primary artifact, such as a .so or .jar. (For Windows DLL components, this should be the location of the .dll. See also link_location.)

If the path starts with @prefix@, the package's prefix is substituted (see Package Searching). This is recommended, as it allows packages to be relocatable.

This attribute is required for components that are not of "interface" type.

Specifies the canonical name of the package. In order for searching to succeed, the name of the CPS file without the .cps suffix must exactly match (including case) either name as-is, or name converted to lower case.

Specifies the platform on which a package's components may run. This allows tools to ignore packages which target a different platform than the platform that the consumer targets (see Package Searching). Any platform attribute not specified implies that the package's components are agnostic to that platform attribute. If this attribute is not specified, the package is implied to be platform agnostic. (This might be the case for a "library" which consists entirely of C/C++ headers. Note that JVM/CLR versions are platform attributes, so packages consisting entirely of Java and/or CLR components will still typically use this attribute.)

Specifies the package's prefix for non-relocatable package. See also Prefix Determination.

Exactly one of cps_path or prefix is required.

Specifies additional components required by a component. This is used, for example, to indicate transitive dependencies. Relative component names are interpreted relative to the current package. Absolute component names must refer to a package required by this package (see requires (package)). Compile and link attributes should be applied transitively, as if the consuming component also directly consumed the components required by the component being consumed.

See also link_requires.

Specifies additional packages that are required by this package. Keys are the name of another required package. Values are a valid requirement object or null (equivalent to an empty requirement object) describing the package required.

Specifies the type of a component. The component type affects how the component may be used. Officially supported values are "executable" (any artifact which the target platform can directly execute), "archive" (CABI static library), "dylib" (CABI shared library), "module" (CABI plugin library), "jar" (Java Archive), "interface" and "symbolic". If the type is not recognized by the parser, the component shall be ignored. (Parsers are permitted to support additional types as a conforming extension.)

A "dylib" is meant to be linked at compile time; the location specifies the artifact required for such linking (i.e. the import library on PE platforms). A "module" is meant to be loaded at run time with dlopen or similar; again, the location specifies the appropriate artifact.

An "interface" component is a special case; it may have the usual attributes of a component, but does not have a location. This can be used to create "virtual" components that do not have an associated artifact.

A "symbolic" component is even more special, as it has no (required) attributes at all, and the meaning of any attributes or configurations assigned to such a component is unspecified. A "symbolic" component is intended to be used as a form of feature testing; a package that has a feature that is meaningful to users but does not otherwise map directly to a component may use a symbolic component to indicate availability of the feature to users.

Specifies the version of the package. The format of this string is determined by version_schema.

If not provided, the CPS will not satisfy any request for a specific version of the package.

Specifies the required version of a package. If omitted, any version of the required package is acceptable. Semantics are the same as for the version attribute of a package.

Specifies the structure to which the package's version numbering conforms. Tools may use this to determine how to perform version comparisons. Officially supported (case-insensitive) values are "simple" and "custom" ("rpm" or "dpkg" should be used where applicable, but may not be supported by all tools). If a package uses "custom", version numbers may be compared, but version ordering is not possible.

Needless to say, changing a package's version scheme between releases is very strongly discouraged.

Note that this attribute determines only how version numbers are ordered. It does not imply anything about the compatibility or incompatibility of various versions of a package. See also compat_version.

simple

The package's version number shall match the regular expression [0-9]+([.][0-9]+)([-+].)?.

The portion of the version which precedes the optional - or + may be interpreted as a tuple of integers, in which leading zeros are ignored. Version numbers are compared according to numerical order, starting from the first (left-most) number of the tuples. If two version numbers have different tuple sizes, the shorter tuple shall be implicitly filled with zeros.

Deprecated since version 0.9.0: "semver" is a deprecated alias for "simple".

Specifies the license that is assumed to apply to a component, if none is otherwise specified. This is convenient for packages that wish their license to reflect portions of the package that are not reflected by a component (such as data files) when most or all of the compiled artifacts use the same license.

The value shall be a well formed SPDX License Expression .

Provides a human readable description of the function which the package or component provides.

Provides a human readable name of the package. If provided, tools may use this in informational messages instead of, or in addition to, the canonical package name.

Specifies the license or licenses under which the package is distributed. The value shall be a well formed SPDX License Expression .

If parts of a package use different licenses, this attribute may also be specified on a component if doing so helps to clarifying the licensing. (See also default_license.)

Provides a description of the file contents, for readers that may not be familiar with CPS files. The typical value is "Common Package Specification for ".

Provides a URI link to a document describing the format of the CPS file. The typical value is "https://cps-org.github.io/cps/" (i.e. the top level page of this site).

Specifies the URI at which the package's website may be found.