Skip to content

v0.1.0.md

Latest commit

 

History

History
76 lines (44 loc) · 7.89 KB

v0.1.0.md

File metadata and controls

76 lines (44 loc) · 7.89 KB

pbr-cpp-memory-pool v0.1.0 — Milestone 1: Build System & Project Skeleton

First tagged release of pbr-cpp-memory-pool: a clean, reproducible C++17 build that links a public C API skeleton with no-op stub implementations and passes the full enterprise CI gate on Linux × {GCC, Clang}, Windows × MSVC, and macOS arm64. This release ships the scaffolding that the real free-list algorithm will hang off — build system, headers, CTest harness, CI matrix, and release pipeline. The actual O(1) free-list lands in Milestone 2 → v0.2.0.

What's in the box

Agent contract and documentation

A complete agent-facing contract lives in AGENTS.md, with tool adapters CLAUDE.md (Claude Code) and GEMINI.md (Gemini Antigravity) deferring to it. The persona, English-only artifact rule, source-tree shape, git workflow, documentation maintenance rules, design-patterns policy, and enterprise quality bar are all normative. The frozen functional/technical specification is at docs/specs/01_spec_cpp_memory_pool.md. The project plan is the numbered checkbox-driven ROADMAP.md, traced section-by-section back to the spec via the Spec Coverage Map.

Seven Architecture Decision Records are accepted: record ADRs (0001), cross-language source layout (0002), design-patterns policy (0003), versioning & release policy (0004), toolchain matrix and supported platforms (0005), code style and static-analysis baseline (0006), and doctest as the test framework (0007).

Source tree and library skeleton

Maven-style cross-language layout per ADR-0002 — all C++ code under src/main/cpp/it/d4np/memorypool/, tests under src/test/cpp/, a minimal C consumer under src/test/c/ for the C89/C99 verification job, and the benchmark root under src/bench/cpp/ waiting for Milestone 2.9. Namespace it::d4np::memorypool mirrors the path 1:1. The public C API surface is the four spec §5 functions:

memory_pool_t* memory_pool_create(size_t block_size, size_t block_count);
void*          memory_pool_alloc(memory_pool_t* pool);
void           memory_pool_free(memory_pool_t* pool, void* block);
void           memory_pool_destroy(memory_pool_t* pool);

with a parallel C++17 RAII wrapper in <it/d4np/memorypool/memory_pool.hpp> exposing it::d4np::memorypool::Pool. Version constants live in <it/d4np/memorypool/version.hpp> — single source of truth per ADR-0004 §2, consumed by CMake at configure time.

The library target is pbr_memory_pool (alias pbr::memory_pool), STATIC, with the include root at src/main/cpp/ so consumers write #include <it/d4np/memorypool/memory_pool.h>.

Build system

CMakeLists.txt (≥ 3.21) declares the project and the static library target; the version is read from version.hpp at configure time so version.hpp stays the single source of truth. CMakePresets.json (schema v6) defines five presets — debug, release, asan, ubsan, tsan — with sanitizer presets gated to POSIX hosts per ADR-0005 §3. The canonical three-step quickstart is the same on every supported platform; the Local Build Guide walks through toolchain installation for Linux / macOS / Windows MSVC / MinGW.

Code style and static analysis

.clang-format — LLVM-derived, 4-space indent, 120-col soft limit, pointer-aligned-left. .clang-tidy — bugprone-*, cert-*, cppcoreguidelines-*, modernize-*, performance-*, portability-*, readability-* baseline with the deviations recorded in ADR-0006 §2.

Test harness

doctest v2.4.11 pulled via CMake FetchContent, gated by PBR_MEMORY_POOL_BUILD_TESTS (on by default in every preset). The first CTest smoke test — pool_smoke, labels smoke;milestone-1 — exercises the version constants, the four spec §5 C symbols, and the Pool RAII wrapper against the Milestone 1 stub contract.

Continuous integration

ci.yml gates every PR with: a 14-cell build matrix (Linux × {GCC 13, Clang 18} × {Debug, Release, ASan, UBSan} + Windows × MSVC × {Debug, Release} + macOS arm64 × Apple Clang × {Debug, Release, ASan, UBSan}); a clang-format repo-wide dry-run with -Werror; a clang-tidy diff gate with --warnings-as-errors='*'; ANSI C (-std=c89) and C99 (-std=c99) compatibility verification of the public C header; and a zero-external-dependency audit that builds the library with tests/benchmarks off and inspects the static archive for stray third-party objects. Markdown / link / ADR sanity runs in parallel via docs.yml.

Release pipeline

release.yml — this release is the first exercise of the new pipeline. Triggered on v* tag push, it re-runs the full PR-gating matrix against the tagged commit, builds per-platform binary artifacts (pbr-memory-pool-<version>-<platform>.tar.gz for Linux x86_64, Windows x86_64, and macOS arm64 — static library + public headers + LICENSE + README + CHANGELOG), emits a single SHA256SUMS, and creates a draft GitHub Release that the maintainer reviews and publishes manually. Pre-release suffixes (-alpha.N / -beta.N / -rc.N) are auto-detected and propagated.

Spec Coverage Map flips

This release moves §3.3 (ANSI C / C++17 standard, no external dependencies) from in-progress to ✅. The dedicated CI jobs M1.10 (ANSI C / C99 verification) and M1.11 (zero-external-dependency audit) close the row.

All other rows remain at 🚧 or ⏳ — the algorithm-bearing requirements (§2.1, §2.2, §2.3, §2.4, §3.1, §3.2, §4, §5 — create/alloc/free/destroy, §6.1, §6.2, §6.3) flip to ✅ across Milestones 2–6 as the real implementations replace the M1 stubs.

What this release does not contain

The Milestone 1 stubs return NULL / no-op. The free-list algorithm, the TypedPool<T> template, the dynamic growth mode, the thread-safe variant, the decorator-pattern instrumentation, and the benchmark vs malloc/free all arrive in Milestones 2–6 (v0.2.0 → v0.6.0). Pinning your build system against v0.1.0 gets you a linkable library that does nothing at runtime — useful for verifying integration and CMake wiring, not for measuring performance.

Distribution via vcpkg and Conan is gated on v1.0.0 per ADR-0004 §5; the only artifact channel during the 0.x line is GitHub Releases.

Verifying the release

Each platform tarball contains the public headers under include/it/d4np/memorypool/, the static archive under lib/ (libpbr_memory_pool.a on POSIX, pbr_memory_pool.lib on MSVC), and the top-level LICENSE, README.md, CHANGELOG.md. SHA-256 checksums of every attached artifact live in SHA256SUMS:

sha256sum --check SHA256SUMS

The release pipeline also re-runs the full CI matrix against the tagged commit — a green release workflow run is the canonical "the release is reproducible from a cold runner" signal.

Links