// $Id: running.txt 2217 2009-07-24 17:47:49Z peter $
[[running]]
== Running Yasm

[[yasm-synopsis]]
=== **yasm** Synopsis

++++
<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>
++++

[[yasm-description]]
=== Description

The **yasm** command assembles the file ?infile? and directs output to
the file ?outfile? if specified.  If ?outfile? is not specified,
**yasm** will derive a default output file name from the name of its
input file, usually by appending `.o` or `.obj`, or by removing all
extensions for a raw binary file.  Failing that, the output file name
will be `yasm.out`.

If called with an ?infile? of ""-"", **yasm** assembles the standard
input and directs output to the file ?outfile?, or `yasm.out` if no
?outfile? is specified.

If errors or warnings are discovered during execution, Yasm outputs
the error message to `stderr` (usually the terminal).  If no errors or
warnings are encountered, Yasm does not output any messages.

[[yasm-options]]
=== Options

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.

[[yasm-general-options]]
==== General Options

[[yasm-option-arch]]
===== %-a ?arch?% or %--arch=?arch?%: Select target architecture

Selects the target architecture.  The default architecture is ""x86"",
which supports both the IA-32 and derivatives and AMD64 instruction
sets.  To print a list of available architectures to standard output,
use ""help"" as ?arch?.  See <<running-arch>> for a list of supported
architectures.

[[yasm-option-oformat]]
===== %-f ?format?% or %--oformat=?format?%: Select object format

Selects the output object format.  The default object format is
""bin"", which is a flat format binary with no relocation.  To print a
list of available object formats to standard output, use ""help"" as
?format?.  See <<running-objfmt>> for a list of supported object
formats.

[[yasm-option-dformat]]
===== %-g ?debug?% or %--dformat=?debug?%: Select debugging format

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;
**yasm** 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 ""help""
as ?debug?.  See <<running-dbgfmt>> for a list of supported debugging
formats.

[[yasm-option-help]]
===== %-h% or %--help%: Print a summary of options

Prints a summary of invocation options.  All other options are
ignored, and no output file is generated.

[[yasm-option-lformat]]
===== %-L ?list?% or %--lformat=?list?%: Select list file format

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 ""nasm"", which mimics
the NASM list file format.  To print a list of available list file
formats to standard output, use ""help"" as ?list?.

[[yasm-option-list]]
===== %-l ?listfile?% or %--list=?listfile?%: Specify list filename

Specifies the name of the output list file.  If this option is not
used, no list file is generated.

[[yasm-option-machine]]
===== %-m ?machine?% or %--machine=?machine?%: Select target machine architecture

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 ""x86"" architecture, the
two available machines are ""x86"", which is used for the IA-32 and
derivative 32-bit instruction set, and ""amd64"", 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 ""help"" as ?machine? and the
given architecture using %-a ?arch?%.  See <<architectures>> for more
details.

[[yasm-option-objfile]]
===== %-o ?filename?% or %--objfile=?filename?%: Specify object filename

Specifies the name of the output file, overriding any default name
generated by Yasm.

[[yasm-option-parser]]
===== %-p ?parser?% or %--parser=?parser?%: Select parser

Selects the parser (the assembler syntax).  The default parser is
""nasm"", which emulates the syntax of NASM, the Netwide Assembler.
Another available parser is ""gas"", which emulates the syntax of GNU
AS.  To print a list of available parsers to standard output, use
""help"" as ?parser?.  See <<running-parser>> for a list of supported
parsers.

[[yasm-option-preproc]]
===== %-r ?preproc?% or %--preproc=?preproc?%: Select preprocessor

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
""nasm"", which is an imported version of the actual NASM
preprocessor.  A ""raw"" 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 ""help"" as ?preproc?.

[[yasm-option-version]]
===== %--version%: Get the Yasm version

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.

[[yasm-warning-options]]
==== Warning Options

%-W% options have two contrary forms: %-W?name?% and %-Wno-?name?%.
Only the non-default forms are shown here.

The warning options are handled in the order given on the command
line, so if %-w% is followed by %-Worphan-labels%, all warnings are
turned off _except_ for orphan-labels.

[[yasm-option-w]]
===== %-w%: Inhibit all warning messages

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.

[[yasm-option-werror]]
===== %-Werror%: Treat warnings as errors

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 **yasm**, whereas errors do.
This option makes warnings equivalent to errors in terms of this
behavior.

[[yasm-option-wno-unrecognized-char]]
===== %-Wno-unrecognized-char%: Do not warn on unrecognized input characters

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.

[[yasm-option-worphan-labels]]
===== %-Worphan-labels%: Warn on labels lacking a trailing colon

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.

[[yasm-option-x]]
===== %-X ?style?%: Change error/warning reporting style

Selects a specific output style for error and warning messages.  The
default is ""gnu"" style, which mimics the output of **gcc**.  The
""vc"" style is also available, which mimics the output of Microsoft's
Visual Studio compiler.

This option is available so that Yasm integrates more naturally into
IDE environments such as **Visual Studio** or **Emacs**, allowing the
IDE to correctly recognize the error/warning message as such and link
back to the offending line of source code.

[[yasm-preprocessor-options]]
==== Preprocessor Options

While these preprocessor options theoretically will affect any
preprocessor, the only preprocessor currently in Yasm is the ""nasm""
preprocessor.

[[yasm-option-d]]
===== %-D ?macro[=value]?%: Pre-define a macro

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).

[[yasm-option-preproc-only]]
===== %-e% or %--preproc-only%: Only preprocess

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.

[[yasm-option-i]]
===== %-I ?path?%: Add include file path

Adds directory ?path? to the search path for include files.  The
search path defaults to only including the directory in which the
source file resides.

[[yasm-option-p]]
===== %-P ?filename?%: Pre-include a file

Pre-includes file ?filename?, making it look as though ?filename? was
prepended to the input.  Can be useful for prepending multi-line
macros that the %-D% can't support.

[[yasm-option-u]]
===== %-U ?macro?%: Undefine a macro

Undefines a single-line macro (may be either a built-in macro or one
defined earlier in the command line with %-D% (see <<yasm-option-d>>).

[[running-arch]]
=== Supported Target Architectures

Yasm supports the following instruction set architectures (ISAs).  For
more details see <<architectures>>.

x86::
  The ""x86"" architecture supports the IA-32 instruction set and
  derivatives (including 16-bit and non-Intel instructions) and the
  AMD64 instruction set.  It consists of two machines: ""x86"" (for
  the IA-32 and derivatives) and ""amd64"" (for the AMD64 and
  derivatives).  The default machine for the ""x86"" architecture is
  the ""x86"" machine.

[[running-parser]]
=== Supported Parsers (Syntaxes)

Yasm parses the following assembler syntaxes:

nasm::
  NASM syntax is the most full-featured syntax supported by Yasm.
  Yasm is nearly 100% compatible with NASM for 16-bit and 32-bit x86
  code.  Yasm additionally supports 64-bit AMD64 code with Yasm
  extensions to the NASM syntax.  For more details see <<nasm>>.

gas::
  The GNU Assembler (GAS) is the de-facto cross-platform assembler for
  modern Unix systems, and is used as the backend for the GCC
  compiler.  Yasm's support for GAS syntax is moderately good,
  although immature: not all directives are supported, and only 32-bit
  x86 and AMD64 architectures are supported.  There is also no support
  for the GAS preprocessor.  Despite these limitations, Yasm's GAS
  syntax support is good enough to handle essentially all x86 and
  AMD64 GCC compiler output.  For more details see <<gas>>.

[[running-objfmt]]
=== Supported Object Formats

Yasm supports the following object formats.  More details can be found
in <<objfmts>>.

bin::
  The ""bin"" object format produces a flat-format, non-relocatable
  binary file.  It is appropriate for producing DOS .COM executables
  or things like boot blocks.  It supports only 3 sections and those
  sections are written in a predefined order to the output file.

coff::
  The COFF object format is an older relocatable object format used on
  older Unix and compatible systems, and also (more recently) on the
  DJGPP development system for DOS.

dbg::
  The ""dbg"" object format is not a ""real"" object format; the
  output file it creates simply describes the sequence of calls made
  to it by Yasm and the final object and symbol table information in a
  human-readable text format (that in a normal object format would get
  processed into that object format's particular binary
  representation).  This object format is not intended for real use,
  but rather for debugging Yasm's internals.

elf::
  The ELF object format really comes in two flavors: ""elf32"" (for
  32-bit targets) and ""elf64"" (for 64-bit targets).  ELF is a
  standard object format in common use on modern Unix and compatible
  systems (e.g. Linux, FreeBSD).  ELF has complex support for
  relocatable and shared objects.

macho::
  The Mach-O object format really comes in two flavors: ""macho32""
  (for 32-bit targets) and ""macho64"" (for 64-bit targets).  Mach-O
  is used as the object format on MacOS X.  As Yasm currently only
  supports x86 and AMD64 instruction sets, it can only generate Mach-O
  objects for Intel-based Macs.

rdf::
  The RDOFF2 object format is a simple multi-section format originally
  designed for NASM.  It supports segment references but not WRT
  references.  It was designed primarily for simplicity and has
  minimalistic headers for ease of loading and linking.  A complete
  toolchain (linker, librarian, and loader) is distributed with NASM.

win32::
  The Win32 object format produces object files compatible with
  Microsoft compilers (such as Visual Studio) that target the 32-bit
  x86 Windows platform.  The object format itself is an extended
  version of COFF.

win64::
  The Win64 object format produces object files compatible with
  Microsoft compilers that target the 64-bit ""x64"" Windows platform.
  This format is very similar to the win32 object format, but produces
  64-bit objects.

xdf::
  The XDF object format is essentially a simplified version of COFF.
  It's a multi-section relocatable format that supports 64-bit
  physical and virtual addresses.

[[running-dbgfmt]]
=== Supported Debugging Formats

Yasm supports generation of source-level debugging information in the
following formats.  More details can be found in <<dbgfmts>>.

cv8::
  The CV8 debug format is used by Microsoft Visual Studio 2005
  (version 8.0) and is completely undocumented, although it bears
  strong similarities to earlier CodeView formats.  Yasm's support for
  the CV8 debug format is currently limited to generating
  assembly-level line number information (to allow some level of
  source-level debugging).  The CV8 debug information is stored in the
  `.debug$S` and `.debug$T` sections of the Win64 object file.

dwarf2::
  The DWARF 2 debug format is a complex, well-documented standard for
  debugging information.  It was created to overcome shortcomings in
  STABS, allowing for much more detailed and compact descriptions of
  data structures, data variable movement, and complex language
  structures such as in C++.  The debugging information is stored in
  sections (just like normal program sections) in the object file.
  Yasm supports full pass-through of DWARF2 debugging information
  (e.g. from a C++ compiler), and can also generate assembly-level
  line number information.

null::
  The ""null"" debug format is a placeholder; it adds no debugging
  information to the output file.

stabs::
  The STABS debug format is a poorly documented, semi-standard format
  for debugging information in COFF and ELF object files.  The
  debugging information is stored as part of the object file's symbol
  table and thus is limited in complexity and scope.  Despite this,
  STABS is a common debugging format on older Unix and compatible
  systems, as well as DJGPP.

////
[[running-examples]]
=== Examples
////

// vim: set syntax=asciidoc sw=2 tw=70:
