102 lines
2.8 KiB
Groff
102 lines
2.8 KiB
Groff
.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 .
|