The CRS Packaging Format

CRS, an initialism for “Compile-Ready Source”, is a package format with an emphasis on simplicity and embeddability. A CRS package is so-called “compile-ready” because it contains package source files that do not require preparation, configuration, generation, or tweaking before being given to a compiler.

Note

The CRS format is intended to be portable and not directly tied to bpt itself.

Note

This documentation, and CRS itself, are both still works-in-progress. It may be incomplete and feature errors in speling and grammars.

Topics

Base Concepts

Briefly, CRS concerns itself with the following high-level concepts:

CRS

An acronym for Compile-Ready Source. CRS is a set of file formats and JSON schemas that describe a way to distribute software in source-code format, ready to be given to any compatible compiler without further configuration or code generation.

See also

The CRS Packaging Format

CRS package

A CRS package is the unit of distribution in CRS. A package has a name and a version and contains one or more CRS libraries.

See also

The documentation page about packages

CRS library

A CRS library is the smallest consumable unit in a CRS package. A package can have one or more libraries, but a library can only belong to one package. Each library within a single package must have a unique name. A library can have some number of CRS dependencies, and can “use” other libraries within the same package.

See also

The documentation page about libraries

CRS dependency

A CRS dependency is associated with a CRS library within a CRS package. A dependency names a package, one or more libraries within that package, and one or more compatible version ranges.

See also

The documentation page about dependencies

Dependencies

Range Semantics

Versions should be compared using the version ordering specified by Semantic Versioning.

For the purpose of version comparison, a synthesized version number “synth-high” refers to the version specified by high with an additional lowest-possible-precedence prerelease identifier attached. It is impossible to spell this synthesized semantic version number as a valid string, but it is required to obtain half-open range semantics on version ranges. For purposes of examples here, this lowest-possible-precedence prerelease identifier will be represented as a percent-symbol “%”.

If given a version V and a low and high range, V is considered to be within the version range if it is greater-than or equal-to low, and less-than “synth-high”.

Range Comparison Example

Suppose a version range is provided:

{
    "low": "2.8.0",
    "high": "3.0.0"
}

and the following versions are available:

  • 1.2.6

  • 2.5.6

  • 2.7.5

  • 2.8.0-beta.1

  • 3.0.0-alpha

  • 3.1.0

It is easy to see that 1.2.6, 2.5.6, and 2.7.5 are too old, as they compare less-than the low version. The 3.1.0 version is greater-than the high version, so it is also not within the range.

The 2.8.0-beta.1 version is less-than our low 2.8.0 requirement, since prerelease versions are strictly less-than a non-prerelease with the same version number components.

The 3.0.0-alpha version is within the half-open version range [2.8.0, 3.0.0), because 3.0.0-alpha is less-than 3.0.0. However, selecting this version to satisfy the range would be very surprising and unlikely to be what the user wanted. For this reason, the synthesized prerelease “high” version 3.0.0-% is used for the range comparison. The imaginary “%” prerelease identifier is strictly less than all other possible prerelease identifiers. For this reason, 3.0.0-alpha is not within the half-open version range [2.8.0, 3.0.0-%), and therefore does not satisfy the dependency version range JSON object provided.