cppboot

cppboot scaffolds a complete, opinionated C++ project so you can start shipping code instead of wiring build systems.

pip install cppboot
cppboot -n myproj
cd myproj && make && make test

---

Requirements

Python	3.9 or newer
Generated projects	CMake 3.20+ (3.28+ with --with-modules), a C++20 compiler, Ninja recommended

Optional tools used when present: git, clang-format, make / ninja, doxygen, ctags, GitHub CLI (gh).

---

Install

pip install cppboot

Upgrade:

pip install -U cppboot

---

Quick start

cppboot -n myproj
cd myproj
make          # Debug build
make test
./myproj --version

On Windows (Developer Command Prompt or any shell with cmake on PATH):

build.bat
build.bat test

Create a public GitHub remote in one step (requires authenticated gh):

cppboot -n myproj --github

---

What you get

Each project is ready for multi-platform development and release:

Area	Included
Build	CMake (C++20), GNU Makefile, Windows build.bat, CMakePresets.json
Versioning	Root VERSION file (single source of truth) → CMake, CLI --version, release checks
Library + app	Static library by default (--shared optional), thin src/main.cpp entrypoint
Sample API	Version component with unit tests and a microbenchmark
Deps	FetchContent (on by default): CLI11, nlohmann/json, spdlog, GoogleTest, Google Benchmark
Quality	Microsoft .clang-format, Google C++ style for code, warnings-as-errors, .clangd
Docs	Doxygen Doxyfile, README.md, AGENTS.md for humans and coding agents
IDE	VS Code (clangd, CMake Tools, CodeLLDB, C++ TestMate), optional Vim + ctags
CI/CD	GitHub Actions: multi-OS CI, sanitizers, tag/dispatch Release with zip assets
Community	CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md
Bootstrap	make fmt then git init + initial commit (when tools are available)

C++20 modules: cppboot -n myproj --with-modules scaffolds module interface units (no classic include/ tree for the sample API). CI installs module-capable toolchains on Linux/macOS.

---

CLI

cppboot [-n NAME] [options]

Core options

Flag	Default	Description
-n, --name	(prompt)	Project / program name
--license	apache-2.0	apache-2.0, mit, bsd-3-clause, gpl-3.0, lgpl-3.0, mpl-2.0, unlicense
--build-system	cmake	Only cmake is supported
--with-modules	off	C++20 modules layout
--shared	off	Shared library instead of static
--github	off	Create a public remote with gh and push
--output-dir	.	Parent directory for the new project folder
-v, --verbose	off	Verbose logging
--version		Print cppboot version
-h, --help		Help

Opt-outs (features are on unless disabled)

Flag	Effect
--no-vim	Skip project-local .vimrc
--no-ctags	Skip Universal Ctags config / make tags
--no-vscode	Skip VS Code config and CMake presets
--no-github-actions	Skip CI, sanitizers, and release workflows
--no-codespaces	Skip Dev Container / Codespaces config
--no-community-docs	Skip CoC / CONTRIBUTING / SECURITY
--no-git	Skip git init and the initial commit
--no-fmt	Skip make fmt after scaffolding

Examples:

cppboot -n service --license mit
cppboot -n libdemo --shared --no-vscode
cppboot -n moddemo --with-modules
cppboot -n tool --github --output-dir ~/src

---

Generated project workflow

After scaffolding, day-to-day commands (Unix / make):

Command	Purpose
make / make debug	Configure and build Debug
make release	Configure and build Release
make test	Unit tests (Debug)
make bench	Microbenchmarks (Release)
make sanitizer	ASan+UBSan (Linux-oriented)
make fmt	clang-format
make doc	Doxygen HTML under docs/html
make clean	Remove build trees

Windows: the same targets via build.bat / build.bat release / build.bat test, etc.

Versioning: edit the root VERSION file only (e.g. 1.2.3). CMake regenerates the version API; the Release workflow requires the Git tag to match.

Releases (generated repos): push tag vX.Y.Z or run the Release workflow; multi-OS zips attach to the GitHub Release when CI succeeds.

---

Library usage (Python)

from pathlib import Path
from cppboot import ProjectOptions, generate_project

result = generate_project(
    ProjectOptions(
        name="myproj",
        root=Path.cwd(),
        with_git=True,
        with_fmt=True,
    )
)
print(result.project_dir)

---

Contributing to cppboot

Clone and develop in an editable environment:

git clone https://github.com/bluesentinelsec/cppboot.git
cd cppboot
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
python3 -m ruff check src tests
python3 -m mypy

Package version is defined in src/cppboot/_version.py. Releases are cut from main with an annotated GitHub tag vX.Y.Z (must match that version); CI publishes the wheel/sdist to PyPI.

See CHANGELOG.md for release history.

---

License

Apache License 2.0. See LICENSE.