1YASM(1) The Yasm Modular Assembler YASM(1)
2
6 yasm - The Yasm Modular Assembler
7
9 yasm [-f format] [-o outfile] [other options...] {infile}
10 yasm -h
12
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 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 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 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
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 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 -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 -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 -L list or --lformat=list: Select list file format
66 Selects the format/style of the output list file. List files
67 typically intermix the original source with the machine code
68 generated by the assembler. The default list format is “nasm”,
69 which mimics the NASM list file format. To print a list of
70 available list file formats to standard output, use “help” as list.
71 -l listfile or --list=listfile: Specify list filename
73 Specifies the name of the output list file. If this option is not
74 used, no list file is generated.
75 -m machine or --machine=machine: Select target machine architecture
77 Selects the target machine architecture. Essentially a subtype of
78 the selected architecture, the machine type selects between major
79 subsets of an architecture. For example, for the “x86”
80 architecture, the two available machines are “x86”, which is used
81 for the IA-32 and derivative 32-bit instruction set, and “amd64”,
82 which is used for the 64-bit instruction set. This differentiation
83 is required to generate the proper object file for relocatable
84 object formats such as COFF and ELF. To print a list of available
85 machines for a given architecture to standard output, use “help” as
86 machine and the given architecture using -a arch. See yasm_arch(7)
87 for more details.
88 -o filename or --objfile=filename: Specify object filename
90 Specifies the name of the output file, overriding any default name
91 generated by Yasm.
92 -p parser or --parser=parser: Select parser
94 Selects the parser (the assembler syntax). The default parser is
95 “nasm”, which emulates the syntax of NASM, the Netwide Assembler.
96 Another available parser is “gas”, which emulates the syntax of GNU
97 AS. To print a list of available parsers to standard output, use
98 “help” as parser. See yasm_parsers(7) for a list of supported
99 parsers.
100 -r preproc or --preproc=preproc: Select preprocessor
102 Selects the preprocessor to use on the input file before passing it
103 to the parser. Preprocessors often provide macro functionality that
104 is not included in the main parser. The default preprocessor is
105 “nasm”, which is an imported version of the actual NASM
106 preprocessor. A “raw” preprocessor is also available, which simply
107 skips the preprocessing step, passing the input file directly to
108 the parser. To print a list of available preprocessors to standard
109 output, use “help” as preproc.
110 -h or --help: Print a summary of options
112 Prints a summary of invocation options. All other options are
113 ignored, and no output file is generated.
114 --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 Warning Options
121 -W options have two contrary forms: -Wname and -Wno-name. Only the
122 non-default forms are shown here.
123 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 -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 -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 -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 -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 -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 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 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 -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 -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 -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 -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 -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
191 To assemble NASM syntax, 32-bit x86 source source.asm into ELF file
192 source.o, warning on orphan labels:
193 yasm -f elf32 -Worphan-labels source.asm
195 To assemble NASM syntax AMD64 source x.asm into Win64 file object.obj:
197 yasm -f win64 -o object.obj x.asm
199 To assemble already preprocessed NASM syntax x86 source y.asm into flat
201 binary file y.com:
202 yasm -f bin -r raw -o y.com y.asm
204
206 The yasm command exits 0 on success, and nonzero if an error occurs.
207
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 Yasm´s GAS parser and preprocessor are missing a number of features
214 present in GNU AS.
215
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 There is no support for symbol maps.
222
224 yasm_arch(7), yasm_dbgfmts(7), yasm_objfmts(7), yasm_parsers(7)
225 Related tools: as(1), ld(1), nasm(1)
227
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
235 Peter Johnson <peter@tortall.net>
236 Author.
237
239 Copyright © 2004, 2005, 2006, 2007 Peter Johnson
240Yasm April 2007 YASM(1)