| <?xml version="1.0"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> |
| |
| <!-- $Id: yasm.xml,v 1.1.1.1 2012/03/29 17:21:05 uid42307 Exp $ --> |
| |
| <refentry id="yasm"> |
| |
| <refentryinfo> |
| <title>The Yasm Modular Assembler</title> |
| <date>April 2007</date> |
| <productname>Yasm</productname> |
| <author> |
| <firstname>Peter</firstname> |
| <surname>Johnson</surname> |
| <affiliation> |
| <address><email>peter@tortall.net</email></address> |
| </affiliation> |
| </author> |
| |
| <copyright> |
| <year>2004</year> |
| <year>2005</year> |
| <year>2006</year> |
| <year>2007</year> |
| <holder>Peter Johnson</holder> |
| </copyright> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>yasm</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>yasm</refname> |
| <refpurpose>The Yasm Modular Assembler</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>yasm</command> |
| <arg choice="opt"> |
| <option>-f <replaceable>format</replaceable></option> |
| </arg> |
| <arg choice="opt"> |
| <option>-o <replaceable>outfile</replaceable></option> |
| </arg> |
| <arg choice="opt" rep="repeat"> |
| <option><replaceable>other options</replaceable></option> |
| </arg> |
| <arg choice="req"><replaceable>infile</replaceable></arg> |
| </cmdsynopsis> |
| |
| <cmdsynopsis> |
| <command>yasm</command> |
| <arg choice="plain"> |
| <option>-h</option> |
| </arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>The Yasm Modular Assembler is a portable, retargetable |
| assembler written under the <quote>new</quote> (2 or 3 clause) BSD |
| license. Yasm currently supports the x86 and AMD64 instruction |
| sets, accepts NASM and GAS assembler syntaxes, outputs binary, |
| ELF32, ELF64, COFF, Win32, and Win64 object formats, and generates |
| source debugging information in STABS, DWARF 2, and CodeView 8 |
| formats.</para> |
| |
| <para>YASM consists of the <command>yasm</command> command, libyasm, |
| the core backend library, and a large number of modules. |
| Currently, libyasm and the loadable modules are statically built |
| into the <command>yasm</command> executable.</para> |
| |
| <para>The <command>yasm</command> command assembles the file infile |
| and directs output to the file <replaceable>outfile</replaceable> |
| if specified. If <replaceable>outfile</replaceable> is not |
| specified, <command>yasm</command> will derive a default output |
| file name from the name of its input file, usually by appending |
| <filename>.o</filename> or <filename>.obj</filename>, or by |
| removing all extensions for a raw binary file. Failing that, the |
| output file name will be <filename>yasm.out</filename>.</para> |
| |
| <para>If called with an <replaceable>infile</replaceable> of |
| <quote>-</quote>, <command>yasm</command> assembles the standard |
| input and directs output to the file |
| <replaceable>outfile</replaceable>, or |
| <filename>yasm.out</filename> if no |
| <replaceable>outfile</replaceable> is specified.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>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. Options are listed in alphabetical order.</para> |
| |
| <refsect2> |
| <title>General Options</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>-a <replaceable>arch</replaceable></option> or |
| <option>--arch=<replaceable>arch</replaceable></option>: Select |
| target architecture</term> |
| |
| <listitem> |
| <para>Selects the target architecture. The default architecture |
| is <quote>x86</quote>, which supports both the IA-32 and |
| derivatives and AMD64 instruction sets. To print a list of |
| available architectures to standard output, use |
| <quote>help</quote> as <replaceable>arch</replaceable>. See |
| |
| <citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| |
| for a list of supported architectures.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-f <replaceable>format</replaceable></option> or |
| <option>--oformat=<replaceable>format</replaceable></option>: |
| Select object format</term> |
| |
| <listitem> |
| <para>Selects the output object format. The default object |
| format is <quote>bin</quote>, which is a flat format binary |
| with no relocation. To print a list of available object |
| formats to standard output, use <quote>help</quote> as |
| <replaceable>format</replaceable>. See |
| |
| <citerefentry> |
| <refentrytitle>yasm_objfmts</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| |
| for a list of supported object formats.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-g <replaceable>debug</replaceable></option> or |
| <option>--dformat=<replaceable>debug</replaceable></option>: |
| Select debugging format</term> |
| |
| <listitem> |
| <para>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; <command>yasm</command> 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 |
| <quote>help</quote> as <replaceable>debug</replaceable>. See |
| |
| <citerefentry> |
| <refentrytitle>yasm_dbgfmts</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| |
| for a list of supported debugging formats.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-h</option> or <option>--help</option>: Print a |
| summary of options</term> |
| |
| <listitem> |
| <para>Prints a summary of invocation options. All other options |
| are ignored, and no output file is generated.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-L <replaceable>list</replaceable></option> or |
| <option>--lformat=<replaceable>list</replaceable></option>: |
| Select list file format</term> |
| |
| <listitem> |
| <para>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 |
| <quote>nasm</quote>, which mimics the NASM list file format. |
| To print a list of available list file formats to standard |
| output, use <quote>help</quote> as |
| <replaceable>list</replaceable>.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-l <replaceable>listfile</replaceable></option> or |
| <option>--list=<replaceable>listfile</replaceable></option>: |
| Specify list filename</term> |
| |
| <listitem> |
| <para>Specifies the name of the output list file. If this |
| option is not used, no list file is generated.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-m <replaceable>machine</replaceable></option> or |
| <option>--machine=<replaceable>machine</replaceable></option>: |
| Select target machine architecture</term> |
| |
| <listitem> |
| <para>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 |
| <quote>x86</quote> architecture, the two available machines are |
| <quote>x86</quote>, which is used for the IA-32 and derivative |
| 32-bit instruction set, and <quote>amd64</quote>, 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 <quote>help</quote> as <replaceable>machine</replaceable> |
| and the given architecture using <option>-a |
| <replaceable>arch</replaceable></option>. See |
| |
| <citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| |
| for more details.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-o <replaceable>filename</replaceable></option> or |
| <option>--objfile=<replaceable>filename</replaceable></option>: |
| Specify object filename</term> |
| |
| <listitem> |
| <para>Specifies the name of the output file, overriding any |
| default name generated by Yasm.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-p <replaceable>parser</replaceable></option> or |
| <option>--parser=<replaceable>parser</replaceable></option>: |
| Select parser</term> |
| |
| <listitem> |
| <para>Selects the parser (the assembler syntax). The default |
| parser is <quote>nasm</quote>, which emulates the syntax of |
| NASM, the Netwide Assembler. Another available parser is |
| <quote>gas</quote>, which emulates the syntax of GNU AS. To |
| print a list of available parsers to standard output, use |
| <quote>help</quote> as <replaceable>parser</replaceable>. See |
| |
| <citerefentry> |
| <refentrytitle>yasm_parsers</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| |
| for a list of supported parsers.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-r <replaceable>preproc</replaceable></option> or |
| <option>--preproc=<replaceable>preproc</replaceable></option>: |
| Select preprocessor</term> |
| |
| <listitem> |
| <para>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 <quote>nasm</quote>, which is an |
| imported version of the actual NASM preprocessor. A |
| <quote>raw</quote> 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 <quote>help</quote> as |
| <replaceable>preproc</replaceable>.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--version</option>: Get the Yasm version</term> |
| |
| <listitem> |
| <para>This option causes Yasm to prints the version number of |
| Yasm as well as a license summary to standard output. All |
| other options are ignored, and no output file is |
| generated.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect2> |
| |
| <refsect2> |
| <title>Warning Options</title> |
| |
| <para><option>-W</option> options have two contrary forms: |
| <option>-W<replaceable>name</replaceable></option> and |
| <option>-Wno-<replaceable>name</replaceable></option>. Only the |
| non-default forms are shown here.</para> |
| |
| <para>The warning options are handled in the order given on the |
| command line, so if <option>-w</option> is followed by |
| <option>-Worphan-labels</option>, all warnings are turned off |
| <emphasis>except</emphasis> for orphan-labels.</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>-w</option>: Inhibit all warning messages</term> |
| |
| <listitem> |
| <para>This option causes Yasm to inhibit all warning messages. |
| As discussed above, this option may be followed by other |
| options to re-enable specified warnings.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-Werror</option>: Treat warnings as errors</term> |
| |
| <listitem> |
| <para>This option causes Yasm to treat all warnings as errors. |
| Normally warnings do not prevent an object file from being |
| generated and do not result in a failure exit status from |
| <command>yasm</command>, whereas errors do. This option makes |
| warnings equivalent to errors in terms of this behavior.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-Wno-unrecognized-char</option>: Do not warn on |
| unrecognized input characters</term> |
| |
| <listitem> |
| <para>Causes Yasm to not warn on unrecognized characters found |
| in the input. Normally Yasm will generate a warning for any |
| non-ASCII character found in the input file.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-Worphan-labels</option>: Warn on labels lacking a |
| trailing option</term> |
| |
| <listitem> |
| <para>When using the NASM-compatible parser, causes Yasm to warn |
| about labels found alone on a line without a trailing colon. |
| While these are legal labels in NASM syntax, they may be |
| unintentional, due to typos or macro definition |
| ordering.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-X <replaceable>style</replaceable></option>: |
| Change error/warning reporting style</term> |
| |
| <listitem> |
| <para>Selects a specific output style for error and warning |
| messages. The default is <quote>gnu</quote> style, which |
| mimics the output of <command>gcc</command>. The |
| <quote>vc</quote> style is also available, which mimics the |
| output of Microsoft's Visual C++ compiler.</para> |
| |
| <para>This option is available so that Yasm integrates more |
| naturally into IDE environments such as <application |
| class="software">Visual Studio</application> or <application |
| class="software">Emacs</application>, allowing the IDE to |
| correctly recognize the error/warning message as such and link |
| back to the offending line of source code.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect2> |
| |
| <refsect2> |
| <title>Preprocessor Options</title> |
| |
| <para>While these preprocessor options theoretically will affect |
| any preprocessor, the only preprocessor currently in Yasm is the |
| <quote>nasm</quote> preprocessor.</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>-D |
| <replaceable>macro[=value]</replaceable></option>: Pre-define a |
| macro</term> |
| |
| <listitem> |
| <para>Pre-defines a single-line macro. The value is optional |
| (if no value is given, the macro is still defined, but to an |
| empty value).</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-e</option> or <option>--preproc-only</option>: |
| Only preprocess</term> |
| |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-I <replaceable>path</replaceable></option>: Add |
| include file path</term> |
| |
| <listitem> |
| <para>Adds directory <replaceable>path</replaceable> to the |
| search path for include files. The search path defaults to |
| only including the directory in which the source file |
| resides.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-P <replaceable>filename</replaceable></option>: |
| Pre-include a file</term> |
| |
| <listitem> |
| <para>Pre-includes file <replaceable>filename</replaceable>, |
| making it look as though <replaceable>filename</replaceable> |
| was prepended to the input. Can be useful for prepending |
| multi-line macros that the <option>-D</option> can't |
| support.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-U <replaceable>macro</replaceable></option>: |
| Undefine a macro</term> |
| |
| <listitem> |
| <para>Undefines a single-line macro (may be either a built-in |
| macro or one defined earlier in the command line with |
| <option>-D</option>.</para> |
| |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| |
| <para>To assemble NASM syntax, 32-bit x86 source |
| <filename>source.asm</filename> into ELF file |
| <filename>source.o</filename>, warning on orphan labels: |
| |
| <screen>yasm -f elf32 -Worphan-labels source.asm</screen></para> |
| |
| <para>To assemble NASM syntax AMD64 source |
| <filename>x.asm</filename> into Win64 file |
| <filename>object.obj</filename>: |
| |
| <screen>yasm -f win64 -o object.obj x.asm</screen></para> |
| |
| <para>To assemble already preprocessed NASM syntax x86 source |
| <filename>y.asm</filename> into flat binary file |
| <filename>y.com</filename>: |
| |
| <screen>yasm -f bin -r raw -o y.com y.asm</screen></para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Diagnostics</title> |
| |
| <para>The <command>yasm</command> command exits 0 on success, and |
| nonzero if an error occurs.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Compatibility</title> |
| |
| <para>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.</para> |
| |
| <para>Yasm's GAS parser and preprocessor are missing a number of |
| features present in GNU AS.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Restrictions</title> |
| |
| <para>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.</para> |
| |
| <para>There is no support for symbol maps.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <para><citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>yasm_dbgfmts</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>yasm_objfmts</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>yasm_parsers</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry></para> |
| |
| <para>Related tools: |
| <citerefentry> |
| <refentrytitle>as</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>ld</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>nasm</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry></para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Bugs</title> |
| |
| <para>When using the <quote>x86</quote> architecture, it is overly |
| easy to generate AMD64 code (using the <userinput>BITS |
| 64</userinput> directive) and generate a 32-bit object file (by |
| failing to specify <option>-m amd64</option> or selecting a 64-bit |
| object format such as ELF64 on the command line).</para> |
| </refsect1> |
| </refentry> |
