109 lines
2.8 KiB
Markdown
109 lines
2.8 KiB
Markdown
|
# 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
|
||
|
|
```
|