From 6c6b3eacccc9f11f761144fd2ae82ae176275c7b Mon Sep 17 00:00:00 2001 From: Mark Schaller Date: Sat, 26 Sep 2026 02:31:02 -0400 Subject: [PATCH] Name the three configure-step strategies and their costs SKILL.md lists configure_file among the things to warn the user about before proceeding, without saying what to do instead. Unattended agents do not stop, so they improvise, and the skill gave them nothing to improvise against: the choice of how to replace CMake's configure step was made silently and its cost was invisible until someone rebuilt from a clean checkout. Measured in any2bazel-lab, three strategies on larger projects: - consume CMake's build directory as Bazel sources (a MySQL Server migration, which cited the skill's scope boundary as the reason): the Bazel build does not rebuild from the repository at all; - implement configure_file as a Starlark rule (the unguided MySQL Server migration): rebuilds, and reproduced 15 of 15 comparable generated files byte-identically; - check in the probe results as static headers (GDAL, CMake): builds, but the configuration is no longer derived. On CMake itself two runs of the same prompt checked in all 28 configure-time headers; one matched the reference byte for byte, the other differed in three, including a curl_config.h that disables HSTS and a libarchive config.h that falls back to built-in hashes despite OpenSSL being present. Nothing in the diff can see this. The scope list, in SKILL.md and in docs/REFERENCE-cmake.md's scope traps, now covers build-time codegen only, and points configure_file to a new section of docs/REFERENCE-cmake.md beside the build type: prefer a Starlark configure_file rule; checking in a probe result is acceptable for one platform if the file says so and it is verified file by file against the configure output it came from; never point Bazel at CMake's build directory. Whether build-time codegen should also move from "stop" to guidance is a separate change, later in this series. In the lab's later runs with this change, all four agents that met a configure step derived it (a Starlark rule or captured substitutions), and on CMake's sources the three headers that had differed came out byte-identical in all three runs. Lab-Proposal: P20, P21, P5 Co-Authored-By: Claude Opus 5.5 --- SKILL.md | 5 +++-- docs/REFERENCE-cmake.md | 14 ++++++++++++-- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/SKILL.md b/SKILL.md index b2e3912..62d3bd6 100644 --- a/SKILL.md +++ b/SKILL.md @@ -229,7 +229,8 @@ Inspect the reference build for anything unsupported. Surface them and confirm with the user before proceeding. **NOT yet supported — warn the user if the project has these:** -- Custom commands / generated code +- Build-time custom commands / generated code. Configure-time generated + files are handled by you, not the tool: see the reference guide. - Per-test-binary identity alignment, and include search **order** (presence only) — both have planned follow-ups - Packaging / install rules @@ -271,7 +272,7 @@ generated `.bazelrc` so a declared version that MVS overrides fails the build instead of being a warning nobody reads. The reference guide covers what is specific to translating its build system -(for CMake: the build type). +(for CMake: the build type and configure-time generated files). ### Main migration loop {#main-migration-loop} diff --git a/docs/REFERENCE-cmake.md b/docs/REFERENCE-cmake.md index db36825..37c6c98 100644 --- a/docs/REFERENCE-cmake.md +++ b/docs/REFERENCE-cmake.md @@ -14,8 +14,9 @@ as the reference build. When [confirming scope](../SKILL.md#confirm-scope), inspect `CMakeLists.txt` for these and surface them before proceeding: -- Generated code: `configure_file`, `add_custom_command`, protoc or other - codegen steps. +- Build-time generated code: `add_custom_command`, protoc or other codegen + steps. `configure_file` is handled by you, not the tool: see + [Configure-time generated files](#configure-time-generated-files). - `find_package` of non-system libraries. There is no automatic `find_package` → bzlmod resolution; each one must be mapped by hand. @@ -63,6 +64,15 @@ also turns assertions off where the reference keeps them (`ndebug` in `diff.json`); `build --copt=-UNDEBUG` undoes the toolchain's `-DNDEBUG`, not one in a rule's `copts`. +### Configure-time generated files + +For `configure_file` and probe headers, prefer a Starlark `configure_file` rule +over the `.in` template, so the configuration stays derived. Checking in a +probe's result is acceptable for one platform if the file says so and you +verify it, file by file, against the configure output it came from. Never +point Bazel at CMake's build directory: that will not rebuild from the +repository, which is worse than migrating less. + ## CMake-specific comparison notes - **Target names** in `target_map` and `exclude_targets` keys are CMake target