cmakeless 0.5.0__tar.gz

cmakeless-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main, bbs-dev]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Ninja
+        uses: seanmiddleditch/gha-setup-ninja@v5
+
+      # Ninja needs the MSVC environment on Windows to find cl.exe.
+      - name: Set up MSVC environment
+        if: runner.os == 'Windows'
+        uses: ilammy/msvc-dev-cmd@v1
+
+      # setup-uv already provisions and activates .venv when python-version
+      # is set, so installing into it directly is all that is needed.
+      - name: Install package with dev dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy src
+
+      # The network flag unskips the end-to-end dependency tests, which
+      # download and compile a real third-party package (fmt).
+      - name: Test
+        run: uv run pytest
+        env:
+          CMAKELESS_NETWORK_TESTS: "1"

cmakeless-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+# PyPI via Trusted Publishing (OIDC)
+# And GitHub Release with changelog section for this version.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+
+      # The version is hand-maintained in _version.py, so the pushed tag must
+      # match it; a mismatch means a release was tagged without a version bump.
+      # Read it with sed so the check needs no environment sync.
+      - name: Verify tag matches the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/cmakeless/_version.py)"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v$tag does not match cmakeless._version.__version__ ($version)."
+            echo "Bump src/cmakeless/_version.py to $tag, or retag to v$version."
+            exit 1
+          fi
+          echo "tag v$tag matches the package version."
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check the built distributions
+        run: uvx twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/cmakeless/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create the GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract the changelog entry for this tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '
+            $0 == "## [" v "]" {capture=1; next}
+            capture && /^## / {exit}
+            capture {print}
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "No changelog section for $version; using a generic note." > release-notes.md
+          fi
+
+      - name: Create the release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release-notes.md
+          files: dist/*
+          fail_on_unmatched_files: true

cmakeless-0.5.0/.gitignore

@@ -0,0 +1,24 @@
+PROMPTS.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+uv.lock
+
+# CMake build trees (out-of-source, always)
+build/
+CMakeUserPresets.json
+
+# Generated output inside example projects; regenerated from cmakelessfile.py.
+examples/**/CMakeLists.txt
+examples/**/CMakePresets.json
+examples/**/cmake/
+examples/**/compile_commands.json
+IMPROVEMENTS.md
+SUGGESTIONS.md

cmakeless-0.5.0/ARCHITECTURE.md

@@ -0,0 +1,189 @@
+# CMakeless Architecture
+
+This document describes how CMakeless is designed, how the codebase is organized, and why each decision was made. If [INTRODUCTION](INTRODUCTION.md) is the "why", this is the "how".
+
+## Design Goals
+
+Every architectural decision below serves four goals, in priority order:
+
+1. **A tiny, obvious public API.** The end user sees a handful of classes. Everything else is private machinery.
+2. **Fail early, fail in Python.** Every error that can be caught before CMake runs must be caught before CMake runs, and reported as a normal Python exception with a helpful message.
+3. **Readable output.** The generated `CMakeLists.txt` must look like an expert wrote it by hand: modern, target-centric, deterministic, diffable. Users must be able to walk away from CMakeless at any time and keep their build.
+4. **Delegate, never reimplement.** CMake does the real work: configuring, generating, building. CMakeless is a frontend, not a build system.
+
+## The Big Picture: Four Layers
+
+CMakeless is a strict layered architecture. Each layer depends only on the layer directly below it. Data flows down; results and errors flow back up.
+
+```text
++--------------------------------------------------------------+
+|  1. API layer          cmakeless/api/                         |
+|     What the user touches: Project, Executable, Library,     |
+|     Dependency, Toolchain, Preset. Friendly, forgiving,      |
+|     mutable while the user is describing the build.          |
++--------------------------------------------------------------+
+                              | freeze() + validate
+                              v
++--------------------------------------------------------------+
+|  2. Model layer        cmakeless/model/                       |
+|     The single source of truth: an immutable, validated      |
+|     build graph made of frozen dataclasses. No CMake         |
+|     knowledge, no subprocess calls, pure data.               |
++--------------------------------------------------------------+
+                              | visit
+                              v
++--------------------------------------------------------------+
+|  3. Emitter layer      cmakeless/emitter/                     |
+|     Walks the model and generates idiomatic, modern          |
+|     CMakeLists.txt, preset files, and toolchain files.       |
+|     Deterministic: same model in, same bytes out.            |
++--------------------------------------------------------------+
+                              | invoke
+                              v
++--------------------------------------------------------------+
+|  4. Driver layer       cmakeless/driver/                      |
+|     Runs cmake / ctest / cpack as subprocesses, consumes     |
+|     the CMake File API for structured results, and           |
+|     translates CMake failures into Python exceptions.        |
++--------------------------------------------------------------+
+```
+
+### Why layers, and why these layers
+
+The separation between **API** and **model** exists because the two have opposite needs. While the user is describing a build, objects must be mutable and forgiving (`app.link(engine)` after construction). Once description ends, everything downstream wants immutability: the emitter can cache, the validator can reason about the whole graph at once, and parallel threads can share the model without locks. `Project.build()` is the boundary: it freezes the API objects into the model, validates, and only then proceeds.
+
+The separation between **model** and **emitter** is what keeps us honest about goal 4. The model knows nothing about CMake syntax. This means the emitter is replaceable and testable in isolation (feed it a model, assert on the generated text), and it leaves the door open for other emitters later (for example, a compile_commands-only emitter for tooling) without touching the user-facing API.
+
+The separation between **emitter** and **driver** means generation never requires CMake to be installed. You can generate, inspect, and commit build files on a machine that has never seen a compiler. Only `build()`, `configure()`, and `test()` need the real tool.
+
+## The Public API
+
+The entire user-facing surface is intentionally small. This is the complete class list, and the intent is that it stays close to this size forever:
+
+| Class | Role |
+|---|---|
+| `Project` | The root object and facade. Owns targets, settings, and the `build()` / `configure()` / `test()` / `install()` verbs. |
+| `Executable` | A runnable target. Created via `project.add_executable(...)`. |
+| `Library` | A static, shared, or header-only library. Created via `project.add_library(...)`. |
+| `Dependency` | An external package requirement, usually created implicitly by `target.depends("fmt/10.2.1")`. |
+| `Toolchain` | A compiler/platform description for cross or pinned builds. |
+| `Preset` | A named bundle of configuration (build type, flags, toolchain) mapped onto CMake presets. |
+
+Users never import from `cmakeless.model`, `cmakeless.emitter`, or `cmakeless.driver`. Those are implementation details, and the package layout enforces it: only names re-exported in `cmakeless/__init__.py` are public, and the package ships `py.typed` so every signature is checked by the user's IDE and type checker.
+
+A deliberate non-feature: there is no CMakeless DSL, no YAML dialect, no magic globals. A `cmakelessfile.py` is a plain Python script that happens to import `cmakeless`. Anything Python can do (conditionals, loops, functions, reading environment variables, importing your own helper modules), your build description can do, with zero new semantics to learn.
+
+## Entry Points: `cmakelessfile.py` and the CLI
+
+The user's build description lives in **`cmakelessfile.py`** at the project root. This is a convention, not a requirement, chosen deliberately over a single-module design ("just one `cmakeless.py` file") for three reasons:
+
+1. `cmakelessfile.py` names the user's *intent* (this file builds the project), the way `conanfile.py` and `noxfile.py` do, while `cmakeless.py` would name our library and shadow the actual `cmakeless` package on the import path, a classic Python footgun.
+2. The library itself must be a package, not a module, because the four layers above need separate, privately importable subpackages to grow without breaking users.
+3. A predictable filename lets the CLI find the build description with zero configuration.
+
+Both invocation styles are first-class:
+
+```console
+$ python cmakelessfile.py   # the script is the tool
+$ cmakeless build           # the CLI finds cmakelessfile.py and runs it
+$ cmakeless configure --preset debug
+$ cmakeless test
+$ cmakeless clean
+$ cmakeless init            # scaffold a new project interactively
+```
+
+The `cmakeless` console script and `python -m cmakeless` share one implementation in `cmakeless/cli.py`.
+
+## Repository Layout
+
+Standard src-layout, so the installed package is what gets tested, not the working directory:
+
+```text
+cmakeless/
+├── pyproject.toml            # PEP 621 metadata; zero runtime dependencies
+├── README.md
+├── INTRODUCTION.md
+├── ARCHITECTURE.md           # this file
+├── FEATURES.md
+├── ROADMAP.md
+├── CONTRIBUTING.md
+├── CHANGELOG.md
+├── src/
+│   └── cmakeless/
+│       ├── __init__.py       # the ONLY public import surface
+│       ├── py.typed
+│       ├── cli.py
+│       ├── errors.py         # exception hierarchy (see below)
+│       ├── api/              # layer 1: Project, targets, deps, toolchains
+│       ├── model/            # layer 2: frozen dataclasses, validation
+│       ├── emitter/          # layer 3: model -> CMakeLists.txt
+│       ├── driver/           # layer 4: subprocess + CMake File API
+│       └── deps/             # dependency-provider strategies (see below)
+├── tests/
+│   └── unittests/            # mirrors src/ structure; pytest
+├── examples/                 # runnable example projects, smallest first
+└── docs/
+```
+
+`pyproject.toml` declares **zero runtime dependencies**. A tool whose reason to exist is reducing build friction cannot itself bring a dependency tree. The standard library is enough: `dataclasses` for the model, `subprocess` for the driver, `json` for the File API, `argparse` for the CLI.
+
+## Design Patterns, Named
+
+CMakeless uses classic, institutional patterns deliberately, so that any contributor can locate responsibility by name:
+
+- **Facade.** `Project` is a facade over the entire pipeline. `project.build()` hides freeze, validate, emit, configure, and compile behind one verb. The library as a whole is a facade over CMake.
+- **Builder.** The API layer is a builder for the model layer: users incrementally describe (`add_library`, `link`, `depends`), then `freeze()` produces the immutable product.
+- **Visitor.** The emitter is a visitor over the build graph. Each node type (executable, library, test, install rule) has a visit method that contributes its section of the generated file. New node types plug in without modifying the traversal.
+- **Strategy.** Anything with interchangeable backends is a strategy behind a small interface: CMake generators (Ninja, Visual Studio, Xcode), and above all **dependency providers**.
+- **Adapter.** Each dependency provider in `cmakeless/deps/` (FetchContent, `find_package`, vcpkg, Conan) adapts a foreign tool to the single internal `DependencyProvider` interface, so `target.depends("fmt/10.2.1")` never changes when the backend does.
+- **Composite.** A `Project` may contain subprojects; targets and subprojects form a tree that the emitter and validator traverse uniformly.
+- **Template Method.** Target emission shares a fixed skeleton (declare, sources, properties, links, install) with per-target-type overrides, which is what keeps the generated CMake uniform and boring.
+- **Observer.** The driver publishes progress events (configure started, target compiled, test finished) to subscribers, so the CLI progress display, IDE integrations, and CI log formatting are listeners, not special cases inside the driver.
+
+## Error Handling: Errors Are a Feature
+
+The single biggest quality-of-life difference over raw CMake is *when* and *how* things fail. The rules:
+
+1. **Validate at freeze time.** Unknown source files, dependency cycles, linking a test-only target into a release binary, a typo in a C++ standard: all reported before CMake is ever invoked, with the offending `cmakelessfile.py` line in the traceback.
+2. **Translate at run time.** When CMake or the compiler does fail, the driver parses the output and raises a structured exception instead of dumping a wall of text.
+3. **One hierarchy.** Everything raised on purpose derives from `CmakelessError`:
+
+```text
+CmakelessError
+├── ConfigurationError      # invalid build description (caught at freeze)
+├── DependencyError         # package cannot be resolved/fetched
+├── ToolchainError          # compiler/toolchain missing or misconfigured
+└── CMakeError              # CMake itself failed; carries parsed stderr,
+                            # the exact command line, and the log path
+```
+
+Every message must say three things: what went wrong, where (file and target), and what to try next. A message that fails the "what to try next" test is a bug.
+
+## Free-Threaded Python: Parallelism Where It Pays
+
+CMakeless targets Python 3.13+ and is designed for the free-threaded interpreter (PEP 703, supported non-experimentally since 3.14). The immutable model layer is what makes this safe and cheap: frozen dataclasses can be shared across threads with no locks and no copies.
+
+Parallelism is applied only where wall-clock time actually lives:
+
+- **Dependency resolution.** Fetching and resolving N external packages is embarrassingly parallel network and disk I/O; each provider strategy runs in its own thread.
+- **Multi-configuration emission.** Emitting Debug/Release/RelWithDebInfo trees, or several presets, are independent pure functions over the same frozen model.
+- **Orchestration.** Driving multiple CMake configurations or test partitions concurrently, with the Observer events merged into one coherent progress stream.
+
+On a standard GIL build everything still works; the executor degrades to interleaved I/O concurrency, which is where most of the benefit is anyway. Detection is a single startup check (`sys._is_gil_enabled()`), never a fork in the codebase.
+
+The compile itself is *not* our parallelism: that belongs to Ninja and the compiler, and per goal 4 we delegate it.
+
+## What the Emitter Must Guarantee
+
+Because the generated `CMakeLists.txt` is our public face to the rest of the ecosystem, it has its own contract:
+
+- **Modern, target-centric CMake only.** `target_include_directories`, `target_compile_features`, `target_link_libraries` with explicit visibility. Never directory-level globals, never `include_directories()`, never `file(GLOB)` at configure time (globs are expanded by CMakeless in Python, where they can be validated).
+- **Deterministic.** Same model in, byte-identical output out. Sorted where order is arbitrary. This makes output committable and diffs reviewable.
+- **Self-describing.** A generated header comment states the CMakeless version and the source `cmakelessfile.py`, so a reader landing in the file knows where the truth lives.
+- **Standalone.** The output must build with plain `cmake` on a machine without Python. This is the no-lock-in promise made mechanical.
+
+## Read Next
+
+- [FEATURES](FEATURES.md): The complete feature surface built on this architecture.
+- [ROADMAP](ROADMAP.md): The order in which these layers get built.
+- [CONTRIBUTING](CONTRIBUTING.md): How to help build them.

cmakeless-0.5.0/CHANGELOG.md

@@ -0,0 +1,293 @@
+# Changelog
+
+All notable changes to CMakeless are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0]
+
+The language unlock: options, typed conditions, and custom build steps —
+the last things standing between "a nicer way to write the easy 90% of
+CMake" and the full power of CMake, in Python, with types and a debugger.
+
+### Changed
+
+- **Breaking: the default build description filename is now `cmakelessfile.py`**
+  (was `build.py`). `cmakeless.py` was considered and rejected: on a
+  case-insensitive filesystem (Windows, macOS) it would collide with the
+  installed `cmakeless` package, making `from cmakeless import Project`
+  inside the script resolve to itself. `cmakelessfile.py` names the tool the
+  way `Dockerfile`/`Jenkinsfile` do, with no such collision. Since the
+  project has not published a stable release yet, there is no migration
+  path: rename `build.py` to `cmakelessfile.py` in existing projects.
+- **Breaking: the Python floor is now 3.12** (was 3.13). IMPROVEMENTS.md
+  originally suggested 3.10 for the widest possible reach, but the codebase
+  already uses PEP 695 syntax (`type X = ...` aliases, `def f[T](...)`
+  generics) introduced in 3.12; keeping the floor at 3.12 avoids rewriting
+  that syntax while still covering most current LTS/CI base images. CI now
+  tests 3.12 and 3.13 across all three OSes.
+- **Breaking: `target.compile_options(..., when=...)` now accepts a `When`
+  condition** (see Added, below), or the pre-existing `"gcc|clang"`-style
+  compiler string, kept as sugar. The underlying model field is
+  `when: WhenModel | None`, replacing `compilers: tuple[str, ...]`.
+- **Breaking: `DependencyProvider.pre_configure()`/`.toolchain_args()` now
+  require a `build_type` argument.** Fixes the Conan adapter silently
+  installing Release dependencies under a Debug preset (IMPROVEMENTS §2.2):
+  the active preset's (or `project.optimize`'s) build type now flows all the
+  way through to `conan install -s build_type=...`.
+- ccache/sccache are now wired for Unix Makefiles and Ninja Multi-Config too,
+  not just Ninja (IMPROVEMENTS §2.6); new generator shorthands `"ninja-multi"`,
+  `"make"`, and `"xcode"` join `"ninja"` and `"vs"`.
+- `find_package(Python ...)` now requests the interpreter actually running
+  CMakeless, not a hard-coded `3.13` (IMPROVEMENTS §2.5).
+
+### Added
+
+- **`When` conditions** (SUGGESTIONS §2.2): `When.platform(...)`,
+  `When.compiler(...)`, `When.config(...)`, and `When.option(...)`,
+  composable with `&`/`|`/`~`, rendered as CMake generator expressions.
+  Wired into `define()`, `compile_options()`, and the new `link_options()`.
+- **Project options** (IMPROVEMENTS §2.3, SUGGESTIONS §2.1):
+  `project.option(name, default=..., help=..., type=...)` declares a typed
+  CMake cache variable, discoverable with the new `cmakeless options` verb
+  (lists every declared option without building anything) and usable in
+  `When.option(...)`.
+- **Expanded presets**: `Preset(options={...}, env={...}, inherits="base")`
+  so a preset can set cache-variable overrides, an environment block, and
+  inherit from another preset (IMPROVEMENTS §2.3), validated the same way
+  toolchain references already are.
+- **Custom build steps** (SUGGESTIONS §1): `project.add_command(output=[...],
+  command=[...], depends=[...], comment=...)` for code-generation and
+  asset-cooking steps, and `project.add_custom_target(name, command=[...],
+  depends=[...])` for always-run targets (lint, docs). A command's output
+  feeds a target's `add_sources()` directly; an output nothing consumes is a
+  soft freeze-time warning, not a build error.
+- **Target vocabulary completion** (IMPROVEMENTS §2.4): `target.include_dirs(...)`
+  (private include directories on any target kind, closing the gap next to
+  `Library(public_headers=...)`), `target.link_options(...)` (mirrors
+  `compile_options()`), a per-target `cpp_std` override, and
+  `target.pch = [...]`/`target.unity = True` for precompiled headers and
+  unity builds — retiring the `raw_cmake()` workaround the escape hatch's
+  own docstring used to demonstrate.
+- **An extensible dependency registry** (IMPROVEMENTS §2.1):
+  `cmakeless.register_dependency(name, RegistryEntry(...))` registers or
+  overrides one package, and installed plugin distributions can contribute
+  entries via the `"cmakeless.registry"` entry-point group. The curated list
+  itself stays the same eleven packages for now; growing it from vcpkg/Conan
+  metadata at scale is future work (see ROADMAP.md sub-phase 4.4).
+
+### Docs
+
+- `ROADMAP.md`'s Phase 4 is now followed by sub-phases 4.1–4.3 (this
+  release) and 4.4–4.6 (planned: the interop unlock, the portability
+  release, and documentation/quality debt — see ROADMAP.md for what each
+  covers).
+- `FEATURES.md` and `README.md` updated throughout for the new surface.
+
+## [0.4.1]
+
+Sensible defaults, the escape hatch, and a release pipeline: the polish that
+makes the interop and quality-of-life work land in a real project.
+
+### Changed
+
+- **Default binding backend is now pybind11** (was nanobind):
+  `add_python_module(name, sources)` builds a pybind11 extension unless you pass
+  `binding="nanobind"`. This is a behavior change for callers that relied on the
+  implicit default.
+- **Default test framework is now GoogleTest** (was Catch2):
+  `add_test(name, sources)` fetches and links GoogleTest unless you pass
+  `framework="catch2"` (or `"doctest"`/`"none"`). Also a behavior change for the
+  implicit default.
+
+### Added
+
+- **The escape hatch (FEATURES section 9), now implemented**:
+  `target.raw_cmake("...")` emits a verbatim CMake snippet after the target is
+  defined, and `project.raw_cmake_file("cmake/extra.cmake")` includes an existing
+  CMake file near the top of the generated `CMakeLists.txt`. Both are fenced with
+  a comment naming their `cmakelessfile.py` origin; `raw_cmake_file` paths are validated
+  to exist inside the project root at freeze time.
+- **Project-level `optimize` and `lto`** (FEATURES section 3): `project.optimize =
+  "release"` and `project.lto = True` set the default (no-preset) build type and
+  interprocedural optimization. Both are emitted behind CMake guards, so an active
+  preset always wins.
+- **A tag-driven release workflow** (`.github/workflows/release.yml`): pushing a
+  `v*` tag builds the sdist and wheel, publishes to PyPI via Trusted Publishing
+  (OIDC, no stored token), and cuts a GitHub Release from the matching changelog
+  section. The pushed tag is checked against `_version.py`.
+
+### Docs and examples
+
+- Rewrote `README.md` into a fuller, discoverable front door: the philosophy,
+  a concrete end-to-end workflow, a feature tour, and an ecosystem comparison.
+- Reworked `examples/07_python_module` into a real pybind11 module (a `Vec2`
+  type with operators, properties, and C++-to-Python exception translation),
+  and added `examples/08_capstone`: one `cmakelessfile.py` shipping a library as a CLI,
+  a GoogleTest suite, and a pybind11 module, with presets, install/export, CPack,
+  and a live Observer.
+- Corrected the project URLs to `github.com/bbalouki/cmakeless`.
+
+## [0.4.0]
+
+Interop and parallelism: the differentiators. A pybind11 project migrates its
+binding build to one `add_python_module` call, and multi-preset configure runs
+concurrently.
+
+### Added
+
+- **Python and C++ interop**: `project.add_python_module(name, sources,
+  binding="nanobind")` builds a C++ extension with nanobind or pybind11. The
+  binding backend is acquired like any dependency (pinned in `cmakeless.lock`),
+  the module is built against the invoking interpreter's development headers,
+  `.pyi` stubs are generated for nanobind, and after `cmakeless build` the
+  module is copied into the current environment, so `import <name>` works
+  immediately.
+- **Observer event API**: `project.add_observer(observer)` registers a
+  consumer that receives a `StepStarted`/`StepFinished`/`StepFailed` event for
+  every configure, build, test, install, and package step, so IDE extensions
+  and CI log formatters are listeners rather than special cases. The console
+  display is now just the default `ConsoleObserver`. `Observer`, `BuildEvent`,
+  and the event classes join the public API.
+- **CMake File API**: `project.targets_info()` configures the build and returns
+  it as `TargetInfo` objects (name, type, artifacts, sources, dependencies),
+  read from CMake's File API rather than scraped from text.
+- **Free-threaded parallelism, measured**: `project.configure_presets()`
+  configures every preset concurrently, each into its own build tree, over one
+  lock-free frozen model. A reproducible `benchmarks/` harness and published
+  numbers for parallel dependency resolution and multi-preset configure live in
+  [docs/benchmarks.md](docs/benchmarks.md).
+- `PythonModule`, `Observer`, `BuildEvent`, `StepStarted`, `StepFinished`,
+  `StepFailed`, `ConsoleObserver`, and `TargetInfo` join the public API;
+  `cmakeless.api` now re-exports the full layer-1 surface. Registry entries for
+  pybind11 and nanobind.
+- A new runnable project, `examples/07_python_module`.
+
+## [0.3.0]
+
+Quality of life: everything that turns "it builds" into "it ships". A
+library author can build, test (sanitized), install, and package a release
+on CI using only `cmakelessfile.py`.
+
+### Added
+
+- **Testing as a verb**: `project.add_test(name, sources, framework=...)`
+  with Catch2, GoogleTest, and doctest auto-integration (the framework is
+  acquired like any dependency and pinned in `cmakeless.lock`), CTest
+  registration with per-case discovery, and shared-library tests that run
+  on Windows without PATH rituals. `cmakeless test` builds and runs the
+  suite; `framework="none"` registers a plain pass/fail executable.
+- **Sanitizers**: `target.sanitize = ["address", "undefined"]` applied to
+  compile *and* link (the half-applied-sanitizer bug is not reproducible
+  through this API), translated per compiler, and rejected loudly where
+  unsupported. `cmakeless test --sanitize=address` runs the suite under a
+  sanitizer in its own build tree.
+- **`Preset` API**: `project.add_preset(Preset("release",
+  optimize="release", lto=True))` generates `CMakePresets.json` (with
+  build and test presets), so CLion, Visual Studio, and VS Code pick the
+  configurations up natively. Every preset gets its own out-of-source
+  build tree under `build/<name>`; `--preset` works on build, configure,
+  test, install, and package.
+- **`Toolchain` API**: `Toolchain.from_file(...)` wraps existing toolchain
+  files unchanged; `Toolchain(name, compiler=..., system_name=...)`
+  generates simple cross-compilation files under `cmake/toolchains/`.
+  Presets reference toolchains by name.
+- **Install and packaging**: `project.install(target, headers=True)` emits
+  GNUInstallDirs-correct install rules, export sets, and
+  `Config.cmake`/`ConfigVersion.cmake` generation so other CMake users can
+  `find_package()` the result; `project.package(formats=["zip", "deb"])`
+  configures CPack. New `cmakeless install --prefix ...` and `cmakeless
+  package` verbs.
+- **Tooling by default**: `compile_commands.json` is always exported and
+  copied to the project root; ccache/sccache are auto-detected and wired
+  as the compiler launcher on Ninja builds (opt out with `project.cache =
+  False`).
+- `Preset`, `Toolchain`, and `Test` join the public API. Curated registry
+  pins for the default test framework versions (catch2 3.5.4, googletest
+  1.14.0, doctest 2.4.11), so test projects resolve without network.
+- Two new runnable projects: `examples/05_testing` and `examples/06_ship`.
+
+## [0.2.0]
+
+Dependencies: `app.depends("fmt/10.2.1")` works through four backends, and
+resolution is reproducible from the lockfile alone.
+
+### Added
+
+- **`target.depends("name/version")`**: one line per external package, with
+  `components=` for packages like boost and `public=` visibility. Escape
+  hatches (`url=`, `sha256=`, `cmake_name=`, `targets=`) make any package
+  usable, not just the built-in registry's.
+- **Built-in package registry**: the folklore raw CMake makes you memorize
+  (`fmt::fmt` is not `fmt`, googletest is `GTest`, the vcpkg port of
+  nlohmann_json is `nlohmann-json`) curated for fmt, spdlog, catch2,
+  doctest, googletest, nlohmann_json, zlib, and boost.
+- **The default acquisition strategy**: emitted CMake tries `find_package`
+  first and falls back to `FetchContent` pinned by URL and SHA256, so the
+  generated file stays standalone.
+- **`cmakeless.lock`**: byte-deterministic JSON lockfile written on every
+  resolution; a complete lockfile resolves with zero network. Refresh it
+  with `project.dependencies.lock()` or the new `cmakeless lock` verb.
+- **`find_package` backend** (`project.package_manager = "find_package"`):
+  system packages only, version-checked, no source fetches.
+- **vcpkg backend** (`project.package_manager = "vcpkg"`): generates
+  `vcpkg.json` (with `builtin-baseline` and version constraints when
+  available) and wires the vcpkg toolchain file into the configure step.
+- **Conan 2 backend** (`project.package_manager = "conan"`): generates
+  `conanfile.txt`, runs `conan install` before configure, and wires the
+  generated toolchain file.
+- **Parallel resolution**: dependencies resolve in one thread each,
+  correct on GIL builds and fast on free-threaded ones; completion order
+  never leaks into the emitted files or the lockfile.
+- `Dependency` joins the public API; `DependencyError` is now raised.
+- A fourth runnable project, `examples/04_dependencies`.
+
+## [0.1.0] 
+
+The MVP: a small self-contained C++ project can use CMakeless instead of
+hand-written CMake.
+
+### Added
+
+- **Full target set**: `Library` targets ("static", "shared", "header_only")
+  next to `Executable`, with public header directories, correct
+  `PUBLIC`/`PRIVATE`/`INTERFACE` visibility, position-independent code, and
+  Windows export handling via `generate_export_header` for shared libraries.
+- **The link graph**: `target.link(...)` with `public=` visibility on
+  library-to-library links, `INTERFACE` chosen automatically for header-only
+  libraries, and link-cycle detection at freeze time that names the cycle.
+- **Compile settings**: `warnings` presets ("strict", "default", "none")
+  translated per compiler, `target.define(...)`, and
+  `target.compile_options(..., when="gcc|clang")` guards.
+- **Glob sources**: patterns like `src/*.cpp` are expanded and validated in
+  Python; a pattern matching zero files is a `ConfigurationError`.
+- **Subprojects**: `project.add_subproject(path)` composes self-contained
+  child projects (their own `cmakelessfile.py`); every generated file is standalone.
+- **Driver**: generator selection ("ninja", "vs", or any raw CMake `-G`
+  name) and error translation that parses CMake, GCC/Clang, MSVC, and linker
+  failures into structured diagnostics on `CMakeError`.
+- **Emitter contract**: byte-deterministic output enforced by golden-file
+  tests.
+- **CLI**: `cmakeless configure`, `cmakeless clean`, and `cmakeless init`
+  scaffolding next to `cmakeless build`.
+- Three runnable projects under `examples/`, smallest first, and a seeded
+  `docs/` landing page.
+
+## [0.0.1] 
+
+Phase 0: the walking skeleton through all four layers.
+
+### Added
+
+- Walking skeleton through all four layers (API, model, emitter, driver).
+- `Project` and `Executable` public API; `project.build()` freezes, validates,
+  emits `CMakeLists.txt`, and drives CMake configure + build.
+- Freeze-time validation: missing source files are reported as
+  `ConfigurationError` before CMake ever runs.
+- `cmakeless build` CLI and `python -m cmakeless`; `python cmakelessfile.py` works as
+  a first-class entry point.
+- Exception hierarchy: `CmakelessError` with `ConfigurationError`,
+  `DependencyError`, `ToolchainError`, and `CMakeError`.