Version.cmake

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

Prerequisites

1. Use CMake to build your project.
2. Use Git as your code repository
   💡 If you are using a different SCM please raise an issue
3. Structure your project. See Here.
4. Use modern CMake features like targets and properties. See here and here.
5. Understand semantic versioning here and here.
6. 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'
7. Use a 'Prefix' for your project options in CMake options:
   💎 Instead of BUILD_TESTING use MYLIBRARY_BUILD_TESTING

Output Variables

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

Adding Version.cmake

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.

Basic Usage

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:

1. Add version::version to the target_link_libraries for the target library/executable etc
2. Add Version.h via the #include directive
3. 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"

Advantages

• 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

Limitations

• No support for Native NDK Service
• TODO raise an issue