Using as: Invoking

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. Command-Line Options

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

If you are invoking `as` via the GNU C compiler, you can use the ``-Wa'` option to pass arguments through to the assembler. The assembler arguments must be separated from each other (and the ``-Wa'`) by commas. For example:

    gcc -c -g -O -Wa,-alh,-L file.c

This passes two options to the assembler: ``-alh'` (emit a listing to standard output with high-level and assembly source) and ``-L'` (retain local symbols in the symbol table).

Usually you do not need to use this ``-Wa'` mechanism, since many compiler command-line options are automatically passed to the assembler by the compiler. (You can call the GNU compiler driver with the ``-v'` option to see precisely what options it passes to each compilation pass, including the assembler.)

> 2.1 Enable Listings: ``-a[cdghlns]'` |  | -a[cdghlns] enable listings
> 2.2 ``--alternate'` |  | --alternate enable alternate macro syntax
> 2.3 ``-D'` |  | -D for compatibility
> 2.4 Work Faster: ``-f'` |  | -f to work faster
> 2.5 `.include` Search Path: ``-I'` path |  | -I for .include search path
> 2.6 Difference Tables: ``-K'` |  | -K for difference tables

> 2.7 Include Local Symbols: ``-L'` |  | -L to retain local symbols
> 2.8 Configuring listing output: ``--listing'` |  | --listing-XXX to configure listing output
> 2.9 Assemble in MRI Compatibility Mode: ``-M'` |  | -M or --mri to assemble in MRI compatibility mode
> 2.10 Dependency Tracking: ``--MD'` |  | --MD for dependency tracking
> 2.11 Name the Object File: ``-o'` |  | -o to name the object file
> 2.12 Join Data and Text Sections: ``-R'` |  | -R to join data and text sections
> 2.13 Display Assembly Statistics: ``--statistics'` |  | --statistics to see statistics about assembly
> 2.14 Compatible Output: ``--traditional-format'` |  | --traditional-format for compatible output
> 2.15 Announce Version: ``-v'` |  | -v to announce version
> 2.16 Control Warnings: ``-W'`, ``--warn'`, ``--no-warn'`, ``--fatal-warnings'` |  | -W, --no-warn, --warn, --fatal-warnings to control warnings
> 2.17 Generate Object File in Spite of Errors: ``-Z'` |  | -Z to make object file even after errors

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 Enable Listings: ``-a[cdghlns]'`

These options enable listing output from the assembler. By itself, ``-a'` requests high-level, assembly, and symbols listing. You can use other letters to select specific options for the list: ``-ah'` requests a high-level language listing, ``-al'` requests an output-program assembly listing, and ``-as'` requests a symbol table listing. High-level listings require that a compiler debugging option like ``-g'` be used, and that assembly listings (``-al'`) be requested also.

Use the ``-ag'` option to print a first section with general assembly information, like as version, switches passed, or time stamp.

Use the ``-ac'` option to omit false conditionals from a listing. Any lines which are not assembled because of a false `.if` (or `.ifdef`, or any other conditional), or a true `.if` followed by an `.else`, will be omitted from the listing.

Use the ``-ad'` option to omit debugging directives from the 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`. The ``-an'` option turns off all forms processing. If you do not request listing output with one of the ``-a'` options, the listing-control directives have no effect.

The letters after ``-a'` may be combined into one option, e.g., ``-aln'`.

Note if the assembler source is coming from the standard input (e.g., because it is being created by `gcc` and the ``-pipe'` command line switch is being used) then the listing will not contain any comments or preprocessor directives. This is because the listing code buffers input source lines from stdin only after they have been preprocessed by the assembler. This reduces memory usage and makes the code more efficient.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.2 ``--alternate'`

Begin in alternate macro mode, see `.altmacro`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 ``-D'`

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.4 Work Faster: ``-f'`

``-f'` should only be used when assembling programs written by a (trusted) compiler. ``-f'` stops the assembler from doing whitespace and comment preprocessing on the input file(s) before assembling them. See section Preprocessing.

> Warning: if you use ``-f'` when the files actually need to be preprocessed (if they contain comments, for example), `as` does not work correctly.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.5 `.include` Search Path: ``-I'` path

Use this option to add a path to the list of directories `as` searches for files specified in `.include` directives (see section `.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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.6 Difference Tables: ``-K'`

`as` sometimes alters the code emitted for directives of the form ``.word sym1-sym2'`. See section `.word`. You can use the ``-K'` option if you want a warning issued when this is done.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.7 Include Local Symbols: ``-L'`

Symbols beginning with system-specific local label prefixes, typically ``.L'` for ELF systems or ``L'` for traditional a.out systems, are called local symbols. See section 5.3 Symbol Names. Normally you do not see such symbols 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 symbols, so you do not normally debug with them.

This option tells `as` to retain those local symbols in the object file. Usually if you do this you also tell the linker `ld` to preserve those symbols.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.8 Configuring listing output: ``--listing'`

The listing feature of the assembler can be enabled via the command line switch ``-a'` (see section 2.1 Enable Listings: ``-a[cdghlns]'`). This feature combines the input source file(s) with a hex dump of the corresponding locations in the output object file, and displays them as a listing file. The format of this listing can be controlled by directives inside the assembler source (i.e., `.list` (see section 7.73 `.list`), `.title` (see section 7.114 `.title "heading"`), `.sbttl` (see section 7.97 `.sbttl "subheading"`), `.psize` (see section 7.91 `.psize lines , columns`), and `.eject` (see section 7.38 `.eject`) and also by the following switches:

`--listing-lhs-width=``number'``
  Sets the maximum width, in words, of the first line of the hex byte dump. This dump appears on the left hand side of the listing output.

`--listing-lhs-width2=``number'``
  Sets the maximum width, in words, of any further lines of the hex byte dump for a given input source line. If this value is not specified, it defaults to being the same as the value specified for ``--listing-lhs-width'`. If neither switch is used the default is to one.

`--listing-rhs-width=``number'``
  Sets the maximum width, in characters, of the source line that is displayed alongside the hex dump. The default value for this parameter is 100. The source line is displayed on the right hand side of the listing output.

`--listing-cont-lines=``number'``
  Sets the maximum number of continuation lines of hex dump that will be displayed for a given single line of source input. The default value is 4.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.9 Assemble in MRI Compatibility Mode: ``-M'`

The ``-M'` or ``--mri'` option selects MRI compatibility mode. This changes the syntax and pseudo-op handling of `as` to make it compatible with the `ASM68K` or the `ASM960` (depending upon the configured target) assembler from Microtec Research. The exact nature of the MRI syntax will not be documented here; see the MRI manuals for more information. Note in particular that the handling of macros and macro arguments is somewhat different. The purpose of this option is to permit assembling existing MRI assembler code using `as`.

The MRI compatibility is not complete. Certain operations of the MRI assembler depend upon its object file format, and can not be supported using other object file formats. Supporting these would require enhancing each object file format individually. These are:

- global symbols in common section

  The m68k MRI assembler supports common sections which are merged by the linker. Other object file formats do not support this. `as` handles common sections by treating them as a single common symbol. It permits local symbols to be defined within a common section, but it can not support global symbols, since it has no way to describe them.

- complex relocations

  The MRI assemblers support relocations against a negated section address, and relocations which combine the start addresses of two or more sections. These are not support by other object file formats.

- `END` pseudo-op specifying start address

  The MRI `END` pseudo-op permits the specification of a start address. This is not supported by other object file formats. The start address may instead be specified using the ``-e'` option to the linker, or in a linker script.

- `IDNT`, `.ident` and `NAME` pseudo-ops

  The MRI `IDNT`, `.ident` and `NAME` pseudo-ops assign a module name to the output file. This is not supported by other object file formats.

- `ORG` pseudo-op

  The m68k MRI `ORG` pseudo-op begins an absolute section at a given address. This differs from the usual `as` `.org` pseudo-op, which changes the location within the current section. Absolute sections are not supported by other object file formats. The address of a section may be assigned within a linker script.

There are some other features of the MRI assembler which are not supported by `as`, typically either because they are difficult or because they seem of little consequence. Some of these may be supported in future releases.

- EBCDIC strings

  EBCDIC strings are not supported.

- packed binary coded decimal

  Packed binary coded decimal is not supported. This means that the `DC.P` and `DCB.P` pseudo-ops are not supported.

- `FEQU` pseudo-op

  The m68k `FEQU` pseudo-op is not supported.

- `NOOBJ` pseudo-op

  The m68k `NOOBJ` pseudo-op is not supported.

- `OPT` branch control options

  The m68k `OPT` branch control options---`B`, `BRS`, `BRB`, `BRL`, and `BRW`---are ignored. `as` automatically relaxes all branches, whether forward or backward, to an appropriate size, so these options serve no purpose.

- `OPT` list control options

  The following m68k `OPT` list control options are ignored: `C`, `CEX`, `CL`, `CRE`, `E`, `G`, `I`, `M`, `MEX`, `MC`, `MD`, `X`.

- other `OPT` options

  The following m68k `OPT` options are ignored: `NEST`, `O`, `OLD`, `OP`, `P`, `PCO`, `PCR`, `PCS`, `R`.

- `OPT` `D` option is default

  The m68k `OPT` `D` option is the default, unlike the MRI assembler. `OPT NOD` may be used to turn it off.

- `XREF` pseudo-op.

  The m68k `XREF` pseudo-op is ignored.

- `.debug` pseudo-op

  The i960 `.debug` pseudo-op is not supported.

- `.extended` pseudo-op

  The i960 `.extended` pseudo-op is not supported.

- `.list` pseudo-op.

  The various options of the i960 `.list` pseudo-op are not supported.

- `.optimize` pseudo-op

  The i960 `.optimize` pseudo-op is not supported.

- `.output` pseudo-op

  The i960 `.output` pseudo-op is not supported.

- `.setreal` pseudo-op

  The i960 `.setreal` pseudo-op is not supported.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.10 Dependency Tracking: ``--MD'`

`as` can generate a dependency file for the file it creates. This file consists of a single rule suitable for `make` describing the dependencies of the main source file.

The rule is written to the file named in its argument.

This feature is used in the automatic updating of makefiles.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.11 Name the Object File: ``-o'`

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

Whatever the object file is called, `as` overwrites any existing file of the same name.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.12 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 its bytes are appended to the text section. (See section Sections and Relocation.)

When you specify ``-R'` it would be possible to generate shorter address displacements (because we do not 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 or ELF output, this option is only useful if you use sections named ``.text'` and ``.data'`.

``-R'` is not supported for any of the HPPA targets. Using ``-R'` generates a warning from `as`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.13 Display Assembly Statistics: ``--statistics'`

Use ``--statistics'` to display two statistics about the resources used by `as`: the maximum amount of space allocated during the assembly (in bytes), and the total execution time taken for the assembly (in CPU seconds).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.14 Compatible Output: ``--traditional-format'`

For some targets, the output of `as` is different in some ways from the output of some existing assembler. This switch requests `as` to use the traditional format instead.

For example, it disables the exception frame optimizations which `as` normally does by default on `gcc` output.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.15 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.16 Control Warnings: ``-W'`, ``--warn'`, ``--no-warn'`, ``--fatal-warnings'`

`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 the ``-W'` and ``--no-warn'` options, no warnings are issued. This 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.

If you use the ``--fatal-warnings'` option, `as` considers files that generate warnings to be in error.

You can switch these options off again by specifying ``--warn'`, which causes warnings to be output as usual.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.17 Generate Object File in Spite of Errors: ``-Z'`

After an error message, `as` normally produces no output. If for some reason you are interested in object file output even after `as` gives an error message on your program, use the ``-Z'` option. If there are any errors, `as` continues anyways, and writes an object file after a final warning message of the form ``n errors, m warnings, generating bad object file.'`

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 10 2014 using texi2html