https://github.com/emanuelemessina/cmake-git-versioning
A CMake module to auto update the project version numbers from Git tags.
https://github.com/emanuelemessina/cmake-git-versioning
cmake git version-control versioning
Last synced: 11 months ago
JSON representation
A CMake module to auto update the project version numbers from Git tags.
- Host: GitHub
- URL: https://github.com/emanuelemessina/cmake-git-versioning
- Owner: emanuelemessina
- License: mit
- Created: 2022-08-28T18:27:41.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-08-28T19:48:51.000Z (almost 4 years ago)
- Last Synced: 2025-03-05T14:30:50.958Z (over 1 year ago)
- Topics: cmake, git, version-control, versioning
- Language: CMake
- Homepage:
- Size: 17.6 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cmake-git-versioning
A CMake module to auto update the project version numbers from Git tags.
## Usage
1. Check that git exists, eg:
```cmake
find_package(Git)
if(GIT_FOUND)
message("Git found: ${GIT_EXECUTABLE}")
else()
message(FATAL_ERROR "Git not found!")
endif()
```
2. Include the module:
```cmake
include("path/to/cmake-git-versioning.cmake")
```
3. You now have access to the [Output Variables](#output-variables).
When you want to update the current version of your project, tag a commit with a [version tag](#version-tag-syntax). The most recent version tag found is taken as the current version.
## Internal Behavior
### Notes
This module:
- Uses `GIT_FOUND` to check if git is present.
- Uses `GIT_EXECUTABLE` to call git.
### Quick flowchart
### Details
The module won't start if git is not found.
\
If git is found, it queries the latest tag.
\
If no tag is found it checks the `.version` file.
\
If the latest tag does not contain the mandatory `major.minor.patch` pattern, the tag is not considered a valid version tag. It checks `.version` for the latest version cached.
\
If the tag is valid, it checks for a `-tweak.number` part. If not present/valid, it defaults it to `0.0`.
\
Finally builds the output variables and cache them to `.version` in the project root directory.
\
\
When checking `.version`, if it corrupted or it doesn't exist, sets the current major number to `1` and everything else at `0`. This is the last resort to pass CMake a valid version when calling `project`.
###
Valid version tag syntax
Git version tag syntax:
[something]..[-[.]]
## Output Variables
The following variables will be set ( eg. complete latest git version tag: `v2.3.1-RC.7` ) :
- `PROJECT_VERSION_STRING`
> Version string without metadata. Directly corresponds to the latest version tag (`v2.3.1-RC.7`)
- `PROJECT_VERSION_STRING_FULL`
> Version string with added git metadata (`v2.3.1-RC.7+21.ef12c8`)
- `PROJECT_VERSION`
> Same as `PROJECT_VERSION_STRING`, without preceding letters (`2.3.1-RC.7`)
- `PROJECT_VERSION_MAJOR`
> Major version number (`2`)
- `PROJECT_VERSION_MINOR`
> Minor version number (`3`)
- `PROJECT_VERSION_PATCH`
> Patch version number (`1`)
- `PROJECT_VERSION_MMP`
> Simple `major.minor.patch` version string (`2.3.1`)
- `PROJECT_VERSION_TWEAK_NAME`
> Tweak version name (`RC`)
- `PROJECT_VERSION_TWEAK_NUMBER`
> Tweak version number : (`7`)
- `PROJECT_VERSION_TWEAK_FULL`
> Tweak version full string (`RC.7`)
- `PROJECT_VERSION_COMMITS_AHEAD`
> Number of commits ahead of last tag (`21`)
- `PROJECT_VERSION_COMMIT_SHA`
> Git SHA1 of the most recent commit (`ef12c8`)
- `PROJECT_VERSION_CMAKE`
> CMake compatible VERSION string, uses the `_TWEAK_NUMBER` as the build number (`2.3.1.7`)
## Acknowledgements
This module was inspired by the public domain [cmake-git-semver](https://github.com/nunofachada/cmake-git-semver).
[License](https://github.com/emanuelemessina/cmake-git-versioning/blob/master/LICENSE)