From 5c3e9a874b1abf8e6f218f02b838509270b36745 Mon Sep 17 00:00:00 2001 From: Jorijn van der Graaf Date: Sat, 31 Oct 2026 16:56:11 +0100 Subject: [PATCH] docs: keep this repository's agent notes in AGENTS.template.md This repository now uses the template itself. AGENTS.md is written by the self-host build and `test` and is gitignored, so the notes Crafter.Math ships reach the agents working here, and a change to them no longer leaves a tracked file modified, which also made every build afterwards a dirty-tree version, a new crafter.build-lib variant and a full rebuild. The gotcha that described the old arrangement now says where to edit, that a fresh clone or worktree has no AGENTS.md until its first build (./build.sh does not write it), and what an older harness does to the generated file. The paths table and the never-commit list name both files. The CI error for a missing signing key and a manifest comment point at the template, since the forge no longer shows an AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- .forgejo/workflows/ci.yaml | 2 +- .gitignore | 2 ++ AGENTS.md => AGENTS.template.md | 5 +++-- packaging/flatpak/net.catcrafts.CrafterBuild.yaml | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) rename AGENTS.md => AGENTS.template.md (96%) diff --git a/.forgejo/workflows/ci.yaml b/.forgejo/workflows/ci.yaml index ec1a47a..0f2e7ad 100644 --- a/.forgejo/workflows/ci.yaml +++ b/.forgejo/workflows/ci.yaml @@ -140,7 +140,7 @@ jobs: # (/etc/crafter-flatpak: signing-key.asc and key-id) and mounted # read-only; it is imported into a throwaway keyring per run. if [ ! -s /run/crafter-flatpak/signing-key.asc ] || [ ! -s /run/crafter-flatpak/key-id ]; then - echo "no signing key under /etc/crafter-flatpak on the runner host; generate it as described in AGENTS.md (CI and publishing)" >&2 + echo "no signing key under /etc/crafter-flatpak on the runner host; generate it as described in AGENTS.template.md (CI and publishing)" >&2 exit 1 fi export GNUPGHOME=$(mktemp -d) diff --git a/.gitignore b/.gitignore index 67d2a68..bb506eb 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ share/crafter-build/ .claude # written by CI next to the manifest so relative source paths still resolve packaging/flatpak/ci-manifest.yaml +# written by every build and test run from AGENTS.template.md +/AGENTS.md diff --git a/AGENTS.md b/AGENTS.template.md similarity index 96% rename from AGENTS.md rename to AGENTS.template.md index eab0c32..cb23933 100644 --- a/AGENTS.md +++ b/AGENTS.template.md @@ -11,6 +11,7 @@ crafter-build is a C++26 modules build system. A project is described by a `proj | `interfaces/Crafter.Build-.cppm` | Module interface partitions. `Crafter.Build.cppm` is the umbrella that re-exports them. | | `implementations/Crafter.Build-.cpp` | Implementation units, one per partition, named `Crafter.Build:_impl`. `main.cpp` is a thin wrapper around `Crafter::Run`. | | `project.cpp` | The self-host build description: a `crafter.build-lib` library, a `crafter.build-exe` executable, the test declarations, the lint rules and the `flatpak` and `install` scripts. | +| `AGENTS.template.md` | The source of AGENTS.md. Every build and test run writes AGENTS.md from it, with the notes the dependencies ship; AGENTS.md is gitignored, so changes go here. | | `tests//main.cpp` | One self-test per directory; `tests//fixture/` holds the sample project it builds. | | `examples/` | Standalone user-facing projects, MIT licensed. | | `build.sh` | Bootstrap script. It compiles everything by hand, without crafter-build. | @@ -141,7 +142,7 @@ These were decided deliberately. Do not undo them without the maintainer's say-s - Separate commits for the fix, its test and the README change when each stands on its own. - Update the README in the same PR when user-visible behaviour changes. - `format`, `lint` and `test` green before pushing. CI builds the Flatpak and runs the suite inside it on PRs, publishes the `beta` branch of the Catcrafts repo on every push to `master`, and the `stable` branch plus a release on an `X.Y.Z` tag. -- Never commit `bin/`, `build/`, `share/crafter-build/`, `lib/*.a` or fixture build outputs (all gitignored), and never edit the vendored files in `lib/`. +- Never commit `bin/`, `build/`, `share/crafter-build/`, `lib/*.a`, `AGENTS.md` or fixture build outputs (all gitignored), and never edit the vendored files in `lib/`. - Keep `CRAFTER_BUILD_MARCH=x86-64-v2` in the manifest for the shipped binary: it has to run on any x86_64 machine. User projects still default to `native`. ## Security considerations @@ -194,4 +195,4 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary: - The wasm compile flags live in one place, `WasmBaselineFlags` in `Crafter.Build-Clang.cppm`: the std module and every unit have to agree on them, and `VariantId()` and the std PCM directory hash them, so a change rebuilds instead of mixing old and new BMIs. They enable C++ exceptions, so the link takes the exception-enabled libc++ and libunwind from the sysroot's `lib//eh/` (wasi-sdk 33 and later). The Flatpak's sysroot has them and a distro's may not; where they are missing the wasm tests skip, so run those through the Flatpak. A browser page checks the engine with the `WasmBaselineProbes` named in `variants.json`. - `WasiBrowserRuntimeExit` runs `wasi-runtime/runtime.js` under node and skips where there is none. The Flatpak has no node, so CI never runs it: after touching `runtime.js`, run the suite in the native loop with node on `PATH`. - `VariantId()` names the output directory, so CI globs `bin/crafter.build-exe---*/` rather than predicting the hash. The hash includes the compiler, so after a toolchain update the previous variant's directories stay in `bin/` and `build/` until `clean`, and such a glob matches both. -- This repository has no `AGENTS.template.md`, so the self-host build and `test` leave this file alone, and the `AGENTS.consumer.md` Crafter.Math ships does not reach it. A template would make this file build output: it would go into `.gitignore`, and a fresh clone or worktree would have no AGENTS.md until its first build. +- AGENTS.md is build output: the self-host build and `test` write it from `AGENTS.template.md`, with the `AGENTS.consumer.md` of each dependency that ships one (Crafter.Math, today) merged in, and it is gitignored. Edit the template; an edit made in AGENTS.md is gone after the next build. A fresh clone or worktree has no AGENTS.md until its first `./bin/crafter-build` or `test`, since `./build.sh` does not write it. A harness from before the template (3.0.0 and older) never creates one and keeps its section in one it finds; the next build with a current harness writes it over. diff --git a/packaging/flatpak/net.catcrafts.CrafterBuild.yaml b/packaging/flatpak/net.catcrafts.CrafterBuild.yaml index f812261..562a3fb 100644 --- a/packaging/flatpak/net.catcrafts.CrafterBuild.yaml +++ b/packaging/flatpak/net.catcrafts.CrafterBuild.yaml @@ -224,7 +224,7 @@ modules: build-options: # The self-host build fetches Crafter.Math, Crafter.Asset, # Crafter.LintRules and glslang from git; they are unpinned on purpose - # (sibling repos tracking their default branch, see AGENTS.md). + # (sibling repos tracking their default branch, see AGENTS.template.md). build-args: - --share=network # On this module, not at the top of the manifest: top-level build