mirror of https://github.com/yasm/yasm.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
202 lines
8.8 KiB
202 lines
8.8 KiB
.\"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>.
|
|
|