docs: add the full documentation surface — AGENTS, CONTRIBUTING, cli and development references

Assisted-by: DeepSeek V4 Flash
2026-08-01 05:22:00 +02:00
parent 89d633f4bb
commit c77d68018c
7 changed files with 1519 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Development Guide
+
+Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
+## Prerequisites
+
+- **Go** 1.26+ with `toolchain go1.26.5`
+- **just** — the command runner; every task below is a just recipe
+- No external dependencies beyond the Go toolchain
+
+## Quick Start
+
+```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 Recipes
+
+### `just build`
+
+Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
+the minimum bar before any commit.
+
+### `just test`
+
+```sh
+go test -race -count=1 -coverprofile=coverage.out ./...
+```
+
+Plus an `awk` gate that fails if total coverage is below 80 %.
+
+### `just fmt`
+
+```sh
+gofmt -w .
+```
+
+Run after editing any Go source. The output must be idempotent.
+
+### `just run -- <args>`
+
+Runs the CLI via `go run` with the version string stamped:
+
+```sh
+just run -- lint kernel_amd64.s
+just run -- fmt -w kernel_amd64.s
+just run -- verify --ground-truth kernel_amd64.s
+```
+
+### `just install-bin`
+
+Installs the `gasm` binary into `$GOBIN` with the release version
+embedded via `-ldflags "-X main.version=..."`.
+
+### `just gen`
+
+Regenerates the architecture instruction tables in `arch/` by parsing
+the Go toolchain's own assembler source
+(`$GOROOT/src/cmd/internal/obj/<arch>/anames.go`). Requires a Go
+installation. Output is committed — no runtime dependency on the
+toolchain.
+
+### `just uninstall`
+
+Removes `coverage.out`, the `gasm` binary, and `*.test` artefacts.
+
+## Running Individual Tests
+
+```sh
+go test -run TestVexGroundTruth ./asm/
+go test -run TestDifferentialLZ4Fuzz ./verify/
+go test -run TestFLACDecorrelate ./verify/
+go test -run TestGOObjectLinkAndRun ./asm/
+```
+
+## Debugger Note
+
+`gasm debug` spawns a child process from the binary on `$PATH`. It does
+not work with `go run` — install first:
+
+```sh
+just install-bin
+gasm debug --func decodeBlockAVX2 path/to/kernel_amd64.s
+```
+
+## Project Layout
+
+```
+cmd/gasm/           CLI entry point (subcommands)
+token/              Lexical token kinds and positions
+lexer/              Hand-written scanner
+ast/                Abstract syntax tree
+parser/             Line-oriented parser
+arch/               Register and instruction tables (generated)
+lint/               Static analysis rules
+format/             Canonical formatter
+lsp/                Language Server Protocol server
+asm/                Standalone assembler, encoder, object emitters
+verify/             JIT execution, differential testing, ABI checks
+debug/              Interactive ptrace debugger (linux/amd64)
+_gen/               Instruction table generator
+testdata/           Test fixtures
+docs/               Architecture, development, CLI reference
+```