cxx-init

A small personal tool for creating clean, modern C++ projects without repeating the same setup work.

Install

uv tool install cxx-init

Alternatively, use pipx:

pipx install cxx-init

Create a project

cxx init hello
cd hello
cmake --workflow --preset dev

The generated project uses normal C++ tooling directly and does not depend on cxx after creation.

Upgrade or uninstall the tool with:

uv tool upgrade cxx-init
uv tool uninstall cxx-init

Requirements

cxx requires Python 3.10 or newer. Generated projects require CMake 3.25 or newer, Ninja, and a C++23 compiler.

Experimental standard-library import

cxx init demo --import-std
cd demo
export CXX="$(brew --prefix llvm)/bin/clang++"
export CMAKE_CXX_STDLIB_MODULES_JSON="$(brew --prefix llvm)/lib/c++/libc++.modules.json"
cmake --workflow --preset dev

This opt-in replaces standard headers with C++23 import std;; the ordinary command and its generated files are unchanged. It is experimental, currently verified only on Apple Silicon macOS with Homebrew LLVM/libc++ 23.1.2, CMake 4.4.3 and Ninja 1.13.2. Verified versions are not a blanket compatibility promise. The opt-in project's CMake minimum is 4.4 and its experimental gate must be rechecked when upgrading CMake.

The shared dev/san/release workflows, CTest and clang configs remain in use, with one project-local exception: import-std sets Diagnostics.MissingIncludes: None because Include Cleaner can falsely require textual standard-library headers. Headers projects keep Strict; ordinary semantic diagnostics and clang-tidy remain enabled. Supply metadata through the environment for each workflow; machine paths are not embedded in the generated project. Creation stays offline and does not probe or install toolchains. Unsupported tools or missing metadata fail at configure/build, with no headers fallback.

clangd may suggest redundant standard-library includes. Do not enable --experimental-modules-support for the verified setup; its generated PCM showed a configuration mismatch. clang-tidy may diagnose libc++ module sources; an exception-escape warning for main() using std::println also occurs with headers and is not a module bug. Neither mode changes exception semantics to silence that policy. The generated mode README records setup and limitations. There is no global editor change, general --modules option or custom module/partition generation.

The published v0.2.0 artifact still generates MissingIncludes: Strict in both modes. The project-local override is a v0.2.1 correction, not a retroactive change to that release. Existing import-std projects can set None manually; upgrading the generator never rewrites existing projects.

Generated project workflows

Each workflow configures, builds, and runs CTest:

The configure step restores the preset's sanitizer setting even after a manual cache override. release is a local optimized build, not a packaging or publishing command.

The template fixes the project's editing baseline, including direct-include diagnostics for headers projects and the documented import-std exception above. clangd always uses build/dev/compile_commands.json; running san or release does not switch it. Configure dev before editing C++ files.

Choose a compiler before the first configure of each build directory. For example, on macOS:

CXX=/opt/homebrew/opt/llvm/bin/clang++ cmake --workflow --preset dev

CMake caches that choice; changing CXX later does not switch an already configured directory. Use a separate build directory when comparing compilers. Machine-specific paths or SDK overrides can be recorded in the ignored CMakeUserPresets.json; no extra config is needed for normal use. If an explicit compiler experiment uses another compilation database, select it explicitly in clangd as well. Project style and diagnostic preferences remain fixed in the template.

Design priorities

1. Personal developer experience first.
2. Small, readable implementation.
3. Minimal generated files.
4. No hidden host mutation.
5. No build-system wrapper.
6. No network requirement during project creation.
7. Prefer boring, inspectable code over framework-heavy abstractions.

Scope

The current product creates one canonical app project. Additional artifact types remain deferred until real usage demonstrates a need for them:

lib
header-only

Initial generated projects use:

C++23
Modern target-centric CMake
CMake Presets / Workflow Presets
Ninja
clangd
clang-format
clang-tidy
CTest
ASan / UBSan where supported
compile_commands.json

Dependency managers, C++26, custom Modules, ROS, CUDA, benchmarking and fuzzing remain deferred.

Repository documents

• AGENTS.md — rules for Codex and other coding agents.
• docs/architecture.md — architecture and boundaries.
• docs/implementation-plan.md — current implementation sequence.

Development

Build the wheel and source distribution with:

uv build

Run the black-box test suite with:

python3 -m unittest discover -s tests -v

For the v0.2.1 release gate on the verified Mac toolchain, explicitly enable the import-std artifact tests (otherwise they are reported as skipped, not verified):

export CXX="$(brew --prefix llvm)/bin/clang++"
export CMAKE_CXX_STDLIB_MODULES_JSON="$(brew --prefix llvm)/lib/c++/libc++.modules.json"
export CLANG_FORMAT="$(brew --prefix llvm)/bin/clang-format"
export CLANGD="$(brew --prefix llvm)/bin/clangd"
export CLANG_TIDY="$(brew --prefix llvm)/bin/clang-tidy"
uv build --no-sources
CXX_TEST_IMPORT_STD=1 CXX_TEST_DIST="$PWD/dist" CXX_RELEASE_TAG=v0.2.1 \
  python3 -m unittest discover -s tests -v

This tests the supplied wheel without rebuilding it. Both modes run all three workflows with exact application output and real compilation database checks. The import-std path also checks formatting, static clangd --check, real LSP diagnostics and clang-tidy; only the observed libc++ _Exit reserved-identifier warning is accepted. Application warnings still fail. The LSP regression separately introduces std::println in unsaved buffers to verify that the shared exception warning remains active in both module and header forms; it does not rewrite the generated app or weaken the command-line clang-tidy gate. The unchanged Ubuntu publishing workflow verifies the headers path; it does not claim Linux import-std support. Do not release without the separate Mac gate.

Tooling acceptance boundaries

The import-std capability remains Forward-ready / experimental, not a blanket "tooling PASS". On the verified Mac toolchain, distinguish these layers:

The v0.2.0 static check result did not establish an editor-wide diagnostics PASS. The real LSP regression is added after that release; it runs for both checkout and installed-wheel import-std projects when CXX_TEST_IMPORT_STD=1.

House-style regression

The canonical formatter configuration is the single source of house-style rules; documentation does not keep a second copy. Check the formatting sample against its reviewed expected output with the fixed clang-format 23.1.x baseline:

CLANG_FORMAT=/opt/homebrew/opt/llvm/bin/clang-format python3 tests/check_format.py

CLANG_FORMAT selects the executable; it defaults to clang-format on PATH. The check reports the actual version, reads the canonical config explicitly, and fails on errors or output differences. It never rewrites the sample or golden output. Review intentional style changes before updating either.

The sample covers include grouping, pointers/references, access labels, concepts/requires, wrapped parameters/arguments, control flow, lambdas, namespaces, and long string literals. It is formatting-only: the header names are not build dependencies. This explicit check is separate from Python test discovery and wheel acceptance, which do not require a formatter.