C++ Standard

The cpp-library profile covers native C++ libraries, command line tools, and C ABI surfaces. It is also inherited by mixed-mode packages that combine Python, C++, and WASM.

Formatter

Owned C++ source uses a committed .clang-format at the repo root. The baseline follows the current native-library convention: LLVM base style, Allman braces, 4-space indentation, 100-column line limit, left pointer alignment, sorted includes, and preserved include blocks.

BasedOnStyle: LLVM
BreakBeforeBraces: Allman
IndentWidth: 4
ColumnLimit: 100
AllowShortFunctionsOnASingleLine: Empty
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AllowShortBlocksOnASingleLine: Empty
PointerAlignment: Left
SortIncludes: true
IncludeBlocks: Preserve
SpaceAfterCStyleCast: false
SpaceBeforeParens: ControlStatements

Static Analysis

New native projects commit .clang-tidy and run clang-tidy from a build-graph-generated compile_commands.json. Existing projects may document temporary suppressions, but new warnings should not be added.

C and C++ projects enable google-runtime-int and treat it as an error for owned code. That gate blocks short, long, long long, unsigned long, and unsigned long long spellings in application-owned integer storage.

Integer Widths

Owned C++ code uses fixed-width standard integer types when width matters: std::int32_t, std::uint32_t, std::int64_t, and std::uint64_t. C ABI and C headers use the corresponding C spellings from <stdint.h> or <cstdint> without the std:: qualifier where the ABI requires C-compatible names.

Use std::size_t for object sizes and container indices, and std::ptrdiff_t for signed pointer or container differences. External-library integer spellings are allowed at the external API boundary, but owned code should convert them into the project-owned type at the boundary.

Checks: >
  -*,
  google-runtime-int

WarningsAsErrors: >
  google-runtime-int

Build Systems

Bazel is the preferred build option for greenfield C++ libraries and executables. Preferred projects use Bzlmod with MODULE.bazel and MODULE.bazel.lock, use Bazelisk with a checked-in .bazelversion, commit .bazelrc, register owned targets in BUILD.bazel, and expose bazel build, bazel test, and compile_commands.json generation through Rack.

CMake remains a permitted and supported compatibility option. CMake projects use CTest and CMakePresets.json, use Ninja as the generator, and set CMAKE_EXPORT_COMPILE_COMMANDS=ON. A project does not need to carry both graphs. The selected graph is authoritative and must remain reproducible in local and CI signoff.

Warnings

Owned C++ code should compile with MSVC /W4 and Clang/GCC -Wall -Wextra -Wpedantic. Release-facing CI should treat warnings in owned code as errors. Third-party code is isolated from these warning policies unless explicitly patched and owned.

Native Tests

Register native tests with preferred bazel test or permitted CTest and expose them through Rack strata. A typical native sequence is L0 compile/foundation, L1 algorithm tests, L2 CLI or public API integration, optional slow corpus/performance lanes, and L99 release signoff.

Complexity

C and C++ projects must run a Lizard-based complexity gate as part of the normal signoff loop. The gate scans owned native source, excludes generated and third-party code explicitly, and fails when project thresholds are exceeded. Canonical new-code limits are max_file_lines = 2200, max_function_lines = 220, and max_cyclomatic_complexity = 10.

Existing projects may carry a checked-in baseline for current debt. The baseline makes old debt visible, but new functions over the canonical cyclomatic complexity threshold must fail signoff.

[limits]
max_file_lines = 2200
max_function_lines = 220
max_cyclomatic_complexity = 10

[tools]
lizard = "fail"
clang_format = "report"
clang_tidy = "report"

Boundaries

Public headers live behind an intentional include boundary. Private headers stay under an internal or private source tree. C ABI boundaries must be versioned, must report errors without throwing C++ exceptions across the boundary, and must document ownership of allocated memory.