1YASM(1)                   The Yasm Modular Assembler                   YASM(1)
2
3
4

NAME

6       yasm - The Yasm Modular Assembler
7

SYNOPSIS

9       yasm [-f format] [-o outfile] [other options...] {infile}
10
11       yasm -h
12

DESCRIPTION

14       The Yasm Modular Assembler is a portable, retargetable assembler
15       written under the “new” (2 or 3 clause) BSD license. Yasm currently
16       supports the x86 and AMD64 instruction sets, accepts NASM and GAS
17       assembler syntaxes, outputs binary, ELF32, ELF64, COFF, Win32, and
18       Win64 object formats, and generates source debugging information in
19       STABS, DWARF 2, and CodeView 8 formats.
20
21       YASM consists of the yasm command, libyasm, the core backend library,
22       and a large number of modules. Currently, libyasm and the loadable
23       modules are statically built into the yasm executable.
24
25       The yasm command assembles the file infile and directs output to the
26       file outfile if specified. If outfile is not specified, yasm will
27       derive a default output file name from the name of its input file,
28       usually by appending .o or .obj, or by removing all extensions for a
29       raw binary file. Failing that, the output file name will be yasm.out.
30
31       If called with an infile of “-”, yasm assembles the standard input and
32       directs output to the file outfile, or yasm.out if no outfile is
33       specified.
34

OPTIONS

36       Many options may be given in one of two forms: either a dash followed
37       by a single letter, or two dashes followed by a long option name.
38       Options are listed in alphabetical order.
39
40   General Options
41       -a arch or --arch=arch: Select target architecture
42           Selects the target architecture. The default architecture is “x86”,
43           which supports both the IA-32 and derivatives and AMD64 instruction
44           sets. To print a list of available architectures to standard
45           output, use “help” as arch. See yasm_arch(7) for a list of
46           supported architectures.
47
48       -f format or --oformat=format: Select object format
49           Selects the output object format. The default object format is
50           “bin”, which is a flat format binary with no relocation. To print a
51           list of available object formats to standard output, use “help” as
52           format. See yasm_objfmts(7) for a list of supported object formats.
53
54       -g debug or --dformat=debug: Select debugging format
55           Selects the debugging format for debug information. Debugging
56           information can be used by a debugger to associate executable code
57           back to the source file or get data structure and type information.
58           Available debug formats vary between different object formats; yasm
59           will error when an invalid combination is selected. The default
60           object format is selected by the object format. To print a list of
61           available debugging formats to standard output, use “help” as
62           debug. See yasm_dbgfmts(7) for a list of supported debugging
63           formats.
64
65       -h or --help: Print a summary of options
66           Prints a summary of invocation options. All other options are
67           ignored, and no output file is generated.
68
69       -L list or --lformat=list: Select list file format
70           Selects the format/style of the output list file. List files
71           typically intermix the original source with the machine code
72           generated by the assembler. The default list format is “nasm”,
73           which mimics the NASM list file format. To print a list of
74           available list file formats to standard output, use “help” as list.
75
76       -l listfile or --list=listfile: Specify list filename
77           Specifies the name of the output list file. If this option is not
78           used, no list file is generated.
79
80       -m machine or --machine=machine: Select target machine architecture
81           Selects the target machine architecture. Essentially a subtype of
82           the selected architecture, the machine type selects between major
83           subsets of an architecture. For example, for the “x86”
84           architecture, the two available machines are “x86”, which is used
85           for the IA-32 and derivative 32-bit instruction set, and “amd64”,
86           which is used for the 64-bit instruction set. This differentiation
87           is required to generate the proper object file for relocatable
88           object formats such as COFF and ELF. To print a list of available
89           machines for a given architecture to standard output, use “help” as
90           machine and the given architecture using -a arch. See yasm_arch(7)
91           for more details.
92
93       -o filename or --objfile=filename: Specify object filename
94           Specifies the name of the output file, overriding any default name
95           generated by Yasm.
96
97       -p parser or --parser=parser: Select parser
98           Selects the parser (the assembler syntax). The default parser is
99           “nasm”, which emulates the syntax of NASM, the Netwide Assembler.
100           Another available parser is “gas”, which emulates the syntax of GNU
101           AS. To print a list of available parsers to standard output, use
102           “help” as parser. See yasm_parsers(7) for a list of supported
103           parsers.
104
105       -r preproc or --preproc=preproc: Select preprocessor
106           Selects the preprocessor to use on the input file before passing it
107           to the parser. Preprocessors often provide macro functionality that
108           is not included in the main parser. The default preprocessor is
109           “nasm”, which is an imported version of the actual NASM
110           preprocessor. A “raw” preprocessor is also available, which simply
111           skips the preprocessing step, passing the input file directly to
112           the parser. To print a list of available preprocessors to standard
113           output, use “help” as preproc.
114
115       --version: Get the Yasm version
116           This option causes Yasm to prints the version number of Yasm as
117           well as a license summary to standard output. All other options are
118           ignored, and no output file is generated.
119
120   Warning Options
121       -W options have two contrary forms: -Wname and -Wno-name. Only the
122       non-default forms are shown here.
123
124       The warning options are handled in the order given on the command line,
125       so if -w is followed by -Worphan-labels, all warnings are turned off
126       except for orphan-labels.
127
128       -w: Inhibit all warning messages
129           This option causes Yasm to inhibit all warning messages. As
130           discussed above, this option may be followed by other options to
131           re-enable specified warnings.
132
133       -Werror: Treat warnings as errors
134           This option causes Yasm to treat all warnings as errors. Normally
135           warnings do not prevent an object file from being generated and do
136           not result in a failure exit status from yasm, whereas errors do.
137           This option makes warnings equivalent to errors in terms of this
138           behavior.
139
140       -Wno-unrecognized-char: Do not warn on unrecognized input characters
141           Causes Yasm to not warn on unrecognized characters found in the
142           input. Normally Yasm will generate a warning for any non-ASCII
143           character found in the input file.
144
145       -Worphan-labels: Warn on labels lacking a trailing option
146           When using the NASM-compatible parser, causes Yasm to warn about
147           labels found alone on a line without a trailing colon. While these
148           are legal labels in NASM syntax, they may be unintentional, due to
149           typos or macro definition ordering.
150
151       -X style: Change error/warning reporting style
152           Selects a specific output style for error and warning messages. The
153           default is “gnu” style, which mimics the output of gcc. The “vc”
154           style is also available, which mimics the output of Microsoft's
155           Visual C++ compiler.
156
157           This option is available so that Yasm integrates more naturally
158           into IDE environments such as Visual Studio or Emacs, allowing the
159           IDE to correctly recognize the error/warning message as such and
160           link back to the offending line of source code.
161
162   Preprocessor Options
163       While these preprocessor options theoretically will affect any
164       preprocessor, the only preprocessor currently in Yasm is the “nasm”
165       preprocessor.
166
167       -D macro[=value]: Pre-define a macro
168           Pre-defines a single-line macro. The value is optional (if no value
169           is given, the macro is still defined, but to an empty value).
170
171       -e or --preproc-only: Only preprocess
172           Stops assembly after the preprocessing stage; preprocessed output
173           is sent to the specified output name or, if no output name is
174           specified, the standard output. No object file is produced.
175
176       -I path: Add include file path
177           Adds directory path to the search path for include files. The
178           search path defaults to only including the directory in which the
179           source file resides.
180
181       -P filename: Pre-include a file
182           Pre-includes file filename, making it look as though filename was
183           prepended to the input. Can be useful for prepending multi-line
184           macros that the -D can't support.
185
186       -U macro: Undefine a macro
187           Undefines a single-line macro (may be either a built-in macro or
188           one defined earlier in the command line with -D.
189

EXAMPLES

191       To assemble NASM syntax, 32-bit x86 source source.asm into ELF file
192       source.o, warning on orphan labels:
193
194           yasm -f elf32 -Worphan-labels source.asm
195
196       To assemble NASM syntax AMD64 source x.asm into Win64 file object.obj:
197
198           yasm -f win64 -o object.obj x.asm
199
200       To assemble already preprocessed NASM syntax x86 source y.asm into flat
201       binary file y.com:
202
203           yasm -f bin -r raw -o y.com y.asm
204

DIAGNOSTICS

206       The yasm command exits 0 on success, and nonzero if an error occurs.
207

COMPATIBILITY

209       Yasm's NASM parser and preprocessor, while they strive to be as
210       compatible as possible with NASM, have a few incompatibilities due to
211       YASM's different internal structure.
212
213       Yasm's GAS parser and preprocessor are missing a number of features
214       present in GNU AS.
215

RESTRICTIONS

217       As object files are often architecture and machine dependent, not all
218       combinations of object formats, architectures, and machines are legal;
219       trying to use an invalid combination will result in an error.
220
221       There is no support for symbol maps.
222

SEE ALSO

224       yasm_arch(7), yasm_dbgfmts(7), yasm_objfmts(7), yasm_parsers(7)
225
226       Related tools: as(1), ld(1), nasm(1)
227

BUGS

229       When using the “x86” architecture, it is overly easy to generate AMD64
230       code (using the BITS 64 directive) and generate a 32-bit object file
231       (by failing to specify -m amd64 or selecting a 64-bit object format
232       such as ELF64 on the command line).
233

AUTHOR

235       Peter Johnson <peter@tortall.net>
236           Author.
237
239       Copyright © 2004, 2005, 2006, 2007 Peter Johnson
240
241
242
243
244Yasm                              April 2007                           YASM(1)
Impressum