Version
The version module extracts the project version from Git tags at configure time. It parses semantic version tags into the standard CMake version variables, so that the rest of the build system — installation rules, package metadata, documentation — can use the version without any manual bookkeeping.
The versioning scheme is defined by ADR-0007 — Versioning and Release Model, which establishes semantic versioning as the standard across all Ideal components.
Tag format
The module recognizes tags in two forms:
- Stable releases:
vX.Y.Z— for examplev1.0.0,v2.1.3 - Release candidates:
vX.Y.Z-rcN— for examplev2.0.0-rc1
The module uses
git describe --tags --match "v*" to find the most recent matching
tag. Tags that do not match the expected pattern are silently ignored.
Version string
The full version string depends on the relationship between the current commit and the most recent tag. When the
working tree is exactly on a tagged commit, the version matches the tag. When there are commits beyond the tag,
a distance and abbreviated hash are appended. A trailing + signals uncommitted changes in the working tree.
These modifiers combine freely. For instance, a commit that is 5 ahead of v1.2.3 with uncommitted changes
produces 1.2.3-5.gabcdef+.
| State | Example | PROJECT_VERSION_PRERELEASE |
|---|---|---|
| Tagged stable release | 1.2.3 | (empty) |
| Tagged release candidate | 2.0.0-rc1 | rc1 |
| Ahead of stable tag | 1.2.3-5.gabcdef | 5.gabcdef |
| Ahead of RC tag | 2.0.0-rc1.5.gabcdef | rc1.5.gabcdef |
| Dirty working tree | 1.2.3+ | (empty) |
| Dirty and ahead | 1.2.3-5.gabcdef+ | 5.gabcdef |
Variables defined
| Variable | Description |
|---|---|
PROJECT_VERSION | Full version string (e.g., 1.2.3, 2.0.0-rc1.5.gabcdef+) |
PROJECT_VERSION_MAJOR | Major version component |
PROJECT_VERSION_MINOR | Minor version component |
PROJECT_VERSION_PATCH | Patch version component |
PROJECT_VERSION_PRERELEASE | Prerelease identifier, or empty for exact stable releases |
Behavior
The module only runs when the project is the top-level project. If
project(VERSION ...) has already set a version —
as happens in source distributions created by make dist — the module does nothing. This ensures that the
version embedded in release tarballs is preserved exactly as it was at distribution time.
When Git is not available or no matching tag is found, the version defaults to 0.0.0 with a prerelease
identifier of unknown.