gasm-sdk/docs/DEVELOPMENT.md

# Development Guide

Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://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

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