156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# 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
|
|
```
|