docs: state verify-build's dist/ guarantee at the width it enforces (closes #331)
check_dist_tree walks -type f -o -type l, so the emitted-tree cross-check covers regular files and symlinks under dist/. README.md said "nothing under dist/ that the build did not write", which is broader: fifos, sockets, device nodes and empty directories are not checked. The exclusion stays. A build emits none of those types, none can carry a shippable payload, and grep on a fifo would hang rather than fail. README.md, the script's header comment and the check_dist_tree comment now say so in the same words, so the code and the docs cannot drift apart again. Documentation only: no non-comment line of script/verify-build changed.
This commit is contained in:
41
README.md
41
README.md
@@ -81,17 +81,21 @@ lives.
|
||||
one of the bundles containing `src/shared/constants.js` — into a build receipt,
|
||||
and `script/verify-build` checks `dist/` against that receipt: every recorded
|
||||
file present with exactly the recorded bytes, every audited bundle carrying the
|
||||
requested `DEBUG` marker, and nothing under `dist/` that the build did not
|
||||
write. The `Makefile` creates the receipt path with `mktemp` per invocation,
|
||||
outside the repo, and deletes it afterwards.
|
||||
requested `DEBUG` marker, and no regular file or symlink under `dist/` that the
|
||||
build did not write. The `Makefile` creates the receipt path with `mktemp` per
|
||||
invocation, outside the repo, and deletes it afterwards.
|
||||
|
||||
That is what ties the check to a build rather than to a directory. What it
|
||||
establishes is narrow and worth stating exactly: `dist/` is byte for byte the
|
||||
output of the `build.js` run that just finished, with nothing added, removed or
|
||||
altered in between. It establishes nothing about whether the source tree or
|
||||
`build.js` were honest, and it offers nothing to someone handed a `dist/` from
|
||||
elsewhere — without the receipt from its own build there is no input to the
|
||||
check. Verifiable provenance for a third party is signing, which this is not.
|
||||
output of the `build.js` run that just finished, with no regular file or symlink
|
||||
added, removed or altered in between. Regular files and symlinks are the whole
|
||||
of what the tree walk covers; fifos, sockets, device nodes and empty directories
|
||||
under `dist/` are not checked, because a build emits none of them, none can
|
||||
carry a shippable payload, and grep on a fifo would hang rather than fail. It
|
||||
establishes nothing about whether the source tree or `build.js` were honest, and
|
||||
it offers nothing to someone handed a `dist/` from elsewhere — without the
|
||||
receipt from its own build there is no input to the check. Verifiable provenance
|
||||
for a third party is signing, which this is not.
|
||||
|
||||
There is deliberately no target that re-verifies an existing `dist/` on its own.
|
||||
The list of files to check has to come from the build that produced them; read
|
||||
@@ -143,16 +147,17 @@ provide:
|
||||
serves. Run deliberately, never as part of a build: the output is committed
|
||||
and there is no runtime fetch, so the shipped list is as fresh as the last
|
||||
vendoring run that was released
|
||||
- `script/verify-build --expect release|debug --receipt PATH` — assert that
|
||||
`dist/` is exactly what the build that just ran emitted, and that the compiled
|
||||
`DEBUG` state of the bundles in it is the one that was asked for. Both
|
||||
arguments are required and neither has a default: the expected mode is stated
|
||||
by the caller rather than read from `AUTISTMASK_DEBUG`, and the file list
|
||||
comes from the build's receipt rather than from `dist/` (see
|
||||
[Build Receipts](#build-receipts)). Run automatically at the end of
|
||||
`make build` and `make build-debug`; fails loudly rather than passing whenever
|
||||
it cannot determine something. Not part of `make check`, which does not depend
|
||||
on build artifacts existing.
|
||||
- `script/verify-build --expect release|debug --receipt PATH` — assert that the
|
||||
regular files and symlinks under `dist/` are exactly what the build that just
|
||||
ran emitted (other file types are out of scope; see
|
||||
[Build Receipts](#build-receipts)), and that the compiled `DEBUG` state of the
|
||||
bundles in it is the one that was asked for. Both arguments are required and
|
||||
neither has a default: the expected mode is stated by the caller rather than
|
||||
read from `AUTISTMASK_DEBUG`, and the file list comes from the build's receipt
|
||||
rather than from `dist/` (see [Build Receipts](#build-receipts)). Run
|
||||
automatically at the end of `make build` and `make build-debug`; fails loudly
|
||||
rather than passing whenever it cannot determine something. Not part of
|
||||
`make check`, which does not depend on build artifacts existing.
|
||||
- `script/test-verify-build` — exercise every failure mode of
|
||||
`script/verify-build` against a fixture tree in a temp dir, asserting the exit
|
||||
status and the message of each, and read the `make build` and
|
||||
|
||||
Reference in New Issue
Block a user