Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tomasmark79/dotnamecpp-pub

Public version of DotNameCpp - production-ready C++ development template designed for rapid project initialization with modern tooling, cross-platform support, and automated workflows
https://github.com/tomasmark79/dotnamecpp-pub

automated-testing boilerplate clang-tidy cmake conan cpp cpp-template cross-platform doxygen emscripten github-actions googletest modern-cpp ninja production-ready project-template static-analysis vscode webassembly

Last synced: about 1 month ago
JSON representation

Public version of DotNameCpp - production-ready C++ development template designed for rapid project initialization with modern tooling, cross-platform support, and automated workflows

Awesome Lists containing this project

README 

          



# DotNameCpp - Advanced C++ Development Template



A comprehensive, production-ready C++ development template designed for rapid project initialization with modern tooling, cross-platform support, and automated workflows. This template provides everything needed to start developing native and cross-platform C++ applications efficiently and cleanly.



   



---



> **Expert Assessment**: *"This C++ template achieves production-grade quality with exceptional CMake organization, comprehensive tooling integration, and modern development practices. The automated workflows, cross-platform support, and developer experience represent industry best practices."* - GitHub Copilot (2025)



## ๐Ÿ› ๏ธ Implementation Details



### โœ… Completed Features (2023-2025)

- **Multi-platform CI/CD**: Full GitHub Actions integration for Linux, macOS, Windows

- **Code Coverage**: Comprehensive gcovr integration with HTML/XML reports

- **WebAssembly Support**: Complete Emscripten integration with live demos

- **Development Tools**: clang-tidy, clang-format, cmake-format automation

- **VSCode Integration**: Extensive keyboard shortcuts and task automation

- **Cross-Toolchain Management**: Seamless integration with popular C++ toolchains

- **Container Support**: Complete Docker environment with multi-stage builds



### ๐Ÿšง Current Limitations

- **Coverage Analysis**: Only available for native builds (`default` architecture)

- **Help System**: SolutionController.py help documentation planned but not yet started



### ๐ŸŽฏ Upcoming Features (2025+)

- Enhanced container development workflows

- Performance profiling integration

- Creation of Conan Package from the project



---



## ๐Ÿ“š Table of Contents



- [๐Ÿš€ Overview](#-overview)

- [โœจ Key Features](#-key-features)

- [โšก Quick Start](#-quick-start)

- [๐Ÿ› ๏ธ Prerequisites & Dependencies](#๏ธ-prerequisites--dependencies)

- [๐Ÿ—๏ธ Project Structure](#๏ธ-project-structure)

- [๐Ÿ”ง Build System](#-build-system)

- [๐Ÿ“ฆ Package Management](#-package-management)

- [๐Ÿงฐ Development Tools](#-development-tools)

- [๐Ÿ’ป IDE Integration](#-ide-integration)

- [๐ŸŒ Cross-Platform Development](#-cross-platform-development)

- [๐ŸŒ WebAssembly & Emscripten](#-webassembly--emscripten)

- [๐Ÿงช Testing Framework](#-testing-framework)

- [๐Ÿ“š Library Development](#-library-development)

- [๐Ÿ”„ CI/CD Pipeline](#-cicd-pipeline)

- [๐Ÿ› ๏ธ Maintenance & Utilities](#๏ธ-maintenance--utilities)

- [๐Ÿ“– Documentation](#-documentation)

- [๐Ÿ“„ License](#-license)



---



## ๐Ÿš€ Overview



**DotNameCpp** is more than just a project templateโ€”it's a complete development ecosystem that streamlines C++ development from conception to deployment. Designed with modern C++ best practices, it provides a robust foundation for both library and standalone application development.



This template has been crafted to eliminate the initial setup overhead that typically accompanies C++ projects, allowing developers to focus on writing code rather than configuring build systems and toolchains.



### ๐ŸŽฏ Design Philosophy



- **Zero-Configuration Start**: Get productive immediately with sensible defaults

- **Scalability**: Grows from simple prototypes to complex multi-platform applications

- **Developer Experience**: Prioritizes ease of use without sacrificing power

- **Modern Standards**: Embraces C++20/23 features and contemporary tooling

- **Production Ready**: Includes all necessary components for professional development



---



## โœจ Key Features



### ๐Ÿ—๏ธ **Advanced Build System**

- **CMake 3.31+** with modern preset system

- **Conan 2.0** integration for dependency management

- **Ninja** build system for fast compilation

- **ccache** support for accelerated rebuilds

- **Cross-compilation** ready with toolchain support



### ๐ŸŒ **Multi-Platform Support**

- **Native Development**: Linux, macOS, Windows

- **WebAssembly**: Emscripten integration for web deployment

- **Cross-Compilation**: ARM, x86, x64 architectures

- **Container Support**: Docker and GitHub Codespaces ready



### ๐Ÿงฐ **Development Tools Integration**

- **Static Analysis**: clang-tidy with comprehensive rule sets

- **Code Formatting**: clang-format and cmake-format

- **Documentation**: Doxygen with automated generation

- **Testing**: Google Test framework integration

- **Debugging**: GDB/LLDB support with VSCode integration

- **Debugging**: CMake files support with VSCode integration

- **Parallel Computing**: TBB (Threading Building Blocks) for Linux builds with execution policy support (requires `libtbb-dev` package)



### ๐Ÿ“ฆ **Project Flexibility**

- **Dual Structure**: Library and standalone application support

- **Modular Architecture**: Reusable components and utilities

- **Asset Management**: Integrated resource handling system

- **Licensing**: Built-in license collection and management



### ๐Ÿš€ **Automation & CI/CD**

- **GitHub Actions**: Multi-platform CI/CD pipelines

- **Automated Testing**: Unit tests, integration tests, and benchmarks

- **Release Management**: Automated packaging and distribution

- **Quality Gates**: Static analysis and code coverage integration



---



## โšก Quick Start



### ๐Ÿ› ๏ธ Clone the Repository



```bash

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

```



### ๐Ÿ› ๏ธ Clone the Repository with removal of .git with simple command

add this function to your `.bashrc` or `.zshrc`:



```bash

clonedotname() {

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

    git clone git@github.com:tomasmark79/DotNameCpp.git "$PN" && rm -rf "$PN/.git" && cd "$PN"

    python SolutionRenamer.py DotNameLib "$PN"Lib DotNameStandalone "$PN"Standalone

}

```



Then simply use:

```bash

clonedotname # Clone with default name "AppName"

clonedotname MyCustomAppName # Clone with custom name

```



### ๐Ÿ—๏ธ Quick Build



```bash

# Use the Python controller for advanced options - callable from VSCode tasks

python SolutionController.py standalone "๐Ÿ—ก๏ธ Conan install" default Debug

python SolutionController.py standalone "๐Ÿ”ง CMake configure" default Debug

python SolutionController.py standalone "๐Ÿ”จ Build" default Debug

```



### โ˜๏ธ GitHub Codespaces



```bash

pip install conan

conan profile detect

# Use the Python controller for advanced options - callable from VSCode tasks

python SolutionController.py standalone "๐Ÿ—ก๏ธ Conan install" default Debug

python SolutionController.py standalone "๐Ÿ”ง CMake configure" default Debug

python SolutionController.py standalone "๐Ÿ”จ Build" default Debug

```



Click the **Code** button on GitHub โ†’ **Codespaces** โ†’ **Create codespace** for instant cloud development environment.



### ๐Ÿš€ One-Command Development



```bash

# Zero to Hero: Complete setup, build, test, and package

python SolutionController.py both "๐Ÿฆธ Zero to Hero" default Debug

```



---



## ๐Ÿ› ๏ธ Prerequisites & Dependencies



### ๐Ÿ”ง 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/) |



### ๐Ÿ›ก๏ธ 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 |

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

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

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

| **TBB** | Parallel computing (Linux) | `sudo dnf install tbb-devel` (Fedora), `sudo apt install libtbb-dev` (Ubuntu) |



### ๐Ÿ’ป 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+ |



---



## ๐Ÿ—๏ธ Project Structure



```

๐Ÿ“ DotNameCpp/

โ”œโ”€โ”€ ๐Ÿ“ .github/                     # GitHub configuration files

โ”œโ”€โ”€ ๐Ÿ“ .vscode/                     # Visual Studio Code configuration

โ”œโ”€โ”€ ๐Ÿ“ assets/                      # Project resources

โ”‚   โ”œโ”€โ”€ customstrings.json          # Localization strings

โ”‚   โ”œโ”€โ”€ DotNameCppLogo.svg          # Project logo

โ”‚   โ””โ”€โ”€ ems-mini.html               # Emscripten template

โ”œโ”€โ”€ ๐Ÿ“ build/                       # Build outputs (auto-generated)

โ”‚   โ”œโ”€โ”€ ๐Ÿ“ installation/            # Installation artifacts

โ”‚   โ”œโ”€โ”€ ๐Ÿ“ standalone/              # Standalone builds

โ”‚   โ””โ”€โ”€ ๐Ÿ“ tarballs/                # Distribution packages

โ”œโ”€โ”€ ๐Ÿ“ cmake/                       # CMake modules and utilities

โ”‚   โ”œโ”€โ”€ project-common.cmake        # Common project settings

โ”‚   โ”œโ”€โ”€ project-library.cmake       # Library-specific configuration

โ”‚   โ”œโ”€โ”€ project-standalone.cmake    # Standalone app configuration

โ”‚   โ”œโ”€โ”€ tmplt-*.cmake               # Feature modules (sanitizers, hardening, etc.)

โ”‚   โ””โ”€โ”€ ๐Ÿ“ modules/                 # Custom CMake modules

โ”œโ”€โ”€ ๐Ÿ“ conan_tools/                 # Conan integration utilities

โ”œโ”€โ”€ ๐Ÿ“ doc/                         # Documentation (auto-generated)

โ”œโ”€โ”€ ๐Ÿ“ include/DotNameLib/          # Public library headers

โ”œโ”€โ”€ ๐Ÿ“ src/                         # Library source code

โ”‚   โ”œโ”€โ”€ DotNameLib.cpp              # Main library implementation

โ”‚   โ”œโ”€โ”€ ๐Ÿ“ Assets/                  # Asset management utilities

โ”‚   โ”œโ”€โ”€ ๐Ÿ“ Logger/                  # Logging functionality

โ”‚   โ””โ”€โ”€ ๐Ÿ“ Utils/                   # Utility classes

โ”œโ”€โ”€ ๐Ÿ“ standalone/                  # Standalone application

โ”‚   โ”œโ”€โ”€ ๐Ÿ“ src/                     # Application source

โ”‚   โ””โ”€โ”€ ๐Ÿ“ tests/                   # Application tests

โ”œโ”€โ”€ ๐Ÿ“„ CMakeLists.txt               # Root CMake configuration

โ”œโ”€โ”€ ๐Ÿ“„ CMakeUserPresets.json        # CMake presets for different configurations

โ”œโ”€โ”€ ๐Ÿ“„ conanfile.py                 # Conan dependency specification

โ”œโ”€โ”€ ๐Ÿ“„ SolutionController.py        # Main Template automation script

โ”œโ”€โ”€ ๐Ÿ“„ SolutionRenamer.py           # Template renaming utility

โ””โ”€โ”€ ๐Ÿ“„ SolutionUpgrader.py          # Template update utility

```



### ๐Ÿ“‚ Directory Purposes



- **`assets/`**: Static resources, configurations, and branding materials

- **`cmake/`**: Modular CMake configuration with reusable templates

- **`include/`**: Public API headers for library consumers

- **`src/`**: Library implementation with organized subsystems

- **`standalone/`**: Example application demonstrating library usage

- **`conan_tools/`**: Custom Conan integration and utility functions



---



## ๐Ÿ”ง Build System



### ๐ŸŽ›๏ธ CMake Presets System



The project uses CMake presets for consistent, reproducible builds across different environments:



```bash

# List available presets

cmake --list-presets



# Configure with a preset

cmake --preset debug-linux-x86_64-gcc-15



# Build with a preset

cmake --build --preset debug-linux-x86_64-gcc-15

```



### ๐Ÿ“‹ Available Build Presets



Depends on your toolchain configuration. Every new build configuration should be added to the `CMakeUserPresets.json` file.



### ๐Ÿ”ง Build Options



Configure your build with these CMake options:



```cmake

# Core options

option(BUILD_LIBRARY "Build the DotNameLib library" ON)

option(BUILD_STANDALONE "Build the standalone application" ON)

option(BUILD_TESTS "Build unit tests" OFF)

option(BUILD_DOCS "Generate documentation" OFF)



# Feature options

option(ENABLE_HARDENING "Enable security hardening" OFF)

option(ENABLE_SANITIZERS "Enable runtime sanitizers" OFF)

option(ENABLE_IPO "Enable interprocedural optimization" OFF)

option(ENABLE_CCACHE "Use ccache for compilation" ON)

option(ENABLE_COVERAGE "Enable code coverage analysis" OFF)



# Platform-specific options

option(EMSCRIPTEN_BUILD "Build for Emscripten/WebAssembly" OFF)

```



> **โš ๏ธ Important Coverage Note**: Code coverage analysis is **exclusively supported for native builds** using the `default` architecture. Cross-compilation targets (Emscripten, MinGW, ARM, etc.) cannot execute tests locally, therefore coverage data collection is not possible for these platforms. Always use native builds when coverage analysis is required.



### ๐Ÿš€ Advanced Build Commands



```bash

# Complete workflow: clean โ†’ configure โ†’ build โ†’ test โ†’ package

python SolutionController.py both "๐Ÿฆธ Zero to Hero" default Debug



# Quick rebuild default Debug

python SolutionController.py both "๐Ÿ”จ Build" default Debug



# Clean build for default Debug

python SolutionController.py both "๐Ÿงน Clean selected folder" default Debug



# Build with code coverage enabled

cmake --preset debug-linux-x86_64-gcc-15 -DENABLE_COVERAGE=ON

cmake --build --preset debug-linux-x86_64-gcc-15

ctest --preset debug-linux-x86_64-gcc-15

make coverage



# Coverage workflow with SolutionController

python SolutionController.py standalone "๐Ÿ“Š Configure with Coverage" default Debug

python SolutionController.py standalone "๐Ÿ”จ Build" default Debug

python SolutionController.py standalone "๐Ÿงช Run CTest" default Debug

python SolutionController.py standalone "๐Ÿ“Š Coverage HTML Report" default Debug



# Cross-compilation example

python SolutionController.py standalone "๐Ÿ”จ Build" x86_64_linux-clang20 Release 

```



### โšก Quick Build without SolutionController



For lightweight public repository versions or when using the template without the SolutionController, you can build the project using these simple commands:



```bash

# Install dependencies with Debug build type

conan install . --output-folder="build/" --build=missing --deployer=full_deploy -s build_type=Debug



# Configure build using Conan-generated preset

cmake --preset generic-linux-x86_64-gcc-15-debug -DBUILD_LIBRARY=ON -DBUILD_STANDALONE=ON



# Build the project

cmake --build build/ -j $(nproc)

```



**Important:** Always specify the build type (`-s build_type=Debug` or `-s build_type=Release`) with Conan install, and use the generated CMake preset instead of manual configuration. This ensures proper dependency resolution and linking.



This approach provides a direct CMake workflow without the additional automation layer, making it suitable for simpler use cases or when integrating with existing build systems.



---



## ๐Ÿ“ฆ Package Management



### ๐Ÿ”— Conan 2.0 Integration



This template uses Conan 2.0 for modern, efficient dependency management:



```python

# conanfile.py excerpt

def requirements(self):

    # Core dependencies

    self.requires("fmt/10.1.1")

```



### ๐Ÿ“‹ Dependency Management Commands



```bash

# Install dependencies

conan install . --build=missing



# Create dependency graph

conan graph info . --format=html > dependencies.html



# Update dependencies

conan install . --update



# Create lockfile for reproducible builds

conan lock create .

```



### ๐Ÿ”„ Custom Conan Profile



Create optimized profiles for different scenarios:



```ini

# profiles/development

[settings]

os=Linux

arch=x86_64

compiler=gcc

compiler.version=13

compiler.libcxx=libstdc++11

build_type=Debug



[options]

*:shared=False

*:fPIC=True



[buildenv]

CC=gcc-13

CXX=g++-13

```



---



## ๐Ÿงฐ Development Tools



### ๐Ÿ” Static Analysis with clang-tidy



> For clang-tidy linting must exist build artifacts due to the nature of the analysis.



Comprehensive static analysis is integrated into the build system:



```bash

# Run static analysis

python SolutionController.py both "๐Ÿ” clang-tidy linting" default Debug



# Custom clang-tidy configuration

python SolutionController.py standalone "๐Ÿ” clang-tidy linting" default Debug

```



**Configuration in `.clang-tidy`**:

```yaml

Checks: >

  clang-diagnostic-*,

  clang-analyzer-*,

  cppcoreguidelines-*,

  modernize-*,

  performance-*,

  readability-*,

  bugprone-*,

  cert-*,

  misc-*

WarningsAsErrors: ''

CheckOptions:

  - key: readability-identifier-naming.VariableCase

    value: camelCase

  - key: readability-identifier-naming.FunctionCase

    value: camelCase

  - key: readability-identifier-naming.ClassCase

    value: PascalCase

```



### ๐ŸŽจ Code Formatting



Consistent code style across the project:



```bash

# Format all C++ code

python SolutionController.py both "๐Ÿ“ clang-format" noNeedArch



# Format CMake files

python SolutionController.py both "๐Ÿ“ cmake-format" noNeedArch

```



---



## ๐Ÿ’ป IDE Integration



### ๐Ÿง  Visual Studio Code Setup



This template provides deep VSCode integration with optimized settings and tasks.



#### โŒจ๏ธ Keyboard Shortcuts



| Shortcut | Action | Description |

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

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

| **F7** | Quick Build | Build standalone application |

| **Shift+F7** | Build Menu | Show comprehensive build options |

| **Ctrl+F7** | Other Tasks | Show utility and maintenance tasks |

| **Ctrl+Alt+F** | Format Code | Run clang-format on current file |

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

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

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

| **Ctrl+Alt+R** | Run Standalone | Execute standalone binary |

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

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

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

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

| **Ctrl+Alt+Shift+T** | Coverage Tasks | Show coverage task menu |

| **Ctrl+Alt+Shift+O** | Coverage Tasks (Other) | Quick access to coverage tasks (native build only) |



#### ๐Ÿ“‹ VSCode Tasks



**๐Ÿ”จ Building Tasks (Shift+F7)**:

- **๐Ÿš€ Zero to Build**: Complete clean build workflow

- **๐Ÿฆธ Zero to Hero**: Full development cycle with testing and packaging

- **๐Ÿงน Clean Build**: Remove build artifacts and rebuild

- **๐Ÿ—ก๏ธ Conan Install**: Install and update dependencies

- **๐Ÿ”ง CMake Configure**: Configure build system

- **๐Ÿ“Š CMake configure with Coverage**: Configure build with code coverage enabled

- **๐Ÿชฒ CMake Configure with CMake-debugger**: Configure with CMake debugger

- **๐Ÿ”จ Build**: Compile the project

- **๐Ÿงช Run Tests**: Execute test suite

- **๐Ÿ“œ Gather dependency licenses**: Gather dependency licenses

- **๐Ÿ“Œ Install built components**: Install built components

- **๐Ÿ—œ๏ธ Create Tarballs for distribution**: Package for distribution

- **๐Ÿ›ธ Run CPack**: Create installation packages



**๐Ÿ› ๏ธ Other Tasks (Ctrl+F7)**:

- **๐Ÿ“– Generate Documentation**: Create Doxygen documentation

- **๐Ÿ“ Format Code**: Apply code formatting

- **๐Ÿ“ Format CMake**: Format CMake files

- **โš”๏ธ Create Conan Recipe**: Generate Conan package

- **๐Ÿ“Š Dependency Graph**: Visualize project dependencies

- **๐Ÿ” Security Scan**: Run security analysis

- **๐Ÿงช Benchmark**: Run performance tests



**๐Ÿ”ฌ Coverage Tasks from Other Menu**:

- **๐Ÿ“Š Coverage HTML Report**: Quick HTML report (native build only)

- **๐Ÿ“Š Coverage XML Report**: Quick XML report (native build only)

- **๐Ÿ“Š Coverage Summary**: Quick summary display (native build only)

- **๐Ÿ“Š Coverage Full Report**: Quick full report (native build only)

- **๐Ÿ“Š Coverage Reset**: Quick coverage reset (native build only)



#### ๐ŸŽฏ IntelliSense Configuration



Optimized C++ IntelliSense settings in `.vscode/c_cpp_properties.json`:



```json

{

    "configurations": [

        {

            "name": "Linux",

            "includePath": [

                "${workspaceFolder}/**",

                "/home/tomas/.cache/CPM/cxxopts/**",

                "/home/tomas/.cache/CPM/fmt*/**",

                "/home/tomas/.conan2/p/b/imgui*/**",

                "/home/tomas/.conan2/p/glm*/**",

                "/home/tomas/.conan2/p/nlohm*/**"

            ],

            "defines": [],

            "compilerPath": "${default}",

            "cStandard": "c11",

            "cppStandard": "c++17",

            "intelliSenseMode": "${default}",

            "recursiveIncludes": {

                "reduce": "always",

                "priority": "beforeSystemIncludes",

                "order": "breadthFirst"

            }

        }

    ],

    "version": 4

}

```



#### โš™๏ธ Useful Editor Settings



To disable middle mouse button paste in VSCode (useful when accidentally triggering paste), add this setting to your VSCode configuration:



```json

{

    "editor.selectionClipboard": false

}

```



---



## ๐ŸŒ Cross-Platform Development



### ๐Ÿ–ฅ๏ธ Platform Support Matrix



| Feature | Linux | macOS | Windows | WebAssembly |

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

| **Native Build** | โœ… | โœ… | โœ… | N/A |

| **Cross-Compilation** | โœ… | โœ… | โœ… | โœ… |

| **Package Management** | โœ… | โœ… | โœ… | โœ… |

| **IDE Integration** | โœ… | โœ… | โœ… | โœ… |

| **CI/CD** | โœ… | โœ… | โœ… | โœ… |

| **Container Support** | โœ… | โœ… | โœ… | โœ… |



> **๐Ÿ“ Linux Note**: For full parallel computing support, install TBB development package: `sudo apt install libtbb-dev` (Ubuntu/Debian) or `sudo dnf install tbb-devel` (Fedora/RHEL)



### ๐Ÿ”ง Cross-Compilation Setup



```bash

# ARM64 Linux from x86_64

conan install . -pr:h=profiles/arm64-linux -pr:b=default



# Windows from Linux

conan install . -pr:h=profiles/windows-x64 -pr:b=default



# Configure cross-compilation

cmake --preset cross-arm64-release

```



### ๐Ÿณ Container Development



**Status**: โœ… **Implemented**



Complete Docker environment with multi-stage builds:



```bash

# Quick start from project root

./docker.sh dev     # Start development environment

./docker.sh test    # Run zero-to-hero build test

./docker.sh prod    # Start production web server



# Or navigate to docker directory for full control

cd docker/

make help           # Show all available commands

make dev && make shell

```



**Key Features**:

- **Organized structure**: All Docker files in `/docker` directory

- **Multi-stage builds**: Development, production, and clean environments

- **Easy access**: Quick commands via `./docker.sh` or `cd docker && make`

- **Persistent volumes**: Conan cache and ccache for faster rebuilds

- **Pre-configured aliases**: `build-debug`, `test-run`, `zero-to-hero`

- **Web hosting**: Nginx server for documentation and demos

- **Live development**: Source code mounted for real-time changes



See [`docker/README.md`](docker/README.md) for complete usage guide.



---



## ๐ŸŒ WebAssembly & Emscripten



### ๐Ÿš€ Emscripten Integration



This template provides seamless WebAssembly development with Emscripten:



```bash

# Build for web deployment

python SolutionController.py both "๐Ÿš€ Launch Emscripten Server" noNeedArch



# Quick Emscripten build

cmake --preset debug-emscripten-wasm-clang-20

cmake --build --preset debug-emscripten-wasm-clang-20

```



### ๐ŸŽฎ Web Application Features



- **Asset Preloading**: Automatic asset packaging for web deployment

- **Modern Web Standards**: ES6+ JavaScript integration

- **Responsive Design**: Mobile-friendly web interface

- **Performance Optimization**: WebAssembly-optimized builds



### ๐ŸŒ Live Demo



Experience the template in action:

- **Debug Version**: [DotNameStandalone.html (Debug)](https://digitalspace.name/dotnamecpp/preview/debug/DotNameStandalone.html)

- **Release Version**: [DotNameStandalone.html (Release)](https://digitalspace.name/dotnamecpp/preview/release/DotNameStandalone.html)



Experience with more complex scenarios: **GPU required**

- **Debug Version**: [DotNameStandalone.html (Debug)](https://digitalspace.name/dotnamecpp/i2/singularity/debug/index2.html)

- **Release Version**: [DotNameStandalone.html (Release)](https://digitalspace.name/dotnamecpp/i2/singularity/release/index2.html)



### ๐Ÿ“ฑ Emscripten Configuration



```cmake

# cmake/tmplt-emscripten.cmake excerpt

if(EMSCRIPTEN)

    set_target_properties(${target} PROPERTIES

        SUFFIX ".html"

        LINK_FLAGS "

            --preload-file ${CMAKE_SOURCE_DIR}/assets@assets

            -s USE_SDL=2

            -s ALLOW_MEMORY_GROWTH=1

            -s EXPORTED_FUNCTIONS=['_main']

            -s EXPORTED_RUNTIME_METHODS=['ccall']

        "

    )

endif()

```



### ๐ŸŽฏ Web Deployment



```bash

# Serve locally for development

python -m http.server 8000 -d build/emscripten/debug



# Production deployment (planned)

# python SolutionController.py emscripten "๐Ÿš€ Deploy Web" noNeedArch



# Current: Manual deployment to web server

# Copy build/emscripten/release/* to your web hosting service

```



---



## ๐Ÿงช Testing Framework



### ๐Ÿ”ฌ Google Test Integration



Comprehensive testing framework with Google Test:



```cpp

// Example test in standalone/tests/

#include 

#include "DotNameLib/DotNameLib.hpp"



class DotNameLibTest : public ::testing::Test {

protected:

    void SetUp() override {

        // Test setup

    }

};



TEST_F(DotNameLibTest, BasicFunctionality) {

    EXPECT_TRUE(DotNameLib::isInitialized());

    EXPECT_EQ(DotNameLib::getVersion(), "1.0.0");

}

```



### ๐ŸŽฏ Test Categories



```bash

# Run all tests

python SolutionController.py both "๐Ÿงช Run CTest" default Debug



# Unit tests only

ctest --preset debug-linux-x86_64-gcc-15 --label-regex "unit"



# Integration tests

ctest --preset debug-linux-x86_64-gcc-15 --label-regex "integration"



# Performance benchmarks

ctest --preset debug-linux-x86_64-gcc-15 --label-regex "benchmark"

```



### ๐Ÿ“Š Test Coverage



```bash

# Enable coverage during configuration

cmake --preset debug-linux-x86_64-gcc-15 -DENABLE_COVERAGE=ON



# Build with coverage

cmake --build --preset debug-linux-x86_64-gcc-15



# Run tests to generate coverage data

ctest --preset debug-linux-x86_64-gcc-15



# Generate HTML coverage report

make coverage-html

# or using cmake

cmake --build . --target coverage-html



# Generate XML coverage report (for CI/CD)

make coverage-xml

# or using cmake

cmake --build . --target coverage-xml   



# Generate both HTML and XML reports

make coverage

# or using cmake

cmake --build . --target coverage



# Display coverage summary in console

make coverage-summary

# or using cmake

cmake --build . --target coverage-summary



# Reset coverage counters

make coverage-reset

# or using cmake

cmake --build . --target coverage-reset



# Alternative: Direct gcovr usage

gcovr --html --html-details -o coverage.html

gcovr -x -o coverage.xml

```



---



## ๐Ÿ“š Library Development



### ๐Ÿ“ฆ Library Structure



The template supports both header-only and compiled library development:



```cpp

// include/DotNameLib/DotNameLib.hpp

#pragma once



namespace DotNameLib {

    // Public API

    bool initialize();

    void shutdown();

    std::string getVersion();

}



// src/DotNameLib.cpp

#include "DotNameLib/DotNameLib.hpp"



namespace DotNameLib {

    bool initialize() {

        // Implementation

        return true;

    }

}

```



### ๐Ÿ”— Integration Methods



1. You create your own project called **Wheels** *using DotNameCpp* and push it to GitHub.

2. Then, in your next project named **Car**, you use the **Wheels** library as follows:



#### Method 1: CPM.cmake (Recommended)



```cmake

# in project Car in file project-standalone.cmake

CPMAddPackage("gh:tomasmark79/Wheels#main")

target_link_libraries(${STANDALONE_NAME} PRIVATE WheelsLib CarLib cxxopts::cxxopts)



# in project Car in file project-tests.cmake

target_link_libraries(${TEST_NAME} PRIVATE GTest::gtest GTest::gtest_main WheelsLib dotname::${TEST_NAME_LOWER}_standalone_common)

```

```cpp

// in project Car in file AppCore.hpp

#include 

std::unique_ptr uniqueWheelsLib;

uniqueWheelsLib = std::make_unique (AppContext::assetsPath);

LOG_I_STREAM << "Wheels count: " << uniqueWheelsLib->getWheelsCount() << std::endl;

```



```bash

$ ./CarStandalone



# output

Starting CarStandalone ...

WheelsLib v.0.0.1 constructed ...

Assets: "tmp/Car/build/standalone/default/share/CarStandalone/assets"

path: "tmp/Car/build/standalone/default/share/CarStandalone/assets/DotNameLogoV2.svg"

CarLib v.0.0.1 constructed ...

Assets: "tmp/Car/build/standalone/default/share/CarStandalone/assets"

path: "tmp/Car/build/standalone/default/share/CarStandalone/assets/DotNameLogoV2.svg"

Wheels count: 4

CarLib v.0.0.1 ... destructed

This is a demo error message

Sucessfully exited CarStandalone

WheelsLib v.0.0.1 ... destructed

```



#### Method 2: FetchContent similar to CPM.cmake



```cmake

include(FetchContent)

FetchContent_Declare(

    Wheels

    GIT_REPOSITORY https://github.com/tomasmark79/Wheels.git

    GIT_TAG v1.0.0

)

FetchContent_MakeAvailable(Wheels)



target_link_libraries(your_target Wheels::Wheels)

```



#### Method 3: Conan Package - TODO



```python

# Create Conan package

python SolutionController.py both "โš”๏ธ Create conan library recipe" noNeedArch



# In consumer project's conanfile.py

def requirements(self):

    self.requires("dotnamelib/1.0.0")

```



#### Method 4: Subdirectory



```cmake

add_subdirectory(path/to/Wheels)

target_link_libraries(your_target Wheels::Wheels)

```



#### Method 5: find_package



```cmake

find_package(Wheels REQUIRED)

target_link_libraries(your_target Wheels::Wheels)

```



### ๐Ÿ“‹ API Design Guidelines



- **Namespace Everything**: Use project-specific namespaces

- **RAII Pattern**: Prefer automatic resource management

- **Exception Safety**: Provide strong exception safety guarantees

- **ABI Stability**: Consider ABI compatibility for library updates

- **Documentation**: Comprehensive Doxygen documentation



### ๐Ÿ”„ Versioning Strategy



The main versioning for libraries is maintained in the project definition file at `cmake/project-library.cmake`.



```cmake

# Semantic versioning

set(PROJECT_VERSION_MAJOR 1)

set(PROJECT_VERSION_MINOR 0)

set(PROJECT_VERSION_PATCH 0)

set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")

```



---



## ๐Ÿ”„ CI/CD Pipeline



### ๐Ÿš€ GitHub Actions Workflows



Comprehensive CI/CD with multi-platform support:



**Implemented Workflows:**

- **โœ… Linux CI**: Ubuntu with GCC and Clang

- **โœ… macOS CI**: Latest macOS with Xcode

- **โœ… Windows CI**: Windows Server with MSVC

- **โœ… Cross-Platform Testing**: Automated test execution

- **โœ… Code Quality**: Static analysis and formatting checks

- **โœ… Documentation**: Automated Doxygen generation

- **โœ… Public Repository Sync**: Automated synchronization to public repo with `-Pub` suffix 



**Workflow Features:**

- Matrix builds across multiple compilers and configurations

- Conan dependency caching for faster builds

- Artifact collection for build outputs

- Code coverage reporting integration

- Release automation with semantic versioning

- Selective file synchronization to public repository



### ๐Ÿ“ข Public Repository Automation



The template includes automated public repository synchronization via `make-pub.yml`:



- **Disabled by default**: Requires explicit developer activation

- **Enable sync**: Set `ENABLE_SYNC=true` in `.github/workflows/make-pub.conf`

- **Auto-sync**: Triggers on push to main branch (when enabled)

- **Selective files**: Configure via `.github/workflows/make-pub.conf`

- **Repository naming**: Creates `[ProjectName]-Pub` automatically

- **Token support**: Uses (PAT) `PUB_REPO_TOKEN` for authentication



**Badge Status**: See repository badges at the top of this README for current build status.



---



## ๐Ÿ› ๏ธ Maintenance & Utilities



### ๐Ÿ”„ Project Maintenance Scripts



#### SolutionRenamer.py

Rename your project from the template:



```bash

python SolutionRenamer.py DotNameLib MyAwesomeLib DotNameStandalone MyAwesomeApp

python SolutionRenamer.py MyAwesomeLib DotNameLib MyAwesomeApp DotNameStandalone

```



Affected files:

- โœ“ All CMake configuration files

- โœ“ All C++ source files and headers

- โœ“ VS Code configuration (`launch.json`, `tasks.json`)

- โœ“ Documentation (`Doxyfile`, `README.md`)

- โœ“ Package management (`conanfile.py`)

- โœ“ Web assets (`ems-mini.html`)

- โœ“ Logger configuration

- โœ“ License files



#### SolutionUpgrader.py

Update template files from the upstream repository:



```bash

python SolutionUpgrader.py

```



#### SolutionController.py

Central automation hub for all build and development tasks:



```bash

# Interactive usage - Use VSCode tasks for full functionality

python SolutionController.py



# Command line usage

python SolutionController.py  ""  [build_type]



# Examples:

python SolutionController.py standalone "๐Ÿ”จ Build" default Debug

python SolutionController.py both "๐Ÿฆธ Zero to Hero" default Release

python SolutionController.py emscripten "๐Ÿš€ Launch Emscripten Server" noNeedArch



# Note: Help system documentation is in development

# For complete task list, use VSCode tasks menu (Shift+F7)

```



---



## ๐Ÿ“– Documentation



### ๐Ÿ“š Doxygen Integration



Automatic documentation generation with Doxygen:



```bash

# Generate documentation

python SolutionController.py both "๐Ÿ“– Doxygen documentation generation" noNeedArch

```



### ๐Ÿ“ฑ View Documentation



```bash

# Open the generated documentation in your browser (Linux)

xdg-open doc/html/index.html

```



### ๐Ÿ”— Additional Resources



- **API Reference**: Generated from source code comments

- **User Guide**: Comprehensive usage examples

- **Developer Guide**: Contribution guidelines and architecture

- **Changelog**: Version history and migration guides



---



## ๐Ÿ“„ License



**MIT License**



Copyright (c) 2024-2025 Tomรกลก Mark



Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:



The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.



---



## โš ๏ธ Important Disclaimer



This template is provided "as is" without warranties of any kind. While extensively tested across multiple platforms and continuously maintained, users must validate that the template meets their specific requirements before production use. The template undergoes regular updates to maintain compatibility with evolving toolchains and dependencies.



**Key Considerations:**

- Verify all dependencies and tools are compatible with your target environment

- Test thoroughly in your specific development and deployment scenarios  

- Some features (marked as TODO) are planned but not yet implemented

- Cross-platform builds may require additional configuration on certain systems



---



**Happy coding! ๐Ÿš€๐Ÿš€๐Ÿš€**



For support, questions, or suggestions, please [open an issue](https://github.com/tomasmark79/DotNameCpp/issues) or [start a discussion](https://github.com/tomasmark79/DotNameCpp/discussions).



[๐Ÿ” Back to top](#dotnamecpp---advanced-c-development-template)



---



## ๐Ÿ“ข Public Repository Information



This is a **public version** of the **DotNameCpp** project.



This repository contains carefully selected files from the main project that are suitable for public sharing and collaboration.



### ๐Ÿ”„ Automatic Synchronization



The content of this repository is automatically synchronized using GitHub Actions.



- **Last synchronization:** 2025-09-02 12:04:32 UTC

- **Source commit:** `b0b954d`

- **Synchronization rules:** Controlled by automated configuration



### ๐Ÿค Contributing



If you find this project useful or have suggestions for improvement, feel free to:

- โญ Star this repository

- ๐Ÿ› Report issues or bugs

- ๐Ÿ’ก Suggest new features

- ๐Ÿ”„ Submit pull requests



### ๐Ÿ“ž Contact



For questions about this project or collaboration opportunities, please create an issue in this repository.