.TH GASM-ASM 1 "2026-09-19" "gasm" "User Commands"
.SH NAME
gasm-asm \- assemble Plan 9 assembly without the Go toolchain
.SH SYNOPSIS
.B gasm asm [\-\-format raw|elf|goobj] [\-p pkg] [\-GOARCH arch] [\-o out] <file>
.SH DESCRIPTION
Assemble FILE without the Go toolchain: every TEXT function is encoded
to machine code and printed as a hex dump.  Supported architectures:
amd64 (including VEX/AVX2 and EVEX/AVX-512), arm64 (AArch64 integer,
FP, conditional select, CRC32 and MOV pseudo), riscv64 (RV64IMAFDC and
RVC) and loong64 (LoongArch base ISA).
.PP
With
.B \-o
the output is written to a file instead.  The
.B \-\-format
flag selects what is written:
.B raw
(the default) concatenates the functions and the data section into one
self-consistent image;
.B elf
emits a relocatable object (.text/.data sections, a symbol table and
one PC32 relocation per static-symbol reference) that links with the
system toolchain;
.B goobj
emits the Go toolchain's own object format, which cmd/link consumes
directly (it requires
.BR \-p ,
the package path, and the installed Go toolchain).
.PP
Framed functions receive the stack-split guard and the trailing
morestack block, byte-identical to the toolchain's output, so split
functions link too.
.SH OPTIONS
.TP
.B \-\-format \fIraw|elf|goobj\fR
Output format; the default is raw.
.TP
.B \-p \fIpkg\fR
Package path for --format goobj, qualifying the exported symbols.
.TP
.B \-GOARCH \fIarch\fR
Target architecture: amd64, arm64, riscv64 or loong64; overrides the
file-name suffix, which is how the suffix-less majority of GOROOT's
files (cpu_x86.s, stub.s, ...) become assemblable.
.TP
.B \-o \fIfile\fR
Write the output to this file instead of a hex dump on stdout.
.SH EXIT STATUS
Exits 0 on success, 1 when parsing or assembly fails, and 2 on a usage
error.
.SH EXAMPLES
.nf
gasm asm \-o hello.bin hello_amd64.s               raw image
gasm asm \-\-format elf \-o k.o k.s                 linkable ELF object
gasm asm \-\-format goobj \-p pkg/path \-o k.o k.s   Go object for go build
gasm asm \-GOARCH amd64 cpu_x86.s                  arch override
.fi
.SH SEE ALSO
.BR gasm (1),
.BR gasm\-dis (1),
.BR gasm\-verify (1)