1<?xml version="1.0"?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 4 5<refentry id="yasm"> 6 7 <refentryinfo> 8 <title>The Yasm Modular Assembler</title> 9 <date>April 2007</date> 10 <productname>Yasm</productname> 11 <author> 12 <firstname>Peter</firstname> 13 <surname>Johnson</surname> 14 <affiliation> 15 <address><email>peter@tortall.net</email></address> 16 </affiliation> 17 </author> 18 19 <copyright> 20 <year>2004</year> 21 <year>2005</year> 22 <year>2006</year> 23 <year>2007</year> 24 <holder>Peter Johnson</holder> 25 </copyright> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle>yasm</refentrytitle> 30 <manvolnum>1</manvolnum> 31 </refmeta> 32 33 <refnamediv> 34 <refname>yasm</refname> 35 <refpurpose>The Yasm Modular Assembler</refpurpose> 36 </refnamediv> 37 38 <refsynopsisdiv> 39 <cmdsynopsis> 40 <command>yasm</command> 41 <arg choice="opt"> 42 <option>-f <replaceable>format</replaceable></option> 43 </arg> 44 <arg choice="opt"> 45 <option>-o <replaceable>outfile</replaceable></option> 46 </arg> 47 <arg choice="opt" rep="repeat"> 48 <option><replaceable>other options</replaceable></option> 49 </arg> 50 <arg choice="req"><replaceable>infile</replaceable></arg> 51 </cmdsynopsis> 52 53 <cmdsynopsis> 54 <command>yasm</command> 55 <arg choice="plain"> 56 <option>-h</option> 57 </arg> 58 </cmdsynopsis> 59 </refsynopsisdiv> 60 61 <refsect1> 62 <title>Description</title> 63 64 <para>The Yasm Modular Assembler is a portable, retargetable 65 assembler written under the <quote>new</quote> (2 or 3 clause) BSD 66 license. Yasm currently supports the x86 and AMD64 instruction 67 sets, accepts NASM and GAS assembler syntaxes, outputs binary, 68 ELF32, ELF64, COFF, Win32, and Win64 object formats, and generates 69 source debugging information in STABS, DWARF 2, and CodeView 8 70 formats.</para> 71 72 <para>YASM consists of the <command>yasm</command> command, libyasm, 73 the core backend library, and a large number of modules. 74 Currently, libyasm and the loadable modules are statically built 75 into the <command>yasm</command> executable.</para> 76 77 <para>The <command>yasm</command> command assembles the file infile 78 and directs output to the file <replaceable>outfile</replaceable> 79 if specified. If <replaceable>outfile</replaceable> is not 80 specified, <command>yasm</command> will derive a default output 81 file name from the name of its input file, usually by appending 82 <filename>.o</filename> or <filename>.obj</filename>, or by 83 removing all extensions for a raw binary file. Failing that, the 84 output file name will be <filename>yasm.out</filename>.</para> 85 86 <para>If called with an <replaceable>infile</replaceable> of 87 <quote>-</quote>, <command>yasm</command> assembles the standard 88 input and directs output to the file 89 <replaceable>outfile</replaceable>, or 90 <filename>yasm.out</filename> if no 91 <replaceable>outfile</replaceable> is specified.</para> 92 </refsect1> 93 94 <refsect1> 95 <title>Options</title> 96 97 <para>Many options may be given in one of two forms: either a dash 98 followed by a single letter, or two dashes followed by a long 99 option name. Options are listed in alphabetical order.</para> 100 101 <refsect2> 102 <title>General Options</title> 103 104 <variablelist> 105 <varlistentry> 106 <term><option>-a <replaceable>arch</replaceable></option> or 107 <option>--arch=<replaceable>arch</replaceable></option>: Select 108 target architecture</term> 109 110 <listitem> 111 <para>Selects the target architecture. The default architecture 112 is <quote>x86</quote>, which supports both the IA-32 and 113 derivatives and AMD64 instruction sets. To print a list of 114 available architectures to standard output, use 115 <quote>help</quote> as <replaceable>arch</replaceable>. See 116 117 <citerefentry> 118 <refentrytitle>yasm_arch</refentrytitle> 119 <manvolnum>7</manvolnum> 120 </citerefentry> 121 122 for a list of supported architectures.</para> 123 </listitem> 124 </varlistentry> 125 126 <varlistentry> 127 <term><option>-f <replaceable>format</replaceable></option> or 128 <option>--oformat=<replaceable>format</replaceable></option>: 129 Select object format</term> 130 131 <listitem> 132 <para>Selects the output object format. The default object 133 format is <quote>bin</quote>, which is a flat format binary 134 with no relocation. To print a list of available object 135 formats to standard output, use <quote>help</quote> as 136 <replaceable>format</replaceable>. See 137 138 <citerefentry> 139 <refentrytitle>yasm_objfmts</refentrytitle> 140 <manvolnum>7</manvolnum> 141 </citerefentry> 142 143 for a list of supported object formats.</para> 144 </listitem> 145 </varlistentry> 146 147 <varlistentry> 148 <term><option>-g <replaceable>debug</replaceable></option> or 149 <option>--dformat=<replaceable>debug</replaceable></option>: 150 Select debugging format</term> 151 152 <listitem> 153 <para>Selects the debugging format for debug information. 154 Debugging information can be used by a debugger to associate 155 executable code back to the source file or get data structure 156 and type information. Available debug formats vary between 157 different object formats; <command>yasm</command> will error 158 when an invalid combination is selected. The default object 159 format is selected by the object format. To print a list of 160 available debugging formats to standard output, use 161 <quote>help</quote> as <replaceable>debug</replaceable>. See 162 163 <citerefentry> 164 <refentrytitle>yasm_dbgfmts</refentrytitle> 165 <manvolnum>7</manvolnum> 166 </citerefentry> 167 168 for a list of supported debugging formats.</para> 169 </listitem> 170 </varlistentry> 171 172 <varlistentry> 173 <term><option>-L <replaceable>list</replaceable></option> or 174 <option>--lformat=<replaceable>list</replaceable></option>: 175 Select list file format</term> 176 177 <listitem> 178 <para>Selects the format/style of the output list file. List 179 files typically intermix the original source with the machine 180 code generated by the assembler. The default list format is 181 <quote>nasm</quote>, which mimics the NASM list file format. 182 To print a list of available list file formats to standard 183 output, use <quote>help</quote> as 184 <replaceable>list</replaceable>.</para> 185 </listitem> 186 </varlistentry> 187 188 <varlistentry> 189 <term><option>-l <replaceable>listfile</replaceable></option> or 190 <option>--list=<replaceable>listfile</replaceable></option>: 191 Specify list filename</term> 192 193 <listitem> 194 <para>Specifies the name of the output list file. If this 195 option is not used, no list file is generated.</para> 196 </listitem> 197 </varlistentry> 198 199 <varlistentry> 200 <term><option>-m <replaceable>machine</replaceable></option> or 201 <option>--machine=<replaceable>machine</replaceable></option>: 202 Select target machine architecture</term> 203 204 <listitem> 205 <para>Selects the target machine architecture. Essentially a 206 subtype of the selected architecture, the machine type selects 207 between major subsets of an architecture. For example, for the 208 <quote>x86</quote> architecture, the two available machines are 209 <quote>x86</quote>, which is used for the IA-32 and derivative 210 32-bit instruction set, and <quote>amd64</quote>, which is used 211 for the 64-bit instruction set. This differentiation is 212 required to generate the proper object file for relocatable 213 object formats such as COFF and ELF. To print a list of 214 available machines for a given architecture to standard output, 215 use <quote>help</quote> as <replaceable>machine</replaceable> 216 and the given architecture using <option>-a 217 <replaceable>arch</replaceable></option>. See 218 219 <citerefentry> 220 <refentrytitle>yasm_arch</refentrytitle> 221 <manvolnum>7</manvolnum> 222 </citerefentry> 223 224 for more details.</para> 225 </listitem> 226 </varlistentry> 227 228 <varlistentry> 229 <term><option>-o <replaceable>filename</replaceable></option> or 230 <option>--objfile=<replaceable>filename</replaceable></option>: 231 Specify object filename</term> 232 233 <listitem> 234 <para>Specifies the name of the output file, overriding any 235 default name generated by Yasm.</para> 236 </listitem> 237 </varlistentry> 238 239 <varlistentry> 240 <term><option>-p <replaceable>parser</replaceable></option> or 241 <option>--parser=<replaceable>parser</replaceable></option>: 242 Select parser</term> 243 244 <listitem> 245 <para>Selects the parser (the assembler syntax). The default 246 parser is <quote>nasm</quote>, which emulates the syntax of 247 NASM, the Netwide Assembler. Another available parser is 248 <quote>gas</quote>, which emulates the syntax of GNU AS. To 249 print a list of available parsers to standard output, use 250 <quote>help</quote> as <replaceable>parser</replaceable>. See 251 252 <citerefentry> 253 <refentrytitle>yasm_parsers</refentrytitle> 254 <manvolnum>7</manvolnum> 255 </citerefentry> 256 257 for a list of supported parsers.</para> 258 </listitem> 259 </varlistentry> 260 261 <varlistentry> 262 <term><option>-r <replaceable>preproc</replaceable></option> or 263 <option>--preproc=<replaceable>preproc</replaceable></option>: 264 Select preprocessor</term> 265 266 <listitem> 267 <para>Selects the preprocessor to use on the input file before 268 passing it to the parser. Preprocessors often provide macro 269 functionality that is not included in the main parser. The 270 default preprocessor is <quote>nasm</quote>, which is an 271 imported version of the actual NASM preprocessor. A 272 <quote>raw</quote> preprocessor is also available, which simply 273 skips the preprocessing step, passing the input file directly 274 to the parser. To print a list of available preprocessors to 275 standard output, use <quote>help</quote> as 276 <replaceable>preproc</replaceable>.</para> 277 </listitem> 278 </varlistentry> 279 280 <varlistentry> 281 <term><option>-h</option> or <option>--help</option>: Print a 282 summary of options</term> 283 284 <listitem> 285 <para>Prints a summary of invocation options. All other options 286 are ignored, and no output file is generated.</para> 287 </listitem> 288 </varlistentry> 289 290 <varlistentry> 291 <term><option>--version</option>: Get the Yasm version</term> 292 293 <listitem> 294 <para>This option causes Yasm to prints the version number of 295 Yasm as well as a license summary to standard output. All 296 other options are ignored, and no output file is 297 generated.</para> 298 </listitem> 299 </varlistentry> 300 </variablelist> 301 </refsect2> 302 303 <refsect2> 304 <title>Warning Options</title> 305 306 <para><option>-W</option> options have two contrary forms: 307 <option>-W<replaceable>name</replaceable></option> and 308 <option>-Wno-<replaceable>name</replaceable></option>. Only the 309 non-default forms are shown here.</para> 310 311 <para>The warning options are handled in the order given on the 312 command line, so if <option>-w</option> is followed by 313 <option>-Worphan-labels</option>, all warnings are turned off 314 <emphasis>except</emphasis> for orphan-labels.</para> 315 316 <variablelist> 317 <varlistentry> 318 <term><option>-w</option>: Inhibit all warning messages</term> 319 320 <listitem> 321 <para>This option causes Yasm to inhibit all warning messages. 322 As discussed above, this option may be followed by other 323 options to re-enable specified warnings.</para> 324 </listitem> 325 </varlistentry> 326 327 <varlistentry> 328 <term><option>-Werror</option>: Treat warnings as errors</term> 329 330 <listitem> 331 <para>This option causes Yasm to treat all warnings as errors. 332 Normally warnings do not prevent an object file from being 333 generated and do not result in a failure exit status from 334 <command>yasm</command>, whereas errors do. This option makes 335 warnings equivalent to errors in terms of this behavior.</para> 336 </listitem> 337 </varlistentry> 338 339 <varlistentry> 340 <term><option>-Wno-unrecognized-char</option>: Do not warn on 341 unrecognized input characters</term> 342 343 <listitem> 344 <para>Causes Yasm to not warn on unrecognized characters found 345 in the input. Normally Yasm will generate a warning for any 346 non-ASCII character found in the input file.</para> 347 </listitem> 348 </varlistentry> 349 350 <varlistentry> 351 <term><option>-Worphan-labels</option>: Warn on labels lacking a 352 trailing option</term> 353 354 <listitem> 355 <para>When using the NASM-compatible parser, causes Yasm to warn 356 about labels found alone on a line without a trailing colon. 357 While these are legal labels in NASM syntax, they may be 358 unintentional, due to typos or macro definition 359 ordering.</para> 360 </listitem> 361 </varlistentry> 362 363 <varlistentry> 364 <term><option>-X <replaceable>style</replaceable></option>: 365 Change error/warning reporting style</term> 366 367 <listitem> 368 <para>Selects a specific output style for error and warning 369 messages. The default is <quote>gnu</quote> style, which 370 mimics the output of <command>gcc</command>. The 371 <quote>vc</quote> style is also available, which mimics the 372 output of Microsoft's Visual C++ compiler.</para> 373 374 <para>This option is available so that Yasm integrates more 375 naturally into IDE environments such as <application 376 class="software">Visual Studio</application> or <application 377 class="software">Emacs</application>, allowing the IDE to 378 correctly recognize the error/warning message as such and link 379 back to the offending line of source code.</para> 380 </listitem> 381 </varlistentry> 382 </variablelist> 383 </refsect2> 384 385 <refsect2> 386 <title>Preprocessor Options</title> 387 388 <para>While these preprocessor options theoretically will affect 389 any preprocessor, the only preprocessor currently in Yasm is the 390 <quote>nasm</quote> preprocessor.</para> 391 392 <variablelist> 393 <varlistentry> 394 <term><option>-D 395 <replaceable>macro[=value]</replaceable></option>: Pre-define a 396 macro</term> 397 398 <listitem> 399 <para>Pre-defines a single-line macro. The value is optional 400 (if no value is given, the macro is still defined, but to an 401 empty value).</para> 402 </listitem> 403 </varlistentry> 404 405 <varlistentry> 406 <term><option>-e</option> or <option>--preproc-only</option>: 407 Only preprocess</term> 408 409 <listitem> 410 <para>Stops assembly after the preprocessing stage; preprocessed 411 output is sent to the specified output name or, if no output 412 name is specified, the standard output. No object file is 413 produced.</para> 414 </listitem> 415 </varlistentry> 416 417 <varlistentry> 418 <term><option>-I <replaceable>path</replaceable></option>: Add 419 include file path</term> 420 421 <listitem> 422 <para>Adds directory <replaceable>path</replaceable> to the 423 search path for include files. The search path defaults to 424 only including the directory in which the source file 425 resides.</para> 426 </listitem> 427 </varlistentry> 428 429 <varlistentry> 430 <term><option>-P <replaceable>filename</replaceable></option>: 431 Pre-include a file</term> 432 433 <listitem> 434 <para>Pre-includes file <replaceable>filename</replaceable>, 435 making it look as though <replaceable>filename</replaceable> 436 was prepended to the input. Can be useful for prepending 437 multi-line macros that the <option>-D</option> can't 438 support.</para> 439 </listitem> 440 </varlistentry> 441 442 <varlistentry> 443 <term><option>-U <replaceable>macro</replaceable></option>: 444 Undefine a macro</term> 445 446 <listitem> 447 <para>Undefines a single-line macro (may be either a built-in 448 macro or one defined earlier in the command line with 449 <option>-D</option>.</para> 450 451 </listitem> 452 </varlistentry> 453 </variablelist> 454 </refsect2> 455 </refsect1> 456 457 <refsect1> 458 <title>Examples</title> 459 460 <para>To assemble NASM syntax, 32-bit x86 source 461 <filename>source.asm</filename> into ELF file 462 <filename>source.o</filename>, warning on orphan labels: 463 464 <screen>yasm -f elf32 -Worphan-labels source.asm</screen></para> 465 466 <para>To assemble NASM syntax AMD64 source 467 <filename>x.asm</filename> into Win64 file 468 <filename>object.obj</filename>: 469 470 <screen>yasm -f win64 -o object.obj x.asm</screen></para> 471 472 <para>To assemble already preprocessed NASM syntax x86 source 473 <filename>y.asm</filename> into flat binary file 474 <filename>y.com</filename>: 475 476 <screen>yasm -f bin -r raw -o y.com y.asm</screen></para> 477 </refsect1> 478 479 <refsect1> 480 <title>Diagnostics</title> 481 482 <para>The <command>yasm</command> command exits 0 on success, and 483 nonzero if an error occurs.</para> 484 </refsect1> 485 486 <refsect1> 487 <title>Compatibility</title> 488 489 <para>Yasm's NASM parser and preprocessor, while they strive to be 490 as compatible as possible with NASM, have a few incompatibilities 491 due to YASM's different internal structure.</para> 492 493 <para>Yasm's GAS parser and preprocessor are missing a number of 494 features present in GNU AS.</para> 495 </refsect1> 496 497 <refsect1> 498 <title>Restrictions</title> 499 500 <para>As object files are often architecture and machine dependent, 501 not all combinations of object formats, architectures, and machines 502 are legal; trying to use an invalid combination will result in an 503 error.</para> 504 505 <para>There is no support for symbol maps.</para> 506 </refsect1> 507 508 <refsect1> 509 <title>See Also</title> 510 511 <para><citerefentry> 512 <refentrytitle>yasm_arch</refentrytitle> 513 <manvolnum>7</manvolnum> 514 </citerefentry>, 515 <citerefentry> 516 <refentrytitle>yasm_dbgfmts</refentrytitle> 517 <manvolnum>7</manvolnum> 518 </citerefentry>, 519 <citerefentry> 520 <refentrytitle>yasm_objfmts</refentrytitle> 521 <manvolnum>7</manvolnum> 522 </citerefentry>, 523 <citerefentry> 524 <refentrytitle>yasm_parsers</refentrytitle> 525 <manvolnum>7</manvolnum> 526 </citerefentry></para> 527 528 <para>Related tools: 529 <citerefentry> 530 <refentrytitle>as</refentrytitle> 531 <manvolnum>1</manvolnum> 532 </citerefentry>, 533 <citerefentry> 534 <refentrytitle>ld</refentrytitle> 535 <manvolnum>1</manvolnum> 536 </citerefentry>, 537 <citerefentry> 538 <refentrytitle>nasm</refentrytitle> 539 <manvolnum>1</manvolnum> 540 </citerefentry></para> 541 </refsect1> 542 543 <refsect1> 544 <title>Bugs</title> 545 546 <para>When using the <quote>x86</quote> architecture, it is overly 547 easy to generate AMD64 code (using the <userinput>BITS 548 64</userinput> directive) and generate a 32-bit object file (by 549 failing to specify <option>-m amd64</option> or selecting a 64-bit 550 object format such as ELF64 on the command line).</para> 551 </refsect1> 552</refentry> 553