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 output,
45 use “help” as arch. See yasm_arch(7) for a list of supported
46 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 debug.
62 See yasm_dbgfmts(7) for a list of supported debugging formats.
63 -h or --help: Print a summary of options
65 Prints a summary of invocation options. All other options are
66 ignored, and no output file is generated.
67 -L list or --lformat=list: Select list file format
69 Selects the format/style of the output list file. List files
70 typically intermix the original source with the machine code
71 generated by the assembler. The default list format is “nasm”, which
72 mimics the NASM list file format. To print a list of available list
73 file formats to standard output, use “help” as list.
74 -l listfile or --list=listfile: Specify list filename
76 Specifies the name of the output list file. If this option is not
77 used, no list file is generated.
78 -m machine or --machine=machine: Select target machine architecture
80 Selects the target machine architecture. Essentially a subtype of
81 the selected architecture, the machine type selects between major
82 subsets of an architecture. For example, for the “x86” architecture,
83 the two available machines are “x86”, which is used for the IA-32
84 and derivative 32-bit instruction set, and “amd64”, which is used
85 for the 64-bit instruction set. This differentiation is required to
86 generate the proper object file for relocatable object formats such
87 as COFF and ELF. To print a list of available machines for a given
88 architecture to standard output, use “help” as machine and the given
89 architecture using -a arch. See yasm_arch(7) for more details.
90 -o filename or --objfile=filename: Specify object filename
92 Specifies the name of the output file, overriding any default name
93 generated by Yasm.
94 -p parser or --parser=parser: Select parser
96 Selects the parser (the assembler syntax). The default parser is
97 “nasm”, which emulates the syntax of NASM, the Netwide Assembler.
98 Another available parser is “gas”, which emulates the syntax of GNU
99 AS. To print a list of available parsers to standard output, use
100 “help” as parser. See yasm_parsers(7) for a list of supported
101 parsers.
102 -r preproc or --preproc=preproc: Select preprocessor
104 Selects the preprocessor to use on the input file before passing it
105 to the parser. Preprocessors often provide macro functionality that
106 is not included in the main parser. The default preprocessor is
107 “nasm”, which is an imported version of the actual NASM
108 preprocessor. A “raw” preprocessor is also available, which simply
109 skips the preprocessing step, passing the input file directly to the
110 parser. To print a list of available preprocessors to standard
111 output, use “help” as preproc.
112 --version: Get the Yasm version
114 This option causes Yasm to prints the version number of Yasm as well
115 as a license summary to standard output. All other options are
116 ignored, and no output file is generated.
117 Warning Options
119 -W options have two contrary forms: -Wname and -Wno-name. Only the
120 non-default forms are shown here.
121 The warning options are handled in the order given on the command line,
123 so if -w is followed by -Worphan-labels, all warnings are turned off
124 except for orphan-labels.
125 -w: Inhibit all warning messages
127 This option causes Yasm to inhibit all warning messages. As
128 discussed above, this option may be followed by other options to
129 re-enable specified warnings.
130 -Werror: Treat warnings as errors
132 This option causes Yasm to treat all warnings as errors. Normally
133 warnings do not prevent an object file from being generated and do
134 not result in a failure exit status from yasm, whereas errors do.
135 This option makes warnings equivalent to errors in terms of this
136 behavior.
137 -Wno-unrecognized-char: Do not warn on unrecognized input characters
139 Causes Yasm to not warn on unrecognized characters found in the
140 input. Normally Yasm will generate a warning for any non-ASCII
141 character found in the input file.
142 -Worphan-labels: Warn on labels lacking a trailing option
144 When using the NASM-compatible parser, causes Yasm to warn about
145 labels found alone on a line without a trailing colon. While these
146 are legal labels in NASM syntax, they may be unintentional, due to
147 typos or macro definition ordering.
148 -X style: Change error/warning reporting style
150 Selects a specific output style for error and warning messages. The
151 default is “gnu” style, which mimics the output of gcc. The “vc”
152 style is also available, which mimics the output of Microsoft's
153 Visual C++ compiler.
154 This option is available so that Yasm integrates more naturally into
156 IDE environments such as Visual Studio or Emacs, allowing the IDE to
157 correctly recognize the error/warning message as such and link back
158 to the offending line of source code.
159 Preprocessor Options
161 While these preprocessor options theoretically will affect any
162 preprocessor, the only preprocessor currently in Yasm is the “nasm”
163 preprocessor.
164 -D macro[=value]: Pre-define a macro
166 Pre-defines a single-line macro. The value is optional (if no value
167 is given, the macro is still defined, but to an empty value).
168 -e or --preproc-only: Only preprocess
170 Stops assembly after the preprocessing stage; preprocessed output is
171 sent to the specified output name or, if no output name is
172 specified, the standard output. No object file is produced.
173 -I path: Add include file path
175 Adds directory path to the search path for include files. The search
176 path defaults to only including the directory in which the source
177 file resides.
178 -P filename: Pre-include a file
180 Pre-includes file filename, making it look as though filename was
181 prepended to the input. Can be useful for prepending multi-line
182 macros that the -D can't support.
183 -U macro: Undefine a macro
185 Undefines a single-line macro (may be either a built-in macro or one
186 defined earlier in the command line with -D.
187
189 To assemble NASM syntax, 32-bit x86 source source.asm into ELF file
190 source.o, warning on orphan labels:
191 yasm -f elf32 -Worphan-labels source.asm
193 To assemble NASM syntax AMD64 source x.asm into Win64 file object.obj:
195 yasm -f win64 -o object.obj x.asm
197 To assemble already preprocessed NASM syntax x86 source y.asm into flat
199 binary file y.com:
200 yasm -f bin -r raw -o y.com y.asm
202
204 The yasm command exits 0 on success, and nonzero if an error occurs.
205
207 Yasm's NASM parser and preprocessor, while they strive to be as
208 compatible as possible with NASM, have a few incompatibilities due to
209 YASM's different internal structure.
210 Yasm's GAS parser and preprocessor are missing a number of features
212 present in GNU AS.
213
215 As object files are often architecture and machine dependent, not all
216 combinations of object formats, architectures, and machines are legal;
217 trying to use an invalid combination will result in an error.
218 There is no support for symbol maps.
220
222 yasm_arch(7), yasm_dbgfmts(7), yasm_objfmts(7), yasm_parsers(7)
223 Related tools: as(1), ld(1), nasm(1)
225
227 When using the “x86” architecture, it is overly easy to generate AMD64
228 code (using the BITS 64 directive) and generate a 32-bit object file
229 (by failing to specify -m amd64 or selecting a 64-bit object format
230 such as ELF64 on the command line). Similarly, specifying -m amd64 does
231 not default the BITS setting to 64. An easy way to avoid this is by
232 directly specifying a 64-bit object format such as -f elf64.
233
235 Peter Johnson <peter@tortall.net>
236 Author.
237
239 Copyright © 2004, 2005, 2006 Peter Johnson
240Yasm October 2006 YASM(1)