# cmake-project-template

**Repository Path**: xcrtp/cmake-project-template

## Basic Information

- **Project Name**: cmake-project-template
- **Description**: A CMake Project Template.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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

```bash
# 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:

```bash
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.

```cmake
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.

```cmake
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.

```cmake
xc_add_library(mylib src)
```

#### xc_add_header_library(TARGET INCDIR)

Create a header-only library.

```cmake
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.

```cmake
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.

```cmake
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.

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

Then run formatting with:
```bash
cmake --build build --target format
```

## Version Management (get_version.cmake)

#### xc_get_project_version(VERSION_VAR)

Get project version from latest git tag.

```cmake
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