500 lines
16 KiB
HTML
500 lines
16 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<!-- This HTML file has been created by texi2html 1.52
|
|
from ../texi/as.texinfo on 24 April 1999 -->
|
|
|
|
<TITLE>Using as - Command-Line Options</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
Go to the <A HREF="as_1.html">first</A>, <A HREF="as_1.html">previous</A>, <A HREF="as_3.html">next</A>, <A HREF="as_27.html">last</A> section, <A HREF="as_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC9" HREF="as_toc.html#TOC9">Command-Line Options</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX41"></A>
|
|
This chapter describes command-line options available in <EM>all</EM>
|
|
versions of the GNU assembler; see section <A HREF="as_8.html#SEC138">Machine Dependent Features</A>, for options specific
|
|
to particular machine architectures.
|
|
|
|
</P>
|
|
<P>
|
|
If you are invoking <CODE>as</CODE> via the GNU C compiler (version 2), you
|
|
can use the <SAMP>`-Wa'</SAMP> option to pass arguments through to the
|
|
assembler. The assembler arguments must be separated from each other
|
|
(and the <SAMP>`-Wa'</SAMP>) by commas. For example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
gcc -c -g -O -Wa,-alh,-L file.c
|
|
</PRE>
|
|
|
|
<P>
|
|
emits a listing to standard output with high-level
|
|
and assembly source.
|
|
|
|
</P>
|
|
<P>
|
|
Usually you do not need to use this <SAMP>`-Wa'</SAMP> 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 <SAMP>`-v'</SAMP> option to see
|
|
precisely what options it passes to each compilation pass, including the
|
|
assembler.)
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC10" HREF="as_toc.html#TOC10">Enable Listings: <CODE>-a[cdhlns]</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX42"></A>
|
|
<A NAME="IDX43"></A>
|
|
<A NAME="IDX44"></A>
|
|
<A NAME="IDX45"></A>
|
|
<A NAME="IDX46"></A>
|
|
<A NAME="IDX47"></A>
|
|
<A NAME="IDX48"></A>
|
|
<A NAME="IDX49"></A>
|
|
<A NAME="IDX50"></A>
|
|
|
|
</P>
|
|
<P>
|
|
These options enable listing output from the assembler. By itself,
|
|
<SAMP>`-a'</SAMP> requests high-level, assembly, and symbols listing.
|
|
You can use other letters to select specific options for the list:
|
|
<SAMP>`-ah'</SAMP> requests a high-level language listing,
|
|
<SAMP>`-al'</SAMP> requests an output-program assembly listing, and
|
|
<SAMP>`-as'</SAMP> requests a symbol table listing.
|
|
High-level listings require that a compiler debugging option like
|
|
<SAMP>`-g'</SAMP> be used, and that assembly listings (<SAMP>`-al'</SAMP>) be requested
|
|
also.
|
|
|
|
</P>
|
|
<P>
|
|
Use the <SAMP>`-ac'</SAMP> option to omit false conditionals from a listing. Any lines
|
|
which are not assembled because of a false <CODE>.if</CODE> (or <CODE>.ifdef</CODE>, or any
|
|
other conditional), or a true <CODE>.if</CODE> followed by an <CODE>.else</CODE>, will be
|
|
omitted from the listing.
|
|
|
|
</P>
|
|
<P>
|
|
Use the <SAMP>`-ad'</SAMP> option to omit debugging directives from the
|
|
listing.
|
|
|
|
</P>
|
|
<P>
|
|
Once you have specified one of these options, you can further control
|
|
listing output and its appearance using the directives <CODE>.list</CODE>,
|
|
<CODE>.nolist</CODE>, <CODE>.psize</CODE>, <CODE>.eject</CODE>, <CODE>.title</CODE>, and
|
|
<CODE>.sbttl</CODE>.
|
|
The <SAMP>`-an'</SAMP> option turns off all forms processing.
|
|
If you do not request listing output with one of the <SAMP>`-a'</SAMP> options, the
|
|
listing-control directives have no effect.
|
|
|
|
</P>
|
|
<P>
|
|
The letters after <SAMP>`-a'</SAMP> may be combined into one option,
|
|
<EM>e.g.</EM>, <SAMP>`-aln'</SAMP>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC11" HREF="as_toc.html#TOC11"><CODE>-D</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX51"></A>
|
|
This option has no effect whatsoever, but it is accepted to make it more
|
|
likely that scripts written for other assemblers also work with
|
|
<CODE>as</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC12" HREF="as_toc.html#TOC12">Work Faster: <CODE>-f</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX52"></A>
|
|
<A NAME="IDX53"></A>
|
|
<A NAME="IDX54"></A>
|
|
<SAMP>`-f'</SAMP> should only be used when assembling programs written by a
|
|
(trusted) compiler. <SAMP>`-f'</SAMP> stops the assembler from doing whitespace
|
|
and comment preprocessing on
|
|
the input file(s) before assembling them. See section <A HREF="as_3.html#SEC26">Preprocessing</A>.
|
|
|
|
</P>
|
|
|
|
<BLOCKQUOTE>
|
|
<P>
|
|
<EM>Warning:</EM> if you use <SAMP>`-f'</SAMP> when the files actually need to be
|
|
preprocessed (if they contain comments, for example), <CODE>as</CODE> does
|
|
not work correctly.
|
|
</BLOCKQUOTE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC13" HREF="as_toc.html#TOC13"><CODE>.include</CODE> search path: <CODE>-I</CODE> <VAR>path</VAR></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX55"></A>
|
|
<A NAME="IDX56"></A>
|
|
<A NAME="IDX57"></A>
|
|
<A NAME="IDX58"></A>
|
|
Use this option to add a <VAR>path</VAR> to the list of directories
|
|
<CODE>as</CODE> searches for files specified in <CODE>.include</CODE>
|
|
directives (see section <A HREF="as_7.html#SEC97"><CODE>.include "<VAR>file</CODE>"</VAR></A>). You may use <CODE>-I</CODE> as
|
|
many times as necessary to include a variety of paths. The current
|
|
working directory is always searched first; after that, <CODE>as</CODE>
|
|
searches any <SAMP>`-I'</SAMP> directories in the same order as they were
|
|
specified (left to right) on the command line.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC14" HREF="as_toc.html#TOC14">Difference Tables: <CODE>-K</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX59"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX60"></A>
|
|
<A NAME="IDX61"></A>
|
|
<CODE>as</CODE> sometimes alters the code emitted for directives of the form
|
|
<SAMP>`.word <VAR>sym1</VAR>-<VAR>sym2</VAR>'</SAMP>; see section <A HREF="as_7.html#SEC136"><CODE>.word <VAR>expressions</CODE></VAR></A>.
|
|
You can use the <SAMP>`-K'</SAMP> option if you want a warning issued when this
|
|
is done.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC15" HREF="as_toc.html#TOC15">Include Local Labels: <CODE>-L</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX62"></A>
|
|
<A NAME="IDX63"></A>
|
|
Labels beginning with <SAMP>`L'</SAMP> (upper case only) are called <EM>local
|
|
labels</EM>. See section <A HREF="as_5.html#SEC48">Symbol Names</A>. Normally you do not 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 <CODE>as</CODE> and <CODE>ld</CODE> discard such labels, so you do not
|
|
normally debug with them.
|
|
|
|
</P>
|
|
<P>
|
|
This option tells <CODE>as</CODE> to retain those <SAMP>`L...'</SAMP> symbols
|
|
in the object file. Usually if you do this you also tell the linker
|
|
<CODE>ld</CODE> to preserve symbols whose names begin with <SAMP>`L'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
By default, a local label is any label beginning with <SAMP>`L'</SAMP>, but each
|
|
target is allowed to redefine the local label prefix.
|
|
On the HPPA local labels begin with <SAMP>`L$'</SAMP>.
|
|
<SAMP>`;'</SAMP> for the ARM family;
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC16" HREF="as_toc.html#TOC16">Assemble in MRI Compatibility Mode: <CODE>-M</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX64"></A>
|
|
<A NAME="IDX65"></A>
|
|
The <CODE>-M</CODE> or <CODE>--mri</CODE> option selects MRI compatibility mode. This
|
|
changes the syntax and pseudo-op handling of <CODE>as</CODE> to make it
|
|
compatible with the <CODE>ASM68K</CODE> or the <CODE>ASM960</CODE> (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 <CODE>as</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
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:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>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. <CODE>as</CODE> 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.
|
|
|
|
<LI>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.
|
|
|
|
<LI><CODE>END</CODE> pseudo-op specifying start address
|
|
|
|
The MRI <CODE>END</CODE> 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 <CODE>-e</CODE> option to the linker, or in a linker
|
|
script.
|
|
|
|
<LI><CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops
|
|
|
|
The MRI <CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops assign a module
|
|
name to the output file. This is not supported by other object file formats.
|
|
|
|
<LI><CODE>ORG</CODE> pseudo-op
|
|
|
|
The m68k MRI <CODE>ORG</CODE> pseudo-op begins an absolute section at a given
|
|
address. This differs from the usual <CODE>as</CODE> <CODE>.org</CODE> 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.
|
|
</UL>
|
|
|
|
<P>
|
|
There are some other features of the MRI assembler which are not supported by
|
|
<CODE>as</CODE>, typically either because they are difficult or because they
|
|
seem of little consequence. Some of these may be supported in future releases.
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
|
|
<LI>EBCDIC strings
|
|
|
|
EBCDIC strings are not supported.
|
|
|
|
<LI>packed binary coded decimal
|
|
|
|
Packed binary coded decimal is not supported. This means that the <CODE>DC.P</CODE>
|
|
and <CODE>DCB.P</CODE> pseudo-ops are not supported.
|
|
|
|
<LI><CODE>FEQU</CODE> pseudo-op
|
|
|
|
The m68k <CODE>FEQU</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>NOOBJ</CODE> pseudo-op
|
|
|
|
The m68k <CODE>NOOBJ</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>OPT</CODE> branch control options
|
|
|
|
The m68k <CODE>OPT</CODE> branch control options---<CODE>B</CODE>, <CODE>BRS</CODE>, <CODE>BRB</CODE>,
|
|
<CODE>BRL</CODE>, and <CODE>BRW</CODE>---are ignored. <CODE>as</CODE> automatically
|
|
relaxes all branches, whether forward or backward, to an appropriate size, so
|
|
these options serve no purpose.
|
|
|
|
<LI><CODE>OPT</CODE> list control options
|
|
|
|
The following m68k <CODE>OPT</CODE> list control options are ignored: <CODE>C</CODE>,
|
|
<CODE>CEX</CODE>, <CODE>CL</CODE>, <CODE>CRE</CODE>, <CODE>E</CODE>, <CODE>G</CODE>, <CODE>I</CODE>, <CODE>M</CODE>,
|
|
<CODE>MEX</CODE>, <CODE>MC</CODE>, <CODE>MD</CODE>, <CODE>X</CODE>.
|
|
|
|
<LI>other <CODE>OPT</CODE> options
|
|
|
|
The following m68k <CODE>OPT</CODE> options are ignored: <CODE>NEST</CODE>, <CODE>O</CODE>,
|
|
<CODE>OLD</CODE>, <CODE>OP</CODE>, <CODE>P</CODE>, <CODE>PCO</CODE>, <CODE>PCR</CODE>, <CODE>PCS</CODE>, <CODE>R</CODE>.
|
|
|
|
<LI><CODE>OPT</CODE> <CODE>D</CODE> option is default
|
|
|
|
The m68k <CODE>OPT</CODE> <CODE>D</CODE> option is the default, unlike the MRI assembler.
|
|
<CODE>OPT NOD</CODE> may be used to turn it off.
|
|
|
|
<LI><CODE>XREF</CODE> pseudo-op.
|
|
|
|
The m68k <CODE>XREF</CODE> pseudo-op is ignored.
|
|
|
|
<LI><CODE>.debug</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.debug</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.extended</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.extended</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.list</CODE> pseudo-op.
|
|
|
|
The various options of the i960 <CODE>.list</CODE> pseudo-op are not supported.
|
|
|
|
<LI><CODE>.optimize</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.optimize</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.output</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.output</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.setreal</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.setreal</CODE> pseudo-op is not supported.
|
|
|
|
</UL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC17" HREF="as_toc.html#TOC17">Dependency tracking: <CODE>--MD</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX66"></A>
|
|
<A NAME="IDX67"></A>
|
|
<A NAME="IDX68"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<CODE>as</CODE> can generate a dependency file for the file it creates. This
|
|
file consists of a single rule suitable for <CODE>make</CODE> describing the
|
|
dependencies of the main source file.
|
|
|
|
</P>
|
|
<P>
|
|
The rule is written to the file named in its argument.
|
|
|
|
</P>
|
|
<P>
|
|
This feature is used in the automatic updating of makefiles.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC18" HREF="as_toc.html#TOC18">Name the Object File: <CODE>-o</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX69"></A>
|
|
<A NAME="IDX70"></A>
|
|
<A NAME="IDX71"></A>
|
|
There is always one object file output when you run <CODE>as</CODE>. By
|
|
default it has the name
|
|
<TT>`a.out'</TT> (or <TT>`b.out'</TT>, for Intel 960 targets only).
|
|
You use this option (which takes exactly one filename) to give the
|
|
object file a different name.
|
|
|
|
</P>
|
|
<P>
|
|
Whatever the object file is called, <CODE>as</CODE> overwrites any
|
|
existing file of the same name.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC19" HREF="as_toc.html#TOC19">Join Data and Text Sections: <CODE>-R</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX72"></A>
|
|
<A NAME="IDX73"></A>
|
|
<A NAME="IDX74"></A>
|
|
<A NAME="IDX75"></A>
|
|
<A NAME="IDX76"></A>
|
|
<CODE>-R</CODE> tells <CODE>as</CODE> 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 <A HREF="as_4.html#SEC39">Sections and Relocation</A>.)
|
|
|
|
</P>
|
|
<P>
|
|
When you specify <CODE>-R</CODE> 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 <CODE>as</CODE>. In future, <CODE>-R</CODE> may work this way.
|
|
|
|
</P>
|
|
<P>
|
|
When <CODE>as</CODE> is configured for COFF output,
|
|
this option is only useful if you use sections named <SAMP>`.text'</SAMP> and
|
|
<SAMP>`.data'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE>-R</CODE> is not supported for any of the HPPA targets. Using
|
|
<CODE>-R</CODE> generates a warning from <CODE>as</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC20" HREF="as_toc.html#TOC20">Display Assembly Statistics: <CODE>--statistics</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX77"></A>
|
|
<A NAME="IDX78"></A>
|
|
<A NAME="IDX79"></A>
|
|
<A NAME="IDX80"></A>
|
|
Use <SAMP>`--statistics'</SAMP> to display two statistics about the resources used by
|
|
<CODE>as</CODE>: the maximum amount of space allocated during the assembly
|
|
(in bytes), and the total execution time taken for the assembly (in CPU
|
|
seconds).
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC21" HREF="as_toc.html#TOC21">Compatible output: <CODE>--traditional-format</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX81"></A>
|
|
For some targets, the output of <CODE>as</CODE> is different in some ways
|
|
from the output of some existing assembler. This switch requests
|
|
<CODE>as</CODE> to use the traditional format instead.
|
|
|
|
</P>
|
|
<P>
|
|
For example, it disables the exception frame optimizations which
|
|
<CODE>as</CODE> normally does by default on <CODE>gcc</CODE> output.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC22" HREF="as_toc.html#TOC22">Announce Version: <CODE>-v</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX82"></A>
|
|
<A NAME="IDX83"></A>
|
|
<A NAME="IDX84"></A>
|
|
<A NAME="IDX85"></A>
|
|
You can find out what version of as is running by including the
|
|
option <SAMP>`-v'</SAMP> (which you can also spell as <SAMP>`-version'</SAMP>) on the
|
|
command line.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC23" HREF="as_toc.html#TOC23">Suppress Warnings: <CODE>-W</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX86"></A>
|
|
<A NAME="IDX87"></A>
|
|
<A NAME="IDX88"></A>
|
|
<CODE>as</CODE> should never give a warning or error message when
|
|
assembling compiler output. But programs written by people often
|
|
cause <CODE>as</CODE> 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
|
|
<CODE>as</CODE> assembles your file. Errors, which stop the assembly, are
|
|
still reported.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC24" HREF="as_toc.html#TOC24">Generate Object File in Spite of Errors: <CODE>-Z</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX89"></A>
|
|
<A NAME="IDX90"></A>
|
|
After an error message, <CODE>as</CODE> normally produces no output. If for
|
|
some reason you are interested in object file output even after
|
|
<CODE>as</CODE> gives an error message on your program, use the <SAMP>`-Z'</SAMP>
|
|
option. If there are any errors, <CODE>as</CODE> continues anyways, and
|
|
writes an object file after a final warning message of the form <SAMP>`<VAR>n</VAR>
|
|
errors, <VAR>m</VAR> warnings, generating bad object file.'</SAMP>
|
|
|
|
</P>
|
|
<P><HR><P>
|
|
Go to the <A HREF="as_1.html">first</A>, <A HREF="as_1.html">previous</A>, <A HREF="as_3.html">next</A>, <A HREF="as_27.html">last</A> section, <A HREF="as_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|