Command-Line Options
********************

   This chapter describes command-line options available in *all*
versions of the GNU assembler; see Machine Dependent., for options
specific to particular machine architectures.

Enable Listings: `-a', `-al', `-as'
===================================

   These options enable listing output from the assembler.  `-a' by
itself requests all listing output; `-al' requests only the
output-program listing, and `-as' requests only a symbol table listing.

   Once you have specified one of these options, you can further control
listing output and its appearance using the directives `.list',
`.nolist', `.psize', `.eject', `.title', and `.sbttl'.

   If you do not request listing output with one of the `-a' options,
the listing-control directives have no effect.

`-D'
====

   This option has no effect whatsoever, but it is accepted to make it
more likely that scripts written for other assemblers will also work
with `as'.

Work Faster: `-f'
=================

   `-f' should only be used when assembling programs written by a
(trusted) compiler.  `-f' stops the assembler from pre-processing the
input file(s) before assembling them.  See Pre-processing: Pre-processing.

     *Warning:* if the files actually need to be pre-processed (if they
     contain comments, for example), `as' will not work correctly if
     `-f' is used.

`.include' search path: `-I' PATH
=================================

   Use this option to add a PATH to the list of directories `as' will
search for files specified in `.include' directives (see `.include': Include.).  You may use `-I' as many times as necessary to include a
variety of paths.  The current working directory is always searched
first; after that, `as' searches any `-I' directories in the same order
as they were specified (left to right) on the command line.

Difference Tables: `-k'
=======================

   `as' sometimes alters the code emitted for directives of the form
`.word SYM1-SYM2'; see `.word': Word..  You can use the `-k' option
if you want a warning issued when this is done.

Include Local Labels: `-L'
==========================

   Labels beginning with `L' (upper case only) are called "local
labels". See Symbol Names.  Normally you don't see such labels when
debugging, because they are intended for the use of programs (like
compilers) that compose assembler programs, not for your notice.
Normally both `as' and `ld' discard such labels, so you don't normally
debug with them.

   This option tells `as' to retain those `L...' symbols in the object
file.  Usually if you do this you also tell the linker `ld' to preserve
symbols whose names begin with `L'.

Name the Object File: `-o'
==========================

   There is always one object file output when you run `as'.  By
default it has the name `a.out'.  You use this option (which takes
exactly one filename) to give the object file a different name.

   Whatever the object file is called, `as' will overwrite any existing
file of the same name.

Join Data and Text Sections: `-R'
=================================

   `-R' tells `as' to write the object file as if all data-section data
lives in the text section.  This is only done at the very last moment:
your binary data are the same, but data section parts are relocated
differently.  The data section part of your object file is zero bytes
long because all it bytes are appended to the text section.  (
See Sections and Relocation: Sections.)

   When you specify `-R' it would be possible to generate shorter
address displacements (because we don't have to cross between text and
data section).  We refrain from doing this simply for compatibility with
older versions of `as'.  In future, `-R' may work this way.

   When `as' is configured for COFF output, this option is only useful
if you use sections named `.text' and `.data'.

Announce Version: `-v'
======================

   You can find out what version of as is running by including the
option `-v' (which you can also spell as `-version') on the command
line.

Suppress Warnings: `-W'
=======================

   `as' should never give a warning or error message when assembling
compiler output.  But programs written by people often cause `as' to
give a warning that a particular assumption was made.  All such
warnings are directed to the standard error file.  If you use this
option, no warnings are issued.  This option only affects the warning
messages: it does not change any particular of how `as' assembles your
file.  Errors, which stop the assembly, are still reported.