Skip to content

README.md

Latest commit

 

History

History
198 lines (145 loc) · 5.87 KB

README.md

File metadata and controls

198 lines (145 loc) · 5.87 KB
Raw

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

CI PyPI Python versions License

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.