Version.cmake

Simplify your Semantic-Version automation within every developer build using code commits and repository tags.

Prerequisites

Use CMake to build your project.
Use Git as your code repository
💡 If you are using a different SCM please raise an issue
Structure your project. See Here.
Use modern CMake features like targets and properties. See here and here.
Understand semantic versioning here and here.
Tag your releases with the version prefixed by a v.
💎 This is now optional but still preferred - Version.cmake should detect if your tag is 'version-like'
Use a 'Prefix' for your project options in CMake options:
💎 Instead of BUILD_TESTING use MYLIBRARY_BUILD_TESTING

All variables use the form VERSION_<field>

Values are defined similar both CMake and via the default Version.h using C-Preprocessor:or:

VERSION_SET - Boolean indicating if VERSION_<fields> have been populated
VERSION_MAJOR - Major semantic-version extracted from repository tag
VERSION_MINOR - Minor semantic-version extracted from repository tag
VERSION_PATCH - Patch semantic-version extracted from repository tag
VERSION_COMMIT - Commit-count semantic-version extracted from repository branch revision
VERSION_SHA - Revision specific unique SHA hash. For example 4c757e7
VERSION_SEMANTIC - Full semantic version in form <major>.<minor>.<patch>.<commit>. For example 0.1.0.10
VERSION_FULL - Full string description, useful for ABI compatiblity. For example v0.1-9-g4c757e7-dirty

We recommend using CPM.cmake so you stay upto-date with the latest fixes and features.

Alternative, you may directly include Version.cmake in your project but we don't encourage this as to ensure you keep uptodate with latest fixes.

After adding CPM.cmake, add the following line to the CMakeLists.txt.

include(CPM)
CPMAddPackage("gh:BareCpper/Version.cmake")

You may wish to optionally set the PROJECT version on the project(...). If so we recommend checking VERSION_SET == True:

if ( NOT VERSION_SET )
    message( FATAL_ERROR "Version.cmake is required")
endif()
project( MyProject VERSION ${VERSION_SEMANTIC} )

To use the Version information within a cmake build target:

Add version::version to the target_link_libraries for the target library/executable etc
Add Version.h via the #include directive
Use the VERSION_<field> preprocessor values in your code
💎 The default template .in defines C-preprocessor directives. For Modern C++ we intent to support constexpr constants in an upcoming release.

target_link_libraries( MyLibrary
    PRIVATE
        version::version
)

#include "Version.h"

Small and reusable so can be added to any CMake build
No re-configuring of CMake project necessary as the build-time step will udpate version information for your build transparently.
...lots more to think about & list