yasm/yasm.1

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "YASM" 1 "September 2004" "YASM" "YASM Modular Assembler"
.SH NAME
yasm \- The YASM Modular Assembler
.SH "SYNOPSIS"
.ad l
.hy 0
.HP 5
\fByasm\fR [\fB\-f\ \fIformat\fR\fR] [\fB\-o\ \fIoutfile\fR\fR] [\fB\fIoptions\fR\fR...] [\fIinfile\fR]
.ad
.hy
.ad l
.hy 0
.HP 5
\fByasm\fR \fB\-h\fR
.ad
.hy

.SH "DESCRIPTION"

.PP
The YASM Modular Assembler is a portable, retargetable assembler written under the ``new'' (2 or 3 clause) BSD license\&. It is designed from the ground up to allow for multiple assembler syntaxes (parsers) to be supported in addition to multiple output object formats and multiple instruction sets\&. Another primary module of the overall design is an optimizer module\&.

.PP
YASM consists of the \fByasm\fR command, libyasm, the core backend library, and a large number of loadable modules\&. On some platforms, libyasm and the loadable modules are statically built into the \fByasm\fR executable rather than being dynamically loaded\&.

.PP
The \fByasm\fR command assembles the file infile and directs output to the file \fIoutfile\fR if specified\&. If \fIoutfile\fR is not specified, \fByasm\fR will derive a default output file name from the name of its input file, usually by appending \fI\&.o\fR or \fI\&.obj\fR, or by removing all extensions for a raw binary file\&. Failing that, the output file name will be \fIyasm\&.out\fR\&.

.PP
If called without an \fIinfile\fR, \fByasm\fR assembles the standard input and directs output to the file \fIoutfile\fR, or \fIyasm\&.out\fR if no \fIoutfile\fR is specified\&.

.SH "OPTIONS"

.PP
Many options may be given in one of two forms: either a dash followed by a single letter, or two dashes followed by a long option name\&.

.PP
The following general options are available:

.TP
\fB\-\-version\fR
Prints yasm version information and license summary to standard output\&. All other options are ignored, and no output file is generated\&.

.TP
\fB\-h\fR or \fB\-\-help\fR
Prints a summary of invocation options\&. All other options are ignored, and no output file is generated\&.

.TP
\fB\-a \fIarch\fR\fR or \fB\-\-arch=\fIarch\fR\fR
Selects the target architecture\&. The default architecture is ``x86'', which supports both the IA\-32 and derivatives and AMD64 instruction sets\&. To print a list of available architectures to standard output, use ``help'' as \fIarch\fR\&. See \fByasm_arch\fR(7) for more details\&.

.TP
\fB\-p \fIparser\fR\fR or \fB\-\-parser=\fIparser\fR\fR
Selects the parser (the assembler syntax)\&. The default parser is ``nasm'', which emulates the syntax of NASM, the Netwide Assembler\&. To print a list of available parsers to standard output, use ``help'' as \fIparser\fR\&.

.TP
\fB\-r \fIpreproc\fR\fR or \fB\-\-preproc=\fIpreproc\fR\fR
Selects the preprocessor to use on the input file before passing it to the parser\&. Preprocessors often provide macro functionality that is not included in the main parser\&. The default preprocessor is ``nasm'', which is an imported version of the actual NASM preprocessor\&. A ``raw'' preprocessor is also available, which simply skips the preprocessing step, passing the input file directly to the parser\&. To print a list of available preprocessors to standard output, use ``help'' as \fIpreproc\fR\&.

.TP
\fB\-f \fIformat\fR\fR or \fB\-\-oformat=\fIformat\fR\fR
Selects the output object format\&. The default object format is ``bin'', which is a flat format binary with no relocation\&. To print a list of available object formats to standard output, use ``help'' as \fIformat\fR\&.

.TP
\fB\-g \fIdebug\fR\fR or \fB\-\-dformat=\fIdebug\fR\fR
Selects the debugging format for debug information\&. Debugging information can be used by a debugger to associate executable code back to the source file or get data structure and type information\&. Available debug formats vary between different object formats; \fByasm\fR will error when an invalid combination is selected\&. The default object format is selected by the object format\&. To print a list of available debugging formats to standard output, use ``help'' as \fIdebug\fR\&.

.TP
\fB\-L \fIlist\fR\fR or \fB\-\-lformat=\fIlist\fR\fR
Selects the format/style of the output list file\&. List files typically intermix the original source with the machine code generated by the assembler\&. The default list format is ``nasm'', which mimics the NASM list file format\&. To print a list of available list file formats to standard output, use ``help'' as \fIlist\fR\&.

.TP
\fB\-o \fIfilename\fR\fR or \fB\-\-objfile=\fIfilename\fR\fR
Specifies the name of the output file, overriding any default name selected by \fByasm\fR\&.

.TP
\fB\-l \fIlistfile\fR\fR or \fB\-\-list=\fIlistfile\fR\fR
Specifies the name of the output list file\&. If this option is not used, no list file is generated\&.

.TP
\fB\-m \fImachine\fR\fR or \fB\-\-machine=\fImachine\fR\fR
Selects the target machine architecture\&. Essentially a subtype of the selected architecture, the machine type selects between major subsets of an architecture\&. For example, for the ``x86'' architecture, the two available machines are ``x86'', which is used for the IA\-32 and derivative 32\-bit instruction set, and ``amd64'', which is used for the 64\-bit instruction set\&. This differentiation is required to generate the proper object file for relocatable object formats such as COFF and ELF\&. To print a list of available machines for a given architecture to standard output, use ``help'' as \fImachine\fR and the given architecture using \fB\-a \fIarch\fR\fR\&. See \fByasm_arch\fR(7) for more details\&.

.SH "WARNING OPTIONS"

.PP
\fB\-W\fR options have two contrary forms: \fB\-W\fIname\fR\fR and \fB\-Wno\-\fIname\fR\fR\&. Only the non\-default forms are shown here\&.

.TP
\fB\-w\fR
Inhibits all warning messages\&.

.TP
\fB\-Werror\fR
Treats warnings as errors\&.

.TP
\fB\-Wno\-unrecognized\-char\fR
Causes \fByasm\fR to not warn on unrecognized characters found in the input\&.

.TP
\fB\-Worphan\-labels\fR
Causes \fByasm\fR to warn about labels found alone on a line without a trailing colon\&. While these are legal labels in the ``nasm'' parser, they may be unintentional, due to typos or macro definition ordering\&.

.TP
\fB\-X \fIstyle\fR\fR
Selects a specific output style of error and warning messages\&. The default is ``gnu'' style, which mimics the output of \fBgcc\fR\&. The ``vc'' style is also available, which mimics the output of Microsoft's Visual C++ compiler\&.

.SH "PREPROCESSOR OPTIONS"

.TP
\fB\-e\fR or \fB\-\-preproc\-only\fR
Stops assembly after the preprocessing stage; preprocessed output is sent to the specified output name or, if no output name is specified, the standard output\&. No object file is produced\&.

.TP
\fB\-I \fIpath\fR\fR
Adds directory \fIpath\fR to the search path for include files\&.

.TP
\fB\-P \fIfilename\fR\fR
Pre\-includes file \fIfilename\fR, making it look as though \fIfilename\fR was prepended to the input\&.

.TP
\fB\-D \fImacro[=value]\fR\fR
Pre\-defines a single\-line macro\&.

.TP
\fB\-U \fImacro\fR\fR
Undefines a single\-line macro\&.

.SH "EXAMPLES"

.PP
To assemble NASM syntax, 32\-bit x86 source \fIsource\&.asm\fR into ELF file \fIsource\&.o\fR, warning on orphan labels: 

.IP
yasm \-f elf \-Worphan\-labels source\&.asm

.PP
To assemble NASM syntax AMD64 source \fIx\&.asm\fR into AMD64 Win32 file \fIobject\&.obj\fR: 

.IP
yasm \-m amd64 \-f win32 \-o object\&.obj x\&.asm

.PP
To assemble already preprocessed NASM syntax 32\-bit x86 source \fIy\&.asm\fR into flat binary file \fIy\&.com\fR: 

.IP
yasm \-f bin \-r raw \-o y\&.com y\&.asm

.SH "DIAGNOSTICS"

.PP
The \fByasm\fR command exits 0 on success, and nonzero if an error occurs\&.

.SH "COMPATIBILITY"

.PP
YASM's NASM parser and preprocessor, while they strive to be as compatible as possible with NASM, have a few incompatibilities due to YASM's different internal structure\&.

.SH "RESTRICTIONS"

.PP
As object files are often architecture and machine dependent, not all combinations of object formats, architectures, and machines are legal; trying to use an invalid combination will result in an error\&.

.PP
There is no support for list files or symbol maps\&.

.PP
Relocatable object formats are limited to static linking applications, as YASM cannot generate relocations for dynamic linking\&.

.SH "SEE ALSO"

.PP
\fBas\fR(1), \fBld\fR(1), \fBnasm\fR(1), \fByasm_arch\fR(7)

.SH "BUGS"

.PP
When using the ``x86'' architecture, it is overly easy to generate AMD64 code (using the \fBBITS 64\fR directive) and generate a 32\-bit object file (by failing to specify \fB\-m amd64\fR on the command line)\&. Similarly, specifying \fB\-m amd64\fR does not default the BITS setting to 64\&.

.SH AUTHOR
Peter Johnson <peter@tortall\&.net>.