.TH GASM 1 "2026-09-19" "gasm" "User Commands"
.SH NAME
gasm \- developer tooling for Go's Plan 9 assembler
.SH SYNOPSIS
.B gasm
.I command
.RI [ arguments ]
.br
.B gasm
.BR \-h | \-\-help
.br
.B gasm
.BR \-V | \-\-version
.SH DESCRIPTION
.B gasm
bundles a lexer, parser, formatter, linter, standalone assembler and
language server for Plan 9 assembly into one self-contained binary.  It
serves two purposes: it brings developer tooling to the
.I .s
files of Go programs, and it assembles Plan 9 assembly to raw images or
linkable ELF objects with DWARF5 debug sections without the Go toolchain at
all, plus the Go toolchain's own GOOBJ format, which
.B go build
consumes directly.  GOOBJ is the one format that needs the toolchain
installed: the object preamble is captured from
.B go tool asm
and the format version from
.BR "go version" .
.PP
Four architectures are covered: amd64 (including VEX/AVX2 and
EVEX/AVX-512), arm64, riscv64 (RV64IMAFDC and RVC) and loong64.  The
target architecture is inferred from the file-name suffix
(\fI_amd64.s\fR, \fI_arm64.s\fR, \fI_riscv64.s\fR, \fI_loong64.s\fR) or
named explicitly with \fB\-GOARCH\fR where the commands accept it.
.SH COMMANDS
.TP
.B gasm\-tokens(1)
Print the lexical token stream.
.TP
.B gasm\-parse(1)
Parse a file and report syntax errors.
.TP
.B gasm\-fmt(1)
Canonicalise formatting: gofmt for assembly.
.TP
.B gasm\-lint(1)
Run the static checks.
.TP
.B gasm\-asm(1)
Assemble \fI.s\fR files to machine code, raw images, ELF objects or GOOBJ.
.TP
.B gasm\-dis(1)
Disassemble machine code, raw bytes or an assembled \fI.s\fR file.
.TP
.B gasm\-verify(1)
JIT-assemble and run dynamic checks: smoke calls, ABI checks,
differential fuzzing, ground-truth comparison.
.TP
.B gasm\-debug(1)
Interactive source-level debugger.
.TP
.B gasm\-diff(1)
Compare the machine code of two files byte-for-byte.
.TP
.B gasm\-profile(1)
Show the basic-block structure of functions.
.TP
.B gasm\-audit\-instructions(1)
Diff the encoder against the Go toolchain's name table, or measure a
corpus of \fI.s\fR files.
.TP
.B gasm\-scaffold(1)
Generate a differential test skeleton for a kernel file.
.TP
.B gasm\-lsp(1)
Run the language server over standard input/output.
.TP
.B gasm version
Print the version, the same as \fB\-\-version\fR.
.SH GLOBAL FLAGS
.TP
.BR \-h ", " \-\-help
Show the command overview.
.TP
.BR \-V ", " \-\-version
Print the version the toolchain recorded at build time.
.SH EXIT STATUS
Exits 0 on success, 1 when a command fails, and 2 on a usage error.  An
unknown command exits 2; \fBgasm debug\fR exits 3 when \-\-timeout kills
the debuggee.
.SH SEE ALSO
.BR gasm\-asm (1),
.BR gasm\-fmt (1),
.BR gasm\-lint (1),
.BR gasm\-verify (1),
.BR gasm\-debug (1)
.PP
The full command reference, with worked examples and every flag, is in
docs/CLI.md of the repository
.UR https://sourcedock.dev/petrbalvin/gasm-devkit
.UE .