diff --git a/AGENTS.md b/AGENTS.md index 6d7b0b1..f5d7735 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -189,4 +189,4 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary: - A warning is printed only when its unit actually recompiles. A build with nothing to do is silent, which is not evidence that a warning is gone. - A std module source only compiles against the headers of its own libc++ release, and a sysroot does not always ship one (Alpine). The Flatpak therefore carries the sources of the release next to the bundled one under `share/crafter-build/libc++-modules//`, one `libcxx--modules` manifest module each. When the bundled LLVM is bumped, keep the release it leaves behind as such a module: sysroots on the stable distro stay on it for months. The native loop has no such directory; stage one by hand under `share/crafter-build/` to test against a foreign sysroot. - `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. -- The self-host build and `test` keep the dependency notes section of this very file. None of Crafter.Math, Crafter.Asset and Crafter.LintRules ships an `AGENTS.consumer.md` yet; once one does, building here appends the section. Commit it with the change that pulled it in. +- The self-host build and `test` keep the dependency notes section of this very file. None of Crafter.Math, Crafter.Asset and Crafter.LintRules ships an `AGENTS.consumer.md` yet. Once one does, a build here can change AGENTS.md whenever that repository changes its notes, since all three are unpinned. The tree is then dirty, so the next build's `git describe --dirty` version differs, which is a new `crafter.build-lib` variant and a full rebuild. Commit the section to settle it. diff --git a/README.md b/README.md index bb4b533..56b27c0 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ An agent working on a project reads its `AGENTS.md`, which says nothing about th - + ## Crafter.Math ... @@ -110,21 +110,22 @@ An agent working on a project reads its `AGENTS.md`, which says nothing about th ``` -- Each file goes in as written, under a line naming where it came from: the git URL, or for a `LocalProject` the file's path relative to the consumer. It lands among the consumer's own headings, so start it with a `##` heading that names the library. -- The section is appended the first time and rewritten in place after that, wherever it has been moved to. Edits inside it are lost on the next build; the rest of the file is never touched. The file is written only when the section changes, and an `AGENTS.md` is never created. -- The update runs after `project.cpp` loads and before anything compiles, so a build that fails still has the notes. `lint`, `format`, `run` and `clean` leave the file alone. -- An unpinned dependency's notes follow its default branch, as its code does, so the section can change on any build. Pin a `commit` to decide when. -- Unbalanced markers leave the file as it is, and a notes file that would break the section (a code block it never closes, a marker line of its own) is left out; both are reported as warnings. Markers quoted inside a fenced code block don't count. +- Each file goes in as written, under a line naming the dependency: its repository's name, or a `LocalProject`'s directory name. That reads the same on every machine, and for a `--local` checkout and its git clone alike. The file lands among the consumer's own headings, so start it with a `##` heading that names the library. +- The section is appended the first time, after a blank line, and rewritten in place after that, wherever it has been moved to. Edits inside it are lost on the next build; the text around it is left as it is. The file is written only when the section changes, in place, so hard links, ownership and a read-only `AGENTS.md` are respected, and an `AGENTS.md` is never created. +- The update runs once `project.cpp` has loaded and before the project compiles, so a build that fails still has the notes. A `project.cpp` that fails to load gets no update. `test --list`, `lint`, `format`, `run` and `clean` leave the file alone. +- The section follows what the build loaded: a dependency that only some flags pull in (a `--target=`, a flag of the project's own) comes and goes with them. An unpinned dependency's notes follow its default branch, as its code does, so the section can change on any build. Pin a `commit` to decide when. +- A library reached through two specs, pinned at one revision here and another further down, is described once, as the nearer one has it. +- When there are notes to write, unbalanced markers leave the file as it is, with a warning. A notes file that would break the section (a code block it never closes, a marker line of its own) is left out, also with a warning. Markers quoted inside a fenced code block don't count. `cfg.dependencyNotes` picks the dependencies: | Value | Notes from | |---|---| -| `DependencyNotes::Transitive` (default) | everything the project builds against, all the way down: its `dependencies`, its tests' dependencies and its own `#pragma crafter dependency` tooling | -| `DependencyNotes::Direct` | only the projects the project's own configurations, tests and `#pragma crafter dependency` lines name | +| `DependencyNotes::Transitive` (default) | everything the project builds against, all the way down: its `dependencies` and its own `#pragma crafter dependency` tooling | +| `DependencyNotes::Direct` | only the projects the project's own configurations and `#pragma crafter dependency` lines name | | `DependencyNotes::None` | none, and a section from an earlier build is removed | -Two things never count: the project's own `AGENTS.consumer.md`, and a dependency's `#pragma crafter dependency` tooling, which is about how the dependency is built, not how it is used. +Three things never count: the project's own `AGENTS.consumer.md`; its tests' dependencies, since a plain build never looks at the tests; and a dependency's `#pragma crafter dependency` tooling, which is about how the dependency is built, not how it is used. ## Tests