docs: sync README, CHANGELOG and docs with the current state
This commit is contained in:
+17
-9
@@ -5,7 +5,7 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
|
||||
## Prerequisites
|
||||
|
||||
- **Go** 1.27+ with `toolchain go1.27.0`
|
||||
- **just** — the command runner; every task below is a just recipe
|
||||
- **just**, the command runner; every task below is a just recipe
|
||||
- No external dependencies beyond the Go toolchain
|
||||
|
||||
## Quick Start
|
||||
@@ -14,12 +14,17 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
|
||||
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 build # go vet + gofmt, must pass with zero output
|
||||
just test # full suite, race detector, 80 % coverage gate
|
||||
```
|
||||
|
||||
## Just Recipes
|
||||
|
||||
### `just install`
|
||||
|
||||
`go mod download`. The only module dependency, `golang.org/x/arch`, is
|
||||
used in tests only.
|
||||
|
||||
### `just build`
|
||||
|
||||
Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
|
||||
@@ -28,10 +33,13 @@ the minimum bar before any commit.
|
||||
### `just test`
|
||||
|
||||
```sh
|
||||
go test -race -count=1 -coverprofile=coverage.out ./...
|
||||
go test -race -count=1 ./...
|
||||
```
|
||||
|
||||
Plus an `awk` gate that fails if total coverage is below 80 %.
|
||||
Plus a coverage run over the ten analysable packages (arch, asm, ast,
|
||||
format, lexer, lint, lsp, parser, token, verify; `debug` and `cmd/gasm`
|
||||
need hardware or are CLI glue) and an `awk` gate that fails if total
|
||||
coverage is below 80 %.
|
||||
|
||||
### `just fmt`
|
||||
|
||||
@@ -61,7 +69,7 @@ embedded via `-ldflags "-X main.version=..."`.
|
||||
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
|
||||
installation. Output is committed, with no runtime dependency on the
|
||||
toolchain.
|
||||
|
||||
### `just uninstall`
|
||||
@@ -72,15 +80,15 @@ Removes `coverage.out`, the `gasm` binary, and `*.test` artefacts.
|
||||
|
||||
```sh
|
||||
go test -run TestVexGroundTruth ./asm/
|
||||
go test -run TestDifferentialLZ4Fuzz ./verify/
|
||||
go test -run TestFLACDecorrelate ./verify/
|
||||
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:
|
||||
not work with `go run`; install first:
|
||||
|
||||
```sh
|
||||
just install-bin
|
||||
@@ -97,7 +105,7 @@ ast/ Abstract syntax tree
|
||||
parser/ Line-oriented parser
|
||||
arch/ Register and instruction tables (generated)
|
||||
lint/ Static analysis rules
|
||||
s/ Canonical formatter
|
||||
format/ Canonical formatter
|
||||
lsp/ Language Server Protocol server
|
||||
asm/ Standalone assembler, encoder, object emitters
|
||||
verify/ JIT execution, differential testing, ABI checks
|
||||
|
||||
Reference in New Issue
Block a user