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

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

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

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

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

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