4.6 KiB
Development Guide
Repository: sourcedock.dev/petrbalvin/gasm-devkit
Prerequisites
- Go 1.27+ with
toolchain go1.27.0 - just, the command runner; every task below is a just recipe
- No external dependencies beyond the Go toolchain
Quick Start
git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
cd gasm-devkit
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 build
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
go test -count=1 -timeout 30m -coverprofile=coverage.out \
-coverpkg=./arch/...,./asm/...,./ast/...,./disasm/...,./format/...,./lexer/...,./lint/...,./lsp/...,./parser/...,./token/...,./verify/... \
./...
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 race
The same suite under the race detector. The expensive one, so it runs
once, inside gates.
just unit
just unit ./asm/ TestVexGroundTruth
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 -buildvcs=true:
just run -- lint kernel_amd64.s
just run -- fmt -w kernel_amd64.s
just run -- verify --ground-truth kernel_amd64.s
just install
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
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, with no runtime dependency on the
toolchain.
just uninstall
Removes coverage.out, the gasm binary, and *.test artefacts.
Running Individual Tests
go test -run TestVexGroundTruth ./asm/
go test -run TestGroundTruthBasic ./verify/
go test -run TestGOObjectLinkAndRun ./asm/
go test -run TestFuzzWideCopy ./verify/
Debugger Note
gasm debug spawns a child process from the binary on $PATH. It does
not work with go run; install first:
just install
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 (all four architectures)
_gen/ Instruction table generator
testdata/ Test fixtures
docs/ Architecture, development, CLI reference