gasm-sdk/docs/DEVELOPMENT.md

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 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

go test -race -count=1 -coverprofile=coverage.out ./...

Plus an awk gate that fails if total coverage is below 80 %.

just fmt

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:

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

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:

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
s/             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