cmake-project-template

A CMake project template providing version management, quick build/install APIs, and standardized C++ library creation utilities.

Features

• Version Management - Automatic version extraction from git tags (format: vX.Y.Z)
• Library Creation Utilities - Simplified static, shared, and header-only library creation
• Code Formatting - Integrated clang-format support
• Testing Support - Built-in unit test scaffolding
• Install Support - CMake find_package() compatible installation

Quick Start

# Configure
cmake -B build -G Ninja

# Build
cmake --build build

# Install
cmake --install build

# Run tests
cmake -B build -G Ninja -Dmyproject_BUILD_TESTS=ON
ctest --test-dir build

# Format code
cmake --build build --target format

Options

Option	Description	Default
myproject_BUILD_TESTS	Build unit tests	OFF
myproject_BUILD_EXAMPLES	Build examples	OFF
myproject_BUILD_SHARED	Build shared libraries	OFF

Version

Project version is automatically derived from git tags:

git tag v1.0.0
git tag v1.2.3

CMake Utilities (xc_utils.cmake)

Configuration Variables

Variable	Description	Default
DEFAULT_NAMESPACE	Default namespace for libraries	CMAKE_PROJECT_NAME
TEST_PREFIX	Prefix for test executables	test_
TEST_SUFFIX	Suffix for test executables	""
BUILD_SHARED	Build shared libraries	OFF
${PROJECT_NAME}_BUILD_SHARED	Override BUILD_SHARED per project	-
${PROJECT_NAME}_MODIFY_OUTPUT_PREFIX	Add namespace prefix to output name	ON

Library Creation Functions

xc_add_static_library(TARGET SRCDIR)

Create a static library.

xc_add_static_library(hello hello)
xc_add_static_library(hello hello NAMESPACE myproject)
xc_add_static_library(hello hello PUBLIC_LINK otherlib PRIVATE_INCLUDE /path/to/include)

Options:

• NAMESPACE name - Specify namespace
• PUBLIC_LINK lib - Public link library
• PRIVATE_LINK lib - Private link library
• INTERFACE_LINK lib - Interface link library
• PUBLIC_INCLUDE path - Public include directory
• PRIVATE_INCLUDE path - Private include directory
• INTERFACE_INCLUDE path - Interface include directory

xc_add_shared_library(TARGET SRCDIR)

Create a shared library.

xc_add_shared_library(mylib src)
xc_add_shared_library(mylib src NAMESPACE myproject)

Same options as xc_add_static_library.

xc_add_library(TARGET SRCDIR)

Create static or shared library based on BUILD_SHARED variable.

xc_add_library(mylib src)

xc_add_header_library(TARGET INCDIR)

Create a header-only library.

xc_add_header_library(mylib include)
xc_add_header_library(mylib include NAMESPACE myproject)

Testing Functions

xc_add_test(NAME SOURCES)

Create a unit test.

xc_add_test(mytest test.cc)
xc_add_test(mytest test.cc PUBLIC_INCLUDE /path/to/include)
xc_add_test(mytest test.cc PRIVATE_LINK mylib PUBLIC_INCLUDE /path/to/include)
xc_add_test(mytest test.cc TARGET_OUTPUT test_exe)

Options:

• TARGET_OUTPUT outvar - Output variable to receive test executable name
• PUBLIC_LINK lib - Public link library
• PRIVATE_LINK lib - Private link library
• INTERFACE_LINK lib - Interface link library
• PUBLIC_INCLUDE path - Public include directory
• PRIVATE_INCLUDE path - Private include directory
• INTERFACE_INCLUDE path - Interface include directory

Source Management

xc_target_source(TARGET DIR)

Add source files to target.

xc_target_source(my_target src)
xc_target_source(my_target src NORECURSIVE)
xc_target_source(my_target src EXCLUDE_PATH "test" EXCLUDE_PATH "mock")
xc_target_source(my_target src EXTSRC extra.cpp)

Options:

• NORECURSIVE - Non-recursive search
• EXCLUDE_PATH path - Exclude files matching path
• EXTSRC file - Add extra source files

Formatting

xc_add_format_dir(DIR)

Add directory to the list of directories to be formatted.

xc_add_format_dir(${CMAKE_SOURCE_DIR}/src)
xc_add_format_dir(${CMAKE_SOURCE_DIR}/include)

Then run formatting with:

cmake --build build --target format

Version Management (get_version.cmake)

xc_get_project_version(VERSION_VAR)

Get project version from latest git tag.

include(cmake/get_version.cmake)
xc_get_project_version(PROJECT_VERSION)
project(myproject LANGUAGES CXX VERSION ${PROJECT_VERSION})

Version is extracted from tags in format vX.Y.Z (e.g., v1.2.3 -> 1.2.3).

Project Structure

.
├── CMakeLists.txt           # Main CMake configuration
├── cmake/                   # CMake modules
│   ├── xc_utils.cmake      # Library creation utilities
│   ├── get_version.cmake   # Version management
│   ├── formate.cmake       # Code formatting
│   ├── install_deps.cmake  # Dependency installation
│   └── myprojectConfig.cmake.in
├── myproject/              # Main library code
│   └── CMakeLists.txt
├── test/                   # Unit tests
│   └── CMakeLists.txt
└── .clang-format          # Code style configuration

License

MIT