docs: move the recipe and version descriptions with the behaviour

Assisted-by: GLM 5.3 Flash
2026-09-16 22:53:01 +02:00
parent 20e4b8d9c4
commit d08523caa5
3 changed files with 79 additions and 37 deletions
@@ -10,9 +10,8 @@ command runner, and a Linux host on amd64, arm64, riscv64 or loong64.
 ```sh
 git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
 cd gasm-devkit
-just install        # download module dependencies
-just build          # go vet + gofmt check
-just test           # full suite, race detector, 80 % coverage gate
+just build          # compile, zero errors and zero warnings
+just gates          # build, fmt-check, vet, test, race: the definition of done
 ```

 ## Workflow
@@ -40,7 +39,7 @@ CI builds and publishes the binaries for all four architectures.

 ## Code style

-`gofmt` and `go vet` via `just fmt` / `just build`; both must pass with
+`gofmt` and `go vet` via `just fmt` / `just vet`; both must pass with
 zero output; `go fix -diff ./...` must report nothing on touched packages.

 - Standard library only in production code; `golang.org/x/arch` is used
@@ -63,7 +62,7 @@ go test -run TestFuzzWideCopy ./verify/

 The interactive debugger (`gasm debug`) requires a compiled binary on
 `$PATH`; `go run` does not work for the traced child process.  Install
-first with `just install-bin`.
+first with `just install`.

 ## CI (Gitea Actions)

@@ -71,11 +70,12 @@ Workflows live in `.gitea/workflows/` and run on self-hosted runners:

 | Workflow | Trigger | What it does |
 |----------|---------|--------------|
-| Test | push / PR to `development` | gofmt check, `go vet`, `go test -race`, 80 % coverage gate |
-| Release | tag `v*` | cross-compiles binaries for linux/{amd64,arm64,riscv64,loong64} and publishes the Gitea release |
+| Test | push / PR to `development` | the `gates` set minus race: gofmt, `go vet`, `go fix`, build, the suite, the 80 % coverage floor |
+| Race | manual dispatch, and inside the release | the suite under the race detector |
+| Release | tag `v*` | the gates once, then cross-compiles binaries for linux/{amd64,arm64,riscv64,loong64} and publishes the Gitea release |

-The Definition of Done (`just build` + `just test` + `just fmt`) must
-still pass locally before pushing.
+The Definition of Done (`just gates`) must still pass locally before
+pushing.

 ## AI Contribution Policy

@@ -78,12 +78,15 @@ From source (Go 1.27 or later):
 go install sourcedock.dev/petrbalvin/gasm-devkit/cmd/gasm@latest
 ```

-Or from a repository checkout, with the development version stamped:
+Or from a repository checkout:

 ```sh
-just install-bin
+just install
 ```

+The installed binary reports the version the toolchain recorded: the tag
+on a tagged checkout, a pseudo-version naming the commit below one.
+
 ## Quick start

 ```sh
@@ -142,9 +145,9 @@ infers the target architecture from the file-name suffix
 ## Development

 ```sh
-just install      # download module dependencies
-just build        # go vet + gofmt check, zero errors and zero warnings
-just test         # full suite, race detector, 80 % coverage gate
+just build        # compile, zero errors and zero warnings
+just test         # the suite, no cache, the 80 % coverage floor
+just gates        # build, fmt-check, vet, test, race: the definition of done
 just fmt          # gofmt the tree
 just gen          # regenerate the instruction tables from the Go toolchain
 ```
@@ -13,45 +13,71 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
 ```sh
 git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
 cd gasm-devkit
-just install   # go mod download
-just build     # go vet + gofmt, must pass with zero output
-just test      # full suite, race detector, 80 % coverage gate
+just build     # compile bin/gasm, zero errors and zero warnings
+just gates     # build, fmt-check, vet, test, race: the definition of done
 ```

 ## Just Recipes

-### `just install`
-
-`go mod download`.  The only module dependency, `golang.org/x/arch`, is
-used in tests only.
-
 ### `just build`

-Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
-the minimum bar before any commit.
+Compiles `bin/gasm` with `CGO_ENABLED=0` and stripped symbols. Zero
+errors, zero warnings. This is the minimum bar before any commit.
+
+### `just gates`
+
+The definition of done, in one command: `build`, `fmt-check`, `vet`,
+`test` and `race`, in that order. Run it once per task, never per edit;
+`just unit` is the one that runs after every edit.

 ### `just test`

 ```sh
-go test -race -count=1 ./...
+go test -count=1 -timeout 30m -coverprofile=coverage.out \
+    -coverpkg=./arch/...,./asm/...,./ast/...,./disasm/...,./format/...,./lexer/...,./lint/...,./lsp/...,./parser/...,./token/...,./verify/... \
+    ./...
 ```

-Plus a coverage run over the ten analysable packages (arch, asm, ast,
-format, lexer, lint, lsp, parser, token, verify; `debug` and `cmd/gasm`
-need hardware or are CLI glue) and an `awk` gate that fails if total
-coverage is below 80 %.
+The whole suite runs (`-count=1`, so no cached pass counts), which keeps
+the packages that need hardware and the CLI glue under the gate. The
+coverage floor is computed over the product packages only (arch, asm,
+ast, disasm, format, lexer, lint, lsp, parser, token, verify; `debug`
+traces a live process and `cmd/gasm` is CLI glue) and fails if the total
+is below 80 %.

-### `just fmt`
+### `just race`
+
+The same suite under the race detector. The expensive one, so it runs
+once, inside `gates`.
+
+### `just unit`

 ```sh
-gofmt -w .
+just unit ./asm/ TestVexGroundTruth
 ```

-Run after editing any Go source. The output must be idempotent.
+Fast, cached, scoped run for iterating: no race, no coverage, so an
+unchanged package reports instantly.
+
+### `just fuzz <target> <pkg>`
+
+Time-boxed fuzz of one target in one package; the package is required,
+because `go test -fuzz` refuses more than one. Seed corpora run as plain
+tests in `unit` and `test`. Never a gate.
+
+### `just bench`
+
+Benchmarks (`-benchmem -count=5`). On an idle machine only.
+
+### `just fmt`, `just fmt-check`, `just vet`
+
+`fmt` formats in place. `fmt-check` prints nothing when everything is
+formatted, which is the shape the CI step wants. `vet` runs both static
+gates: `go vet` and `go fix -diff`.

 ### `just run -- <args>`

-Runs the CLI via `go run` with the version string stamped:
+Runs the CLI via `go run -buildvcs=true`:

 ```sh
 just run -- lint kernel_amd64.s
@@ -59,10 +85,23 @@ just run -- fmt -w kernel_amd64.s
 just run -- verify --ground-truth kernel_amd64.s
 ```

-### `just install-bin`
+### `just install`

-Installs the `gasm` binary into `$GOBIN` with the release version
-embedded via `-ldflags "-X main.version=..."`.
+Builds and copies the `gasm` binary into `~/.local/bin` (`BINDIR`
+overrides the destination).
+
+### `just uninstall`, `just clean`
+
+`uninstall` removes the installed binary from `bindir`. `clean` removes
+the build artefacts: `bin/` and `coverage.out`.
+
+## Version reporting
+
+The version is never injected. `gasm --version` prints what the
+toolchain recorded in the build information: the tag on a tagged
+checkout, a pseudo-version naming the commit below one, `+dirty` on a
+dirty tree, and `(devel)` outside version control. There is no
+`-ldflags "-X"` anywhere and no version constant in the source.

 ### `just gen`

@@ -91,7 +130,7 @@ go test -run TestFuzzWideCopy ./verify/
 not work with `go run`; install first:

 ```sh
-just install-bin
+just install
 gasm debug --func decodeBlockAVX2 path/to/kernel_amd64.s
 ```