.Dd October 3, 2026
.Dt UASM 1
.Os "uasm 2.57r"
.Sh NAME
.Nm uasm
.Nd Masm-compatible macro assembler
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar asm-file ...
.Op Ar @ Ns Ar env_var
.Sh DESCRIPTION
.Nm
assembles Intel syntax assembly into object files or flat binaries.
It is a fork of JWasm and reads Masm source: the
.Ic .MODEL
directive, the
.Ic .PROC
and
.Ic .ENDP
procedure forms and the usual segment and data directives all work, and an
internal macro library provides the Masm mnemonics.
Extensions over Masm, and the places where the syntax differs from it, are
listed in
.Pa Doc/enh.txt .
.Pp
Unless another output format is selected, objects are written in Intel OMF.
Formats such as
.Fl bin ,
.Fl mz
and
.Fl pe
produce a linked image rather than a relocatable object, and are meant for
boot sectors, DOS and Windows executables.
.Pp
Any number of source files may be given, each with its own options.
Arguments prefixed with
.Ql @
read further options from an environment variable, or from a file named by it.
.Sh OPTIONS
.Ss Output format
.Bl -tag -width Ds
.It Fl bin
Plain binary output.
.It Fl coff
MS COFF object, 32-bit.
.It Fl elf
ELF object, 32-bit.
.It Fl elf64
ELF object, 64-bit.
.It Fl macho64
Mach-O object, 64-bit.
.It Fl mz
DOS MZ executable.
.It Fl omf
Intel OMF object.
This is the default.
.It Fl pe
Windows PE executable, 32 or 64-bit.
.It Fl win64
MS COFF object, 64-bit.
.It Fl pie
Generate a position independent image.
ELF64 and Mach-O64 only.
.El
.Ss File names
.Bl -tag -width Ds
.It Fl Fo Ar file
Write the object to
.Ar file .
A name without an extension gets
.Ql .o
appended.
.It Fl Fl Ar file
Write a listing to
.Ar file .
.It Fl Fw Ar file
Write errors to
.Ar file .
.It Fl Fi Ar file
Include
.Ar file
before assembling.
.It Fl I Ar directory
Add
.Ar directory
to the include path.
.It Fl D Ar name Op Ns = Ns Ar text
Define a text macro.
.El
.Ss Code generation
.Bl -tag -width Ds
.It Op Fl 0 ... Fl 10 Op Ar p
Set the target CPU, from 8086 (0, the default) to x86-64 (10).
A trailing
.Ar p
allows privileged instructions.
.It Fl arch Ar SSE | Ar AVX
Select the instruction set extensions the macro library generates for.
.It Fl G Ar p | Ar c | Ar f | Ar z
Set the calling convention to Pascal, C, Fastcall or stdcall.
.It Fl m Ar t | Ar s | Ar c | Ar m | Ar l | Ar h | Ar f
Set the memory model.
.It Fl Zp Op Ar n
Set the structure alignment to
.Ar n .
.It Fl Sp Op Ar n
Set the segment alignment to
.Ar n .
.It Fl Zg
Generate code that matches Masm byte for byte.
.It Fl nomlib
Do not use the internal macro library.
.It Fl zcm , Fl zcw
Decorate C names with a leading underscore, or leave them alone.
.El
.Ss Diagnostics
.Bl -tag -width Ds
.It Fl W Ar level
Set the warning level, 0 to 4.
The default is 2.
.It Fl WX
Treat warnings as errors.
.It Fl e Ar number
Stop after
.Ar number
errors.
The default is 50.
.It Fl Zs
Check the syntax only.
.It Fl eq
Do not report errors.
.It Fl q , Fl nologo
Do not print the version banner.
.El
.Ss Listing contents
.Bl -tag -width Ds
.It Fl EP
Write the preprocessed source to standard output.
.It Fl Sa
Produce a maximal source listing.
.It Fl Sf
List the first pass.
.It Fl Sg
Include the generated code in the listing.
.It Fl Sn
Omit the symbol table from the listing.
.It Fl Sx
List false conditionals.
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev INCLUDE
A colon separated list of include directories, added to by
.Fl I .
.El
.Sh EXIT STATUS
.Nm
exits with status 0 when every file assembled without an error, and non-zero
otherwise.
.Sh EXAMPLES
Write a freestanding 64-bit Linux program that prints a line, and link it:
.Bd -literal -offset indent
$ cat hello.asm
        .code
PUBLIC _start
_start:
        lea     rdx, msg
        mov     ecx, edx
        mov     edx, len
        mov     eax, 1           ; sys_write
        mov     edi, 1           ; stdout
        syscall
        mov     eax, 60          ; sys_exit
        xor     edi, edi
        syscall

msg     db      'hello, world', 10
len     equ     $-msg
        END

$ uasm -10p -elf64 -Fo hello.o hello.asm
$ gcc -nostdlib -static -o hello hello.o
$ ./hello
hello, world
.Ed
.Sh SEE ALSO
.Pa /usr/share/doc/uasm
holds the upstream readme, the change log, the licence and the developer notes
under
.Pa Doc/ .

.