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)
- Docker - for the development environment
- CMake 3.25+ - only needed if building outside Docker
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.shYour project directory is mounted at /project inside the container.
Clean up when done:
./docker/docker_clean.shAs 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.
- Open the project in VS Code
- Ctrl+Shift+P -> Dev Containers: Reopen in Container
The container uses docker/Dockerfile (same as docker_run.sh).
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 releaseOr for a debug build with symbols:
cmake --preset debug
cmake --build --preset debugOr for AddressSanitizer:
cmake --preset asan
cmake --build --preset asanRun the executable:
./build/release/cpp-project-template
# or
./build/debug/cpp-project-template
# or
./build/asan/cpp-project-templateClean build outputs:
rm -rf buildUnit 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 testsThe tests-asan preset builds in build/tests-asan and AddressSanitizer/UBSan instrumentation.
cmake --preset tests-asan
cmake --build --preset tests-asan
ctest --preset tests-asanThe tests-tsan preset builds in build/tests-tsan and ThreadSanitizer instrumentation.
cmake --preset tests-tsan
cmake --build --preset tests-tsan
ctest --preset tests-tsanThe 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-memcheckBenchmarks 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-reportThe 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 performanceOptional 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.txtThe 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-reportThe last step writes an HTML report to build/tests-coverage/coverage-report/index.html.
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-tidyFiles 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-tidyStatic 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 cppcheckJob count defaults to the CPU count; set it at configure time with -DCPPCHECK_JOBS=8:
cmake --preset cppcheck -DCPPCHECK_JOBS=8
cmake --build --preset cppcheckThe 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 withnpx, 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-checkor
cmake -P cmake/format.cmakeVS 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
|-- 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
See CONTRIBUTING.md and CODE_STYLE.md.
Apache License 2.0 - see LICENSE.