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

Documentation: bluesentinelsec.github.io/cppboot — including the Android (--with-android-ci), iOS (--with-ios-ci), and Web/Emscripten (--with-web-ci) package guides.

Requirements

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:

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

Opt-outs (features are on unless disabled)

Examples:

cppboot -n service --license mit
cppboot -n libdemo --shared --no-vscode
cppboot -n moddemo --with-modules
cppboot -n droidlib --with-android-ci
cppboot -n applelib --with-ios-ci
cppboot -n webgame --with-web-ci
cppboot -n portable --with-android-ci --with-ios-ci --with-web-ci
cppboot -n tool --github --output-dir ~/src

Android (--with-android-ci): adds an android/ Gradle project that packages the library as a Prefab AAR (arm/x86_64 ABIs), a consumer test app with on-device native tests, and GitHub Actions jobs that build the AAR, verify its contents, and run the tests on an emulator. Releases attach <name>-android-release-<version>.aar. Local builds need JDK 17 + the Android SDK; Gradle fetches the pinned NDK and CMake automatically.

iOS (--with-ios-ci): adds scripts that package the library as a static XCFramework (device arm64 + simulator arm64/x86_64, headers included), a Simulator test app consuming the package, and GitHub Actions jobs that build, verify, and test it. Releases attach <name>-ios-xcframework-release-<version>.zip. Local builds need macOS with Xcode command line tools.

Web (--with-web-ci): adds a game-development-oriented Emscripten scaffold — an HTML5 canvas demo built around emscripten_set_main_loop with a custom fullscreen-canvas shell (plus commented hooks for --preload-file assets and SDL2), browser tests (GoogleTest compiled to wasm) run in headless Chrome, and GitHub Actions jobs for both. Releases attach <name>-web-wasm32-release-<version>.zip containing the wasm library, headers, and the playable demo. Local builds need an activated Emscripten SDK.

Generated project workflow

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

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.