Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

cpp-project-template

A minimal C++ project template with CMake, Docker-based development environment, and VS Code Dev Containers support.

Stack: C++26, CMake 3.25+, Ubuntu 26.04 (GCC, clang-tidy, cppcheck, CMake, Git, Node.js for prettier, shfmt)

Build Release Unit Tests (ASan) Unit Tests (TSan) Unit Tests (Valgrind Memcheck) Coverage Static Analysis Format Benchmarks

Prerequisites

  • Docker - for the development environment
  • CMake 3.25+ - only needed if building outside Docker

Development environment

Docker provides a consistent build environment. Scripts live in docker/:

Script Purpose
docker_run.sh Start an interactive shell (builds the image on first run)
docker_build.sh Rebuild the cpp-env image
docker_clean.sh Stop containers and remove the cpp-env image

Start the environment from the project root:

./docker/docker_run.sh

Your project directory is mounted at /project inside the container.

Clean up when done:

./docker/docker_clean.sh

VS Code Dev Containers

As an alternative to starting Docker manually, VS Code can configure the environment automatically using the Dev Containers extension. It opens the project in the same Docker image and installs the C++, CMake, Prettier and shfmt extensions.

  1. Open the project in VS Code
  2. Ctrl+Shift+P -> Dev Containers: Reopen in Container

The container uses docker/Dockerfile (same as docker_run.sh).

Build

CMake is the build system. Presets are defined in CMakePresets.json:

Preset Output directory Description
release build/release Optimized build
relwithdebinfo build/relwithdebinfo Optimized build with debug symbols and frame pointers
debug build/debug Unoptimized build with debug symbols
tests build/tests Inherits debug with unit tests enabled
asan build/asan Sanitizer-instrumented build
tests-asan build/tests-asan Inherits asan with unit tests enabled
tsan build/tsan ThreadSanitizer-instrumented build
tests-tsan build/tests-tsan Inherits tsan with unit tests enabled
tests-valgrind-memcheck build/tests-valgrind-memcheck Inherits debug with unit tests under Valgrind Memcheck
tests-coverage build/tests-coverage Inherits debug with tests and coverage instrumentation
clang-tidy build/clang-tidy Inherits debug with clang-tidy
cppcheck build/cppcheck Inherits debug with cppcheck
benchmarks build/benchmarks Inherits relwithdebinfo with Google Benchmark targets enabled

From inside the container (or locally with CMake installed):

cmake --preset release
cmake --build --preset release

Or for a debug build with symbols:

cmake --preset debug
cmake --build --preset debug

Or for AddressSanitizer:

cmake --preset asan
cmake --build --preset asan

Run the executable:

./build/release/cpp-project-template
# or
./build/debug/cpp-project-template
# or
./build/asan/cpp-project-template

Clean build outputs:

rm -rf build

Testing

Unit tests use Google Test, fetched automatically by CMake. The tests preset builds in build/tests with the same flags as debug.

cmake --preset tests
cmake --build --preset tests
ctest --preset tests

The tests-asan preset builds in build/tests-asan and AddressSanitizer/UBSan instrumentation.

cmake --preset tests-asan
cmake --build --preset tests-asan
ctest --preset tests-asan

The tests-tsan preset builds in build/tests-tsan and ThreadSanitizer instrumentation.

cmake --preset tests-tsan
cmake --build --preset tests-tsan
ctest --preset tests-tsan

The tests-valgrind-memcheck preset builds in build/tests-valgrind-memcheck and runs each test under Valgrind Memcheck.

cmake --preset tests-valgrind-memcheck
cmake --build --preset tests-valgrind-memcheck
ctest --preset tests-valgrind-memcheck

Benchmarks

Benchmarks use Google Benchmark, fetched automatically by CMake. The benchmarks preset builds in build/benchmarks with BUILD_BENCHMARKS enabled and RelWithDebInfo (-O3 -g -fno-omit-frame-pointer) so timings stay optimized while perf can resolve symbols and unwind stacks.

cmake --preset benchmarks
cmake --build --preset benchmarks
cmake --build --preset benchmarks-report

The benchmarks-report preset builds any missing benchmark binaries and runs them all (equivalent to invoking each *_benchmark executable under build/benchmarks/). Each benchmark runs once, and each binary writes its results to build/benchmarks/benchmark-results/<binary>.json.

May need to disable CPU scaling:

sudo cpupower frequency-set -g performance

Optional Linux perf wrapping (may need elevated privileges):

sudo perf stat ./build/benchmarks/my_component_add_benchmark
sudo perf record -g ./build/benchmarks/my_component_add_benchmark
sudo perf report
sudo perf report --stdio > perf_report.txt

Coverage

The tests-coverage preset builds the src/ targets with GCC coverage instrumentation (--coverage) and enables the unit tests. Coverage is scoped to src/ - the report filters out test sources and Google Test headers.

Configure, build, and run the tests to produce coverage data, then build the coverage-report preset. That step prints coverage summaries with lcov and generates an HTML report with genhtml (included in the Docker image):

cmake --preset tests-coverage
cmake --build --preset tests-coverage
ctest --preset tests-coverage
cmake --build --preset coverage-report

The last step writes an HTML report to build/tests-coverage/coverage-report/index.html.

Clang-Tidy

Static analysis uses clang-tidy with the project .clang-tidy config. Analysis is scoped to src/ and uses compile_commands.json from the clang-tidy preset (included in the Docker image).

Configure, then run the clang-tidy build preset:

cmake --preset clang-tidy
cmake --build --preset clang-tidy

Files are analyzed in parallel via run-clang-tidy. Job count defaults to the CPU count; set it at configure time with -DCLANG_TIDY_JOBS=8:

cmake --preset clang-tidy -DCLANG_TIDY_JOBS=8
cmake --build --preset clang-tidy

Cppcheck

Static analysis uses Cppcheck. Analysis is scoped to src/ and uses compile_commands.json from the cppcheck preset (included in the Docker image). Enabled severities are warning, style, performance, and portability. Findings fail the build.

Configure, then run the cppcheck build preset:

cmake --preset cppcheck
cmake --build --preset cppcheck

Job count defaults to the CPU count; set it at configure time with -DCPPCHECK_JOBS=8:

cmake --preset cppcheck -DCPPCHECK_JOBS=8
cmake --build --preset cppcheck

Formatting

The format-check build preset checks all git-tracked files without modifying them and fails on any violation:

  • C++ files (*.cpp, *.cc, *.h, *.hpp) with clang-format, using the project .clang-format.
  • CMake files (CMakeLists.txt, *.cmake) with cmake-format, using the project .cmake-format.yaml.
  • JSON, YAML and Markdown files (*.json, *.yml, *.yaml, *.md) with prettier, using the project .prettierrc.json. The pinned prettier version is fetched with npx, so Node.js is required (installed in the Docker image).
  • Shell scripts (*.sh) with shfmt, using the indentation settings from the project .editorconfig.
cmake --preset debug
cmake --build --preset format-check

or

cmake -P cmake/format.cmake

VS Code formats on save when the project extensions are installed (see .devcontainer/devcontainer.json). To format from the command line:

clang-format -i file.cpp file.h
cmake-format -i CMakeLists.txt
prettier --write file.md file.json file.yaml
shfmt -w script.sh

Project layout

|-- CMakeLists.txt            # Root project configuration, warnings, and custom targets
|-- CMakePresets.json         # Configure, build, and test presets
|-- build/                    # Generated build output (gitignored)
|-- src/                      # Application sources and component libraries
|   |-- main.cpp              # Application entry point
|   |-- <component>/          # One library per component (.h, .cpp, CMakeLists.txt)
|-- tests/                    # Google Test binaries, mirroring src/ components
|-- benchmarks/               # Google Benchmark binaries, mirroring src/ components
|-- cmake/                    # CMake modules and development scripts
|-- docker/                   # Dockerfile and helper scripts
|-- .devcontainer/            # VS Code Dev Container configuration
|-- doc/design/               # Design documents
|-- .github/workflows/        # CI workflows

Contributing

See CONTRIBUTING.md and CODE_STYLE.md.

License

Apache License 2.0 - see LICENSE.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages