https://github.com/tomasmark79/dotnamecpp

A keyboard-driven, CMake-based C++ template for VSCode. It automates the full dev cycle (configure, build, test, format, docs, package) via shortcuts and works cross-platform.
https://github.com/tomasmark79/dotnamecpp
boilerplate-template cmake compiler conan cpp cross cross-platform emscripten exe gcc modern-cpp project-template toolchain vscode wasm
Last synced: 11 days ago
JSON representation
A keyboard-driven, CMake-based C++ template for VSCode. It automates the full dev cycle (configure, build, test, format, docs, package) via shortcuts and works cross-platform.
Host: GitHub
URL: https://github.com/tomasmark79/dotnamecpp
Owner: tomasmark79
License: other
Created: 2025-09-10T11:01:10.000Z (8 months ago)
Default Branch: main
Last Pushed: 2026-02-04T19:46:42.000Z (3 months ago)
Last Synced: 2026-02-05T07:48:16.720Z (3 months ago)
Topics: boilerplate-template, cmake, compiler, conan, cpp, cross, cross-platform, emscripten, exe, gcc, modern-cpp, project-template, toolchain, vscode, wasm
Language: C++
Homepage: https://digitalspace.name
Size: 5.23 MB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

            

      

# DotNameCpp — Advanced C++ Development Template

> 🌱 **Help Keep This Going** - Your support makes a real difference. If you value my work and want to help me continue creating, please consider making a donation. 💙 **Donate here:** [https://paypal.me/TomasMark](https://paypal.me/TomasMark) - Every contribution is truly appreciated ✨  

## Time to Step Ahead

Given the cognitive complexity of the DotNameCpp template, I have decided to move forward and use native NixOS and Meson for configuring new C++ projects starting in 2026. [The new NixonCpp template is here](https://github.com/tomasmark79/NixonCpp).

## Table of Contents

- [Overview](#overview)

- [Quick Start](#quick-start)

- [VSCode Keyboard Workflow](#vscode-keyboard-workflow)

- [Build Methods](#build-methods)

- [Prerequisites](#prerequisites)

- [Development Tools](#development-tools)

- [Maintenance Scripts](#maintenance-scripts)

- [License](#license)

---

## Overview

**A keyboard-driven, CMake-based C++ template for VSCode**. It automates the full dev cycle (configure, build, test, format, docs, package) via shortcuts and works cross-platform.

> 🐧 **Primary Development Platform**: This template is now primarily developed on **NixOS**. Nix shell (`flake.nix` / `shell.nix`) provides a reproducible development environment with all required dependencies. For other distributions, standard package managers can be used.

### Why?

- **Keyboard-first**: One shortcut → structured task chain

- **Modern stack**: CMake presets + Conan 2 + cross/wasm support

- **Built-in quality**: clang-format, clang-tidy, coverage, Doxygen

- **Dual target**: Reusable library + application

---

## Quick Start

### [Open Doxygen Docs Online](https://tomasmark79.github.io/DotNameCpp/html/index.html)  

### Clone Template

```bash

git clone git@github.com:tomasmark79/DotNameCpp.git

```

**Quick clone with auto-rename** - add to your `.bashrc` / `.zshrc`:

```bash

clonedotname() {

    local PN="${1:-DotNameCpp}"

    git clone git@github.com:tomasmark79/DotNameCpp.git "$PN" && \

    rm -rf "$PN/.git" && \

    cd "$PN" && \

    python SolutionRenamer.py DotNameLib "$PN"Lib DotNameApplication "$PN"App && \

    code .

}

```

Then use: `clonedotname MyProject`

### Recommended: VSCode Workflow

Open in VSCode and use keyboard shortcuts:

```text

Shift+F7 → "Zero to Hero"    # Complete setup, build, test, package

F7                              # Quick rebuild

F5                              # Start debugging

```

### GitHub Codespaces

Click **Code** → **Codespaces** → **Create codespace** on GitHub for instant cloud environment.

---

## VSCode Keyboard Workflow

Keyboard-first development: every major action = shortcut → menu → deterministic scripted sequence.

### Core Development Shortcuts

| Shortcut | Action | Description |

|----------|--------|-------------|

| **F5** | Quick Debug | Start debugging application |

| **F7** | Quick Build | Build application (default Debug) |

| **Shift+F7** | Build Menu | **PRIMARY BUILD WORKFLOW** - Access all build tasks |

| **Ctrl+F7** | Other Tasks | Utilities, formatting, documentation, coverage |

| **Ctrl+Alt+R** | Run Application | Execute the built application binary |

| **Ctrl+Alt+E** | Launch Emscripten | Build and serve WebAssembly version |

| **Ctrl+Alt+P** | Build All Presets | Build all CMake presets |

### Build Tasks Menu (Shift+F7)

The **primary development workflow** - this menu contains all essential build operations:

- **Zero to Build**: Complete clean build workflow

- **Zero to Hero**: Full development cycle (build, test, package)

- **Conan Install**: Install/update dependencies

- **CMake Configure**: Configure build system

- **CMake Configure with Coverage**: Configure with code coverage

- **Build**: Compile the project

- **Run Tests**: Execute test suite

- **Clean selected folder**: Clean build artifacts

- **Install built components**: Install built components

- **Create Tarballs**: Package for distribution

### Utility Tasks Menu (Ctrl+F7)

Secondary workflow for code quality and maintenance:

- **Format Code**: Apply clang-format to all C++ files

- **Format CMake**: Format all CMake files

- **clang-tidy linting**: Run static analysis

- **Generate Documentation**: Create Doxygen docs

- **Coverage Tasks from Other Menu**: Quick access to coverage analysis

- **Build All CMakeUserPresets.json**: Build all presets

### Code Quality Shortcuts

| Shortcut | Action | Description |

|----------|--------|-------------|

| **Ctrl+Alt+F** | Format Code | Run clang-format recursively on whole project |

| **Ctrl+Alt+L** | Lint Code | Run clang-tidy analysis |

| **Ctrl+Alt+M** | Format CMake | Run cmake-format recursively on CMake files |

### Coverage Analysis Shortcuts

| Shortcut | Action | Description |

|----------|--------|-------------|

| **Ctrl+Alt+Shift+C** | Configure with Coverage | Configure build with coverage enabled |

| **Ctrl+Alt+H** | Coverage HTML Report | Generate and open HTML coverage report |

| **Ctrl+Alt+Shift+H** | Coverage Full Report | Generate both HTML and XML coverage reports |

| **Ctrl+Alt+T** | Coverage Tasks from Other Menu | Show detailed coverage task options |

### Recommended Development Flow

1. First run: `Shift+F7` → "Zero to Hero" (installs, configures, builds, tests, packages)

2. Iterate: `F7` build → `F5` debug → edit → repeat

3. Quality: `Ctrl+F7` utilities (format / tidy / docs)

4. Tests: `Shift+F7` → "Run Tests"

5. Coverage (native default only): `Ctrl+Alt+H`

### Pro Tips

- Shortcuts configurable via `.vscode/keybindings.json`

- Works identically across Linux / macOS / Windows (and wasm where applicable)

---

## Build Methods

### Method 1: VSCode Shortcuts (Recommended)

Use the keyboard shortcuts detailed in the [VSCode Keyboard Workflow](#vscode-keyboard-workflow) section for a seamless development experience.

> **💡 Note:** All build operations are orchestrated by `SolutionController.py`, which handles Conan dependencies, CMake configuration, and build execution automatically. The raw commands shown in Method 2 are provided for reference and advanced users only - in normal workflow, you simply use VSCode shortcuts and the controller manages everything for you.

### Method 2: CMake + Conan (Raw Commands)

> **⚠️ Advanced Users Only:** These raw commands are typically **not needed** - `SolutionController.py` (invoked via VSCode shortcuts) handles all of this automatically. Use these only for manual control, CI/CD pipelines, or understanding the build process internals.

#### Native Builds

```bash

# Linux/macOS - Complete workflow

conan install . --output-folder=build/application/default/debug \

  -s build_type=Debug -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/default/debug --config Debug -j $(nproc)

ctest --test-dir build/application/default/debug

```

```powershell

# Windows (PowerShell)

conan install . --output-folder=build/application/default/debug `

  -s build_type=Debug -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/debug `

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/debug/conan_toolchain.cmake `

  -DCMAKE_BUILD_TYPE=Debug `

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/default/debug --config Debug

ctest --test-dir build/application/default/debug

```

#### Cross-Compilation Examples

```bash

# Emscripten (WebAssembly)

conan install . --output-folder=build/application/emscripten/debug \

  -s build_type=Debug -s compiler.cppstd=20 \

  -pr:host=emscripten -pr:build=default -b=missing

source build/application/emscripten/debug/conanbuild.sh

cmake -B build/application/emscripten/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/emscripten/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON \

  -DPLATFORM=Web

cmake --build build/application/emscripten/debug

# MinGW (Windows cross-compile from Linux)

conan install . --output-folder=build/application/x86_64_w64_mingw32/debug \

  -s build_type=Debug -s compiler.cppstd=20 \

  -pr:host=x86_64_w64_mingw32 -pr:build=default -b=missing

source build/application/x86_64_w64_mingw32/debug/conanbuild.sh

cmake -B build/application/x86_64_w64_mingw32/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/x86_64_w64_mingw32/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/x86_64_w64_mingw32/debug

# ARM64/aarch64 (Raspberry Pi cross-compile from Linux)

conan install . --output-folder=build/application/rpi4_glibc2.36_gcc12.4/debug \

  -s build_type=Debug -s compiler.cppstd=20 \

  -pr:host=rpi4_glibc2.36_gcc12.4 -pr:build=default -b=missing

source build/application/rpi4_glibc2.36_gcc12.4/debug/conanbuild.sh

cmake -B build/application/rpi4_glibc2.36_gcc12.4/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/rpi4_glibc2.36_gcc12.4/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/rpi4_glibc2.36_gcc12.4/debug

```

#### Build Type Variations

```bash

# Release build

conan install . --output-folder=build/application/default/release \

  -s build_type=Release -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/release \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/release/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Release \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/default/release --config Release

# Release with Debug Info

conan install . --output-folder=build/application/default/relwithdebinfo \

  -s build_type=RelWithDebInfo -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/relwithdebinfo \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/relwithdebinfo/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=RelWithDebInfo \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/default/relwithdebinfo

# Minimum Size Release

conan install . --output-folder=build/application/default/minsizerel \

  -s build_type=MinSizeRel -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/minsizerel \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/minsizerel/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=MinSizeRel \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON

cmake --build build/application/default/minsizerel

```

#### Advanced Options

```bash

# Code coverage (native Debug builds only)

conan install . --output-folder=build/application/default/debug \

  -s build_type=Debug -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/application/default/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON \

  -DENABLE_COVERAGE=ON

cmake --build build/application/default/debug

ctest --test-dir build/application/default/debug

gcovr --html-details coverage.html --root .

# With sanitizers (Debug only)

cmake -B build/application/default/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON \

  -DSANITIZER_MODE=3  # ASAN + UBSAN

# With Link-Time Optimization (Release builds)

cmake -B build/application/default/release \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/release/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Release \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON \

  -DENABLE_IPO=ON

# With hardening enabled

cmake -B build/application/default/release \

  -DCMAKE_TOOLCHAIN_FILE=build/application/default/release/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Release \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=ON \

  -DENABLE_HARDENING=ON

# Library only build

conan install . --output-folder=build/library/default/debug \

  -s build_type=Debug -s compiler.cppstd=20 -pr default -b=missing

cmake -B build/library/default/debug \

  -DCMAKE_TOOLCHAIN_FILE=build/library/default/debug/conan_toolchain.cmake \

  -DCMAKE_BUILD_TYPE=Debug \

  -DBUILD_LIBRARY=ON -DBUILD_APPLICATION=OFF

cmake --build build/library/default/debug

```

#### Utility Commands

```bash

# List available CMake presets

cmake --list-presets

# Clean build

rm -rf build/application/default/debug

cmake --build build/application/default/debug --target clean

# Install built artifacts

cmake --install build/application/default/debug --prefix install

# Create distribution package

cd build/application/default/debug

cpack -G TGZ

# Run specific test

ctest --test-dir build/application/default/debug -R TestName

# Verbose build output

cmake --build build/application/default/debug --verbose

# Show Conan profile

conan profile show --profile default

conan profile show --profile x86_64_w64_mingw32

```

### Build Options

```cmake

option(ENABLE_GTESTS "Build and run unit tests" ON)

option(ENABLE_CCACHE "Use ccache compiler cache" ON)

option(ENABLE_COVERAGE "Enable code coverage analysis" OFF)

option(ENABLE_IPO "Enable link-time optimization" OFF)

option(ENABLE_HARDENING "Enable security hardening" OFF)

# Sanitizer configuration

# SANITIZER_MODE values:

#   0 = None           - No sanitizers

#   1 = ASAN           - Address Sanitizer

#   2 = UBSAN          - Undefined Behavior Sanitizer

#   3 = ASAN + UBSAN   - Address + Undefined

#   4 = TSAN           - Thread Sanitizer

#   5 = TSAN + UBSAN   - Thread + Undefined

# Note: ASAN and TSAN are mutually exclusive

set(SANITIZER_MODE 0 CACHE STRING "Sanitizer mode (0-5)")

```

---

## Prerequisites

### Essential Tools

| Tool | Minimum Version | Purpose | Installation |

|------|----------------|---------|--------------|

| **Git** | 2.25+ | Version control | [Download](https://git-scm.com/downloads) |

| **CMake** | 3.31+ | Build system | [Download](https://cmake.org/download/) |

| **Conan** | 2.0+ | Package manager | `pip install conan` |

| **Python** | 3.8+ | Automation scripts | [Download](https://python.org) |

| **Ninja** | 1.10+ | Build tool | [Download](https://ninja-build.org/) |

| **VSCode** | Latest | IDE | [Download](https://code.visualstudio.com/) |

### Recommended Tools

| Tool | Purpose | Installation |

|------|---------|--------------|

| **ccache** | Compilation cache | [Download](https://ccache.dev/download.html) |

| **clang-tidy** | Static analysis | Part of LLVM |

| **clang-format** | Code formatting | Part of LLVM (base config: `clang-format -style=llvm -dump-config > .clang-format` + small individual adjustments) |

| **cmake-format** | CMake formatting | `pip install cmake-format` |

| **Doxygen** | Documentation | [Download](https://www.doxygen.nl/download.html) |

| **gcovr** | Code coverage | `pip install gcovr` |

| **Emscripten** | WebAssembly compilation | [Download](https://emscripten.org/docs/getting_started/downloads.html) |

### Supported Compilers

| Platform | Compilers | Versions |

|----------|-----------|----------|

| **Linux** | GCC, Clang | GCC 11+, Clang 14+ |

| **macOS** | Clang, GCC | Xcode 14+, GCC 11+ |

| **Windows** | MSVC, Clang, GCC | VS 2022, Clang 14+, MinGW 11+ |

| **Emscripten** | emcc | 3.1.0+ |

### CMake Dependencies (Forked for Stability)

This project uses forked versions of key CMake utilities hosted on the maintainer's GitHub for future stability and version control:

- **[CPM.cmake](https://github.com/tomasmark79/CPM.cmake)** - CMake package manager for automated dependency fetching

> **Useful CMake Snippets** Check out [useful CMake snippets](cmake/useful-cmake-snippets.md) for integrating popular libraries using CPM.cmake.

- **[PackageProject.cmake](https://github.com/tomasmark79/PackageProject.cmake)** - CMake library packaging and installation helper

- **[CPMLicenses.cmake](https://github.com/tomasmark79/CPMLicenses.cmake)** - Automated third-party license collection

> **Note:** These forks ensure long-term stability and allow for custom modifications if upstream changes break compatibility. The original projects are properly credited in respective repositories.

 

---

## Development Tools

**Static Analysis**: `Ctrl+Alt+L` (clang-tidy - requires build artifacts)  

**Code Formatting**: `Ctrl+Alt+F` (C++), `Ctrl+Alt+M` (CMake)  

**Documentation**: `Ctrl+F7` → "Generate Documentation" (Doxygen)  

**Code Coverage**: `Ctrl+Alt+H` (native builds only)

---

## Maintenance Scripts

#### SolutionRenamer.py

Rename project from template defaults:

```bash

python3 SolutionRenamer.py DotNameLib NewAwesomeLib DotNameApplication NewAwesomeApplication

```

#### SolutionUpgrader.py

Sync files from upstream template:

```bash

python SolutionUpgrader.py -i    # Interactive mode

python SolutionUpgrader.py -c    # Check for updates

python SolutionUpgrader.py -u README.md  # Update specific file

```

#### SolutionController.py

Central automation hub (normally accessed via VSCode shortcuts):

```bash

python SolutionController.py  ""  [build_type]

# Examples:

python SolutionController.py application "Build" default Debug

python SolutionController.py both "Zero to Hero" default Release

```

---

## License

**MIT License**  

Copyright (c) 2024–2026 Tomáš Mark

---

## Important Notes

- **Coverage**: Native `default` Debug builds only

- **Emscripten**: Requires appropriate Conan profile (not auto-installed)

- **Cross-compilation**: Conan profiles must be created manually

- **CI/CD**: See badges at top for current build status

For support: [Open an issue](https://github.com/tomasmark79/DotNameCpp/issues) · [Discussions](https://github.com/tomasmark79/DotNameCpp/discussions)

---

**Happy coding!**

[Back to top](#dotnamecpp--advanced-c-development-template)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/tomasmark79/dotnamecpp

Awesome Lists containing this project

README
