This chapter describes the module-independent part of the assembler. It
documents the options and extensions which are not specific to a certain
target, syntax or output driver. Be sure to also read the chapters on the
cpu-backend, syntax- and output-module you are using. They will
likely contain important additional information like data-representation
or additional options.

@node General Assembler Options
@section General Assembler Options

    @command{vasm} is run from the command line using the following syntax:

@example
      @command{vasm<target>_<syntax> [options] [sourcefile]}
@end example

    When the source file name is missing, the assembler reads the source
    text from @file{stdin} until encountering @code{EOF} (end-of-file,
    which is @code{CTRL-D} in Unix shells, or @code{CTRL-\} in AmigaOS
    shells). Note, that most debugging formats (DWARF, etc.) no longer
    function with such temporary source texts.

    The following options are supported by the machine independent part
    of @command{vasm}. The most important ones are:

@table @option

@item -D<name>[=<expression>]
        Defines a symbol with the name @code{<name>} and assigns the value of the
        expression when given. The assigned value defaults to 1 otherwise.

@item -F<fmt>
        Use module @code{<fmt>} as output driver. See the chapter on output
        drivers for available formats and options.

@item -I<path>
        Define another include path. They are searched in the order of
        occurrence on the command line, and always before any include paths
        defined in the source.

@item -L <listfile>
        Enables generation of a listing file and directs the output into
        the file @code{<listfile>}.

@item -nocase
        Disables case-sensitivity for symbols. This doesn't necessarily
        include macro and structure names, which depend on the syntax-module
        in use. Mnemonics and directives are usually case-insensitive by
        default.

@item -nosym
        Strips all local symbols from the output file and doesn't keep
        any other symbols than those which are required for external
        linkage.

@item -o <ofile>
        Write the assembler output to @code{<ofile>} rather than @file{a.out}.

@item -quiet      
        Do not print the copyright notice and the final statistics.

@item -x
        Show an error message when referencing an undefined symbol.
        The default behaviour is to declare such symbols as externally
        defined.
@end table

Other options:

@table @option

@item -ctrace
        Enable tracing of conditional assembly while parsing. Prints all
        lines with conditional directives to stderr, preceded by a number
        of arrows representing the conditional nesting level and a flag
        (0/1) whether the following block will be assembled.

@item -depend=<type>
        Print all dependencies while assembling the source with the given
        options. No output is generated. @code{<type>} may be the word @option{list}
        for printing one file name in each new line, or @option{make} for
        printing a sequence of file names on a single line, suitable for
        Makefiles.
        If the output file name is given by @option{-o outname} then
        @command{vasm} will also print @code{outname:} in front of it.
        Note that in contrast to option @option{-dependall} only relative
        include file dependencies will be listed (which is the common case).

@item -dependall=<type>
        Prints dependencies in the same way as @option{-depend}, but
        adds the include files using absolute paths to it.

@item -depfile <filename>
        Used together with @option{-depend} or @option{-dependall} and
        instructs vasm to output all dependencies into a new file, instead
        of stdout. Additionally, code will be generated in parallel to the
        dependencies output.

@item -dwarf[=<version>]
        Automatically generate DWARF debugging sections, suitable for
        source level debugging. When the version specification is missing,
        DWARF V3 will be emitted. The only difference to V2 is that it
        creates a @code{.debug_ranges} section, with address ranges for all
        sections, instead of using a workaround by specifying
        @code{DW_AT_low_pc=0} and @code{DW_AT_high_pc=~0}.
        Note, that when you build vasm from source, you may have to set
        your host operating system with @code{-Dname} in the Makefile to
        include the appropriate code which can determine the current
        work directory. Otherwise the default would be to set the current
        work directory to an empty string. Currently supported are:
        @code{AMIGA}, @code{ATARI}, @code{MSDOS}, @code{UNIX},
        @code{_WIN32}. MacOSX works with @code{UNIX}.

@item -esc
        Enable escape character sequences. This will make vasm treat the
        escape character \ in string constants similar as in the C language.

@item -ibe
        Use big-endian order when reading target-bytes with more than
        8 bits per byte from the host's file system (default).

@item -ignore-mult-inc
        When the same file is included multiple times, using the same path,
        this is silently ignored, causing the file to be processed only
        once. Note, that you can still include the same file twice when
        using different paths to access it.

@item -ile
        Use little-endian order when reading target-bytes with more than
        8 bits per byte from the host's file system.

@item -iserror=<n>
        Turn warning message @code{<n>} into an error.
        @code{<n>} has to be the number of a valid warning message.

@item -Lall
        List all symbols, including unused equates. Default is to list
        all labels and all used expressions only.

@item -Lbpl=<n>
        Set the maximum number of bytes per line in a listing file to @code{<n>}.
        Defaults to 8 (fmt=@code{wide}).

@item -Lfmt=<fmt>
        Set the listing file format to @code{<fmt>}. Defaults to wide.
        Available are: @code{wide}, @code{old}.

@item -Llo
        Show only program labels in the sorted symbol listing. Default
        is to list all symbols, including absolute expressions.

@item -Lni
        Do not show included source files in the listing file (fmt=@code{wide}).

@item -Lns
        Do not include symbols in the listing file (fmt=@code{wide}).

@item -maxerrors=<n>
        Sets the maximum number of errors to display before assembly
        is aborted. When @code{<n>} is 0 then there is no limit. Defaults to 5.

@item -maxmacrecurs=<n>
        Defines the maximum number of recursion levels within a macro.
        Defaults to 1000.

@item -maxpasses=<n>
        Adjusts the maximum number of passes while resolving a section.
        Defaults to 1500.

@item -no-msrcdebug
        Disable source level debugging within a macro context.
        When generating output with source level debug information, the
        debugger will show the invoking source text line instead.

@item -nocompdir
        Do not search for include files relative to the compile directory
        (where the main input source is located).

@item -noesc
        No escape character sequences. This will make vasm treat the
        escape character \ as any other character. Might be useful for
        compatibility. This is the default in most modules.

@item -noialign
        Perform no automatic alignment for instructions. Note, that
        unaligned instructions can make your code crash when executed!
        Only set if you know what you are doing!

@item -nomsg=<n>
        Disable the informational message @code{<n>}. @code{<n>} has to be the number
        of a valid informational message, like an optimization message.

@item -nowarn=<n>
        Disable warning message @code{<n>}. @code{<n>} has to be the number of a valid
        warning message, otherwise an error is generated.

@item -obe
        Write target-bytes with more than 8 bits per byte in big-endian
        order to the host's file system (default).

@item -ole
        Write target-bytes with more than 8 bits per byte in little-endian
        order to the host's file system.

@item -pad=<value>
        The given padding value can be one or multiple bytes (up to the
        cpu-backend's address size). It is used for alignment purposes
        and to fill gaps between absolute @code{ORG} sections in the
        binary output module. Defaults to a zero-byte.

@item -pic
        Try to generate position independent code. Every address needing
        relocation is flagged by an error message. This option overrides
        the absolute default mode (@code{ORG 0}) of binary output
        modules and doesn't work if you force the assembler into
        absolute mode by such a directive.

@item -relpath
        Do not interpret a source path starting with '/' or '\', or including
        a colon, as absolute, but always attach it relative to defined
        include paths first.

@item -underscore
        Add a leading underscore in front of all imported and exported
        (also common, weak) symbol names, just before writing the
        output file.

@item -unnamed-sections
        Sections are no longer distinguished by their name, but only by
        their attributes. Which has the effect that when defining a second
        section with a different name, but same attributes as a first one,
        it will switch to the first, instead of starting a new section.
        Is enabled automatically, when using an output-module which doesn't
        support section names. For example: aout, tos, xfile.

@item -unsshift
        The shift-right operator (@code{>>}) treats the value to shift as
        unsigned, which has the effect that only 0-bits are inserted on the
        left (MSB) side. The number of bits in a value depend on the target
        address type (refer to the appropriate cpu module documentation).
        This may already be the default for some syntax modules, like for
        example mot-syntax in Devpac-compatibility mode.

@item -uspc=<value>
        Uninitialized memory regions, declared by "space" directives
        (@code{.space} in std-syntax, @code{ds} in mot-syntax, etc.)
        are filled with the given value. Defaults to zero.

@item -v
        Print version and copyright messages from the assembler and all
        its modules, then exit.

@item -w
        Hide all warning messages.

@item -wfail
        The return code of vasm will no longer be 0 (success), when there
        was a warning. Errors always make the return code non-zero (failure).
@end table

Note, that while most options allow an argument without any separating blank,
some do require it (e.g. @option{-o} and @option{-L}).

@section Expressions

Standard expressions are usually evaluated by vasm's core routines
rather than by one of the modules (unless this is necessary).

All expressions evaluated by the frontend are calculated in terms
of target address values, i.e. the range depends on the backend.
Constants which exceed the target address range may be supported by
some backends up to 128 bits.

Backends also have the option to support floating point constants directly
and convert them to a backend-specific format which is described in the
backend's documentation.

@b{Warning:} Be aware that the quality and precision of the backend's
floating point output depends on the combination of host- and
backend-format! If you need absolute precision, encode the floating
point constants yourself in binary.

The available operator tokens may be extended or modified by the current
syntax module in use, but the default is to use the same operators as in
the C programming language.

Note, though, that the operator priority and associativitiy may be different 
from C, to comply with common assembler behaviour. The expression evaluation
priorities, from highest to lowest, are:

@enumerate 1
@item @code{+ - ! ~} (unary +/- sign, not, bitwise complement)
@item @code{<< >>} (shift left, shift right)
@item @code{&} (bitwise and)
@item @code{^} (bitwise exclusive-or)
@item @code{|} (bitwise inclusive-or)
@item @code{* / %} (multiply, divide, modulo)
@item @code{+ -} (add, subtract)
@item @code{< > <= >=} (less, greater, less or equal, greater or equal)
@item @code{== !=} (equality and inequality)
@item @code{&&} (logical and)
@item @code{||} (logical or)
@end enumerate

Operands are integral values of the target address type. They can either be
specified as integer constants of different bases (see the documentation
on the syntax module to see how the base is specified) or character
constants. Character constants are introduced by @code{'} or @code{"}
and have to be terminated by the same character that started them.

Multiple characters are allowed and a constant is built according to the
endianness of the target.

When the @option{-esc} option was specified, or automatically enabled by
a syntax module, vasm interprets escape character sequences as in the
C language:

@table @code

@item \\
        Produces a single @code{\}.

@item \b
        The bell character.

@item \e
        Escape character (27).

@item \f
        Form feed.

@item \n
        Line feed.

@item \r
        Carriage return.

@item \t
        Tabulator.

@item \"
        Produces a single @code{"}.
    
@item \'
        Produces a single @code{'}.

@item \<octal-digits>
        One character with the code specified by the digits
        as octal value.

@item \x<hexadecimal-digits>
        One character with the code specified by the digits
        as hexadecimal value.

@item \X<hexadecimal-digits>
        Same as @code{\x}.

@end table

Note, that the default behaviour of vasm has changed since V1.7! Escape
sequence handling has been the default in older versions. This was
changed to improve compatibility with other assemblers. Use @option{-esc}
to assemble sources with escape character sequences. It is still the
default in the @code{std} syntax module, though.

@section Symbols

You can define as many symbols as your available memory permits. A symbol
may have any length and can be of global or local scope. Internally, there
are three types of symbols:
@table @code
@item Expression
      These symbols are usually not visible outside of the
      source, unless they are explicitly exported.
      Note, that some object file formats use exported expressions
      referencing an imported symbol to represent indirect symbols.
@item Label
      Labels are always addresses within a program section. By
      default they have local scope for the linker.
@item Imported
      These symbols are externally defined and must be
      resolved by the linker.
@end table

@section Predefined Symbols

Beginning with vasm V1.5c at least one expression symbol is always defined
to allow conditional assembly depending on the assembler being used:
@code{__VASM}. Its value depends on the selected cpu module.

Since V1.8i there may be a second internal symbol which reflects the
format of the paths in the host file system. Currently there may be one of:
@table @code
@item __UNIXFS
      Host file system uses Unix-style paths.
@item __MSDOSFS
      Host file system uses MS-DOS-, Windows-, Atari-style paths.
@item __AMIGAFS
      Host file system uses AmigaDOS-style paths.
@end table
Note that such a path-style symbol must be configured by a @code{-D} option
while compiling vasm from source. Refer to the section about
building vasm (Interface chapter) for a listing of all supported host
OS options.

There may be other internal symbols, which are defined by the
syntax- or by the cpu module.

@section Include Files

Vasm supports include files and defining include paths. Whether this
functionality is available depends on the syntax module, which has to
provide the appropriate directives.

On startup vasm defines one or two default include paths: the current
work directory and, when the main source is not located there, the
compile directory.

Include paths are searched in the following order:
@enumerate 1
@item Current work directory.
@item Compile directory (path to main source).
@item Paths specified by @option{-I} in the order of occurrence on the
      command line.
@item Paths specified by directives in the source text (in the order
      of occurrence).
@end enumerate

Additionally, all the relative paths, defined by @option{-I} or directives,
are first appended to the current work directory name, then to the
compile directory name, while searching for an include file.

Searching for include files in paths based on the compile directory can be
completely disabled by @option{-nocompdir}.

@section Macros

Macros are supported by vasm, but the directives for defining them have
to be implemented in the syntax module. The assembler core supports 9
macro arguments by default to be passed in the operand field,
which can be extended to any number by the syntax module.
They can be referenced within the macro either by name (@code{\name}) or by
number (@code{\1} to @code{\9}), or both, depending on the syntax module.
Recursions and early exits are supported.

Refer to the selected syntax module for more details.

@section Structures

Vasm supports structures, but the directives for defining them
have to be implemented in the syntax module.

@section Conditional Assembly

Has to be provided completely by the syntax module.

@section Uninitialized Space

Some syntax modules allow the declaration of uninitialized space, either by
special directives or by assignment of the program counter (for example:
@code{*=*+n} or @code{org *+n}). Depending on the output module, this space
is usually not written to an output file.

@section Known Problems

    Some known module-independent problems of @command{vasm} at the moment:

@itemize @minus

@item None.

@end itemize

@section Credits

    All those who wrote parts of the @command{vasm} distribution, made suggestions,
    answered my questions, tested @command{vasm}, reported errors or were otherwise
    involved in the development of @command{vasm} (in descending alphabetical order,
    under work, not complete):

@itemize
    @item Jordan Zebor
    @item Joseph Zatarski
    @item Brian Woodruff
    @item Frank Wille
    @item Jim Westfall
    @item Bernard Thibault
    @item Dimitri Theulings
    @item Steven Tattersall
    @item Yannick Stamm
    @item Jens Sch@"onfeld
    @item Ross
    @item Henryk Richter
    @item Sebastian Pachuta
    @item Thorsten Otto
    @item Esben Norby
    @item Tom Noorduin
    @item Gunther Nikl
    @item George Nakos
    @item Timm S. Mueller
    @item Gareth Morris
    @item Dominic Morris
    @item Garry Marshall
    @item Jean-Paul Mari
    @item Mauricio Mu@~noz Lucero
    @item Grzegorz Mazur
    @item J@"org van de Loo
    @item Robert Leffmann
    @item Andreas Larsson
    @item Miro Krop@'a@v{c}ek
    @item Olav Kr@"omeke
    @item Christoph Krc
    @item Chester Kollschen
    @item Richard K@"orber
    @item Mikael Kalms
    @item Mark Jones
    @item Bert Jahn
    @item Daniel Illgen
    @item Jerome Hubert
    @item Matthew Hey
    @item Stefan Haubenthal
    @item S@o{}ren Hannibal
    @item John Hankinson
    @item Philippe Guichardon
    @item Luis Panadero Guarde@~no
    @item Romain Giot
    @item Daniel Gerdgren
    @item Fran@,cois Galea
    @item Tom Duin
    @item Adrien Destugues
    @item Kieran Connell
    @item Jae Choon Cha
    @item Fernando Cabrera
    @item Patrick Bricout
    @item Matthias Bock
    @item Simone Bevilacqua
    @item Karoly Balogh
    @item Patrik Axelsson
    @item Anomie-p
@end itemize

@section Error Messages

The frontend has the following error messages:

@itemize @minus
@item 1: illegal operand types
@item 2: unknown mnemonic <%s>
@item 3: unknown section <%s>
@item 4: no current section specified
@item 5: internal error %d in line %d of %s
@item 6: symbol <%s> redefined
@item 7: %c expected
@item 8: cannot resolve section <%s>, maximum number of passes reached
@item 9: instruction not supported on selected architecture
@item 10: number or identifier expected
@item 11: could not initialize %s module
@item 12: multiple input files
@item 13: could not open <%s> for input
@item 14: could not open <%s> for output
@item 15: unknown option <%s>
@item 16: %s module doesn't support %d-bit bytes
@item 17: could not initialize output module <%s>
@item 18: out of memory
@item 19: symbol <%s> recursively defined
@item 20: fail: %s
@item 21: section offset is lower than current pc
@item 22: target data type overflow (%d bits)
@item 23: undefined symbol <%s>
@item 24: trailing garbage after option -%c
@item 25: missing pacro parameters
@item 26: missing end directive for macro "%s"
@item 27: macro definition inside macro "%s"
@item 28: maximum number of %d macro arguments exceeded
@item 29: option %s was specified twice
@item 30: read error on <%s>
@item 31: expression must be constant
@item 32: initialized data in bss
@item 33: missing end directive in repeat-block
@item 34: #%d is not a valid warning message
@item 35: relocation not allowed
@item 36: illegal escape sequence \%c
@item 37: no current macro to exit
@item 38: internal symbol %s redefined by user
@item 39: illegal relocation
@item 40: label name conflicts with mnemonic
@item 41: label name conflicts with directive
@item 42: division by zero
@item 43: illegal macro argument
@item 44: reloc org is already set
@item 45: reloc org was not set
@item 46: address space overflow
@item 47: bad file-offset argument
@item 48: assertion "%s" failed: %s
@item 49: cannot declare structure within structure
@item 50: no structure
@item 51: instruction has been auto-aligned
@item 52: macro name conflicts with mnemonic
@item 53: macro name conflicts with directive
@item 54: non-relocatable expression in equate <%s>
@item 55: initialized data in offset section
@item 56: illegal structure recursion
@item 57: maximum number of macro recursions (%d) reached
@item 58: data has been auto-aligned
@item 59: register symbol <%s> redefined
@item 60: cannot evaluate constant huge integer expression
@item 61: cannot evaluate floating point expression
@item 62: imported symbol <%s> was not referenced
@item 63: symbol <%s> already defined with %s scope
@item 64: unexpected "else" without "if"
@item 65: unexpected "endif" without "if"
@item 66: maximum if-nesting depth exceeded (%d levels)
@item 67: "endif" missing for conditional block started at %s line %d
@item 68: repeatedly defined symbol <%s>
@item 69: macro <%s> does not exist
@item 70: register <%s> does not exist
@item 71: register symbol <%s> has wrong type
@item 72: cannot mix positional and keyword arguments
@item 73: undefined macro argument name
@item 74: required macro argument %d was left out
@item 75: label <%s> redefined
@item 76: base %d numerical term expected
@item 77: section stack overflow
@item 78: section stack is empty
@item 79: illegal value for option: %s
@item 80: %s backend does not support floating point
@item 81: unknown listing file format "%s" ignored
@item 82: cannot export equate based on imported symbol: <%s>
@item 83: label definition not allowed here
@item 84: label defined on the same line as a new section
@item 85: no debug output possible with source from stdin
@item 86: external symbol <%s> must not be defined
@item 87: missing definition for symbol <%s>
@item 88: additional macro arguments ignored (expecting %d)
@item 89: macro previously defined at line %d of %s
@end itemize
