From d08523caa54cd37ac234a710cb27c557d87d4170 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Balv=C3=ADn?= Date: Wed, 16 Sep 2026 22:53:01 +0200 Subject: [PATCH] docs: move the recipe and version descriptions with the behaviour Assisted-by: GLM 5.3 Flash --- CONTRIBUTING.md | 18 +++++----- README.md | 13 ++++--- docs/DEVELOPMENT.md | 85 +++++++++++++++++++++++++++++++++------------ 3 files changed, 79 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a81505..e9024b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index 85f198a..05ff119 100644 --- a/README.md +++ b/README.md @@ -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 ``` diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index b78eb9d..9ecfbab 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -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 ` + +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 -- ` -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 ```