[Main]
Title=A68k Command-Line Parameters (How to use A68k)

[Top]
The command-line syntax to run the assembler is as follows:
<PRE>   a68k &lt;<I>source file name</I>&gt;
        [&lt;<I>object file name</I>&gt;]
        [&lt;<I>listing file name</I>&gt;]
<B>(TIGCC)</B> [-a]
        [-d[[!]&lt;<I>prefix</I>&gt;]]
        [-e[&lt;<I>equate file name</I>&gt;]]
        [-f]
        [-g]
        [-h&lt;<I>header file name</I>&gt;]
        [-i&lt;<I>include directory list</I>&gt;]
        [-k]
        [-l[&lt;<I>listing file name</I>&gt;]]
        [-m&lt;<I>small data offset</I>&gt;]
        [-n]
        [-o&lt;<I>object file name</I>&gt;]
        [-p&lt;<I>page depth</I>&gt;]
        [-q[&lt;<I>quiet interval</I>&gt;]]
<B>(TIGCC)</B> [-r[a][l][m]]
        [-s]
        [-t]
<B>(TIGCC)</B> [-u]
<B>(TIGCC)</B> [-v&lt;<I>name</I>&gt;[,&lt;<I>value</I>&gt;]
        [-w[&lt;<I>hash table size</I>&gt;][,&lt;<I>secondary heap size</I>&gt;]]
        [-x[&lt;<I>listing file name</I>&gt;]]
        [-y]
        [-z[&lt;<I>debug start line</I>&gt;][,&lt;<I>debug end line</I>&gt;]]
</PRE>

These options can be given in any order.  Any parameter which is not
a switch (denoted by a leading hyphen) is assumed to be a file name;
up to three file names (assumed to be source, object, and listing file
names respectively) can be given.  A source file name is always required.
If a switch is being given a value, that value must immediately follow
the switch letter with no intervening spaces.  For instance, to specify
a page depth of 40 lines, the specification <B>'-p40'</B> should be used;
<B>'-p&nbsp;40'</B> will be rejected.
<BR><BR>
Switches perform the following actions:
<DL>
<DT><B>-a</B>
<DD>
Causes all relocs to be emitted, even PC-relative relocs
within a section. It also emits address differences in a
special TIGCC-specific format. This will allow more
aggressive linker-side optimization.
<BR><BR><DT><B>-d</B>
<DD>
Causes symbol table entries (hunk_symbol) to be written
to the object module for the use of symbolic debuggers.
If the switch is followed by a string of characters, only
those symbols beginning with that prefix string will be
written.  This can be used to suppress internal symbols
generated by compilers.  If the first character is an
exclamation mark (<CODE>'!'</CODE>), only symbols which do <B>not</B> begin
with the following characters are written out. Here are some examples:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-d</CODE></TD><TD CLASS="NOBORDER">writes all symbols</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-dabc&nbsp;&nbsp;&nbsp;</CODE></TD><TD CLASS="NOBORDER">writes only symbols beginning with "abc"</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-d!x</CODE></TD><TD CLASS="NOBORDER">writes symbols which do not begin with "x"</TD></TR>
</TABLE>
<BR><DT><B>-e</B>
<DD>
Causes an equate file (see above) to be produced.  A file
name can be specified; otherwise a default name will be used.
<BR><BR><DT><B>-f</B>
<DD>
Causes any branches (<CODE>B<I>cc</I></CODE>, <CODE>BRA</CODE>, <CODE>BSR</CODE>) that could be converted
to short form to be flagged.  <CODE>A68k</CODE> will convert as many
branches as possible to short form (unless the <B>'-n'</B> switch is
is specified), but certain combinations of instructions may
set up a ripple effect where shortening one branch brings
another one into range.  This switch will cause <CODE>A68k</CODE> to
flag any branches that it may have missed; during pass 2
it is possible to tell this, although during pass 1 it might
not be.  If the <B>'-n'</B> switch (see below) is specified along
with this switch (suppressing all optimization), no branches
will be shortened, but all branches which could be shortened
will be flagged.
<BR><BR><DT><B>-g</B>
<DD>
Causes any undefined symbols to be treated as if they were
externally defined (<CODE>XREF</CODE>), rather than being flagged as errors.
<BR><BR><DT><B>-h</B>
<DD>
Causes a header file to be read prior to the source code file.
A file name must be given.  The action is the same as if the
first statement of the source file were an <CODE>INCLUDE</CODE> statement
naming the header file.  To find the header file, the same
directories will be searched as for <CODE>INCLUDE</CODE> files (see the
<B>'-i'</B> switch below).
<BR><BR><DT><B>-i</B>
<DD>
Specifies directories to be searched for <CODE>INCLUDE</CODE> files in
addition to the current directory.  Several names, separated
by commas, may be specified.  No embedded blanks are allowed.
For example, the specification
<PRE>-imylib,df1:another.lib
</PRE>
will cause <CODE>INCLUDE</CODE> files to be searched for first in the
current directory, then in "mylib", then in "df1:another.lib".
<BR><BR><DT><B>-k</B>
<DD>
Causes the object file to be kept even if any errors were
found.  Otherwise, it will be scratched if any errors occur.
<BR><BR><DT><B>-l</B>
<DD>
Causes a listing file to be produced.  If you want the listing
file to include a symbol table dump and cross-reference, use
the <B>'-x'</B> switch instead (see below).
<BR><BR><DT><B>-m</B>
<DD>
Changes the assumed offset from the start of the <CODE>DATA</CODE>/<CODE>BSS</CODE>
section to the base register used when the small code/data
option is activated by the <CODE>NEAR</CODE> directive.
If this parameter is not specified, the offset defaults
to 32768.
<BR><BR><DT><B>-n</B>
<DD>
Causes all object code optimization (see above) to be disabled.
<BR><BR><DT><B>-o</B>
<DD>
Allows the default name for the object code file (see above)
to be overridden.
<BR><BR><DT><B>-p</B>
<DD>
Causes the page depth to be set to the specified value.
This takes the place of the <CODE>PLEN</CODE> directive in the Metacomco
assembler.  Page depth defaults to 60 lines (<B>'-p60'</B>).
<BR><BR><DT><B>-q</B>
<DD>
Changes the interval at which <CODE>A68k</CODE> displays the line number
it has reached in its progress through the assembly.  The
default is to display every 100 lines (<B>'-q100'</B>).  Specifying
larger values reduces console I/O, making assemblies run
slightly faster.
<BR><BR>
If you specify a negative number (e.g.  <B>'-q-10'</B>), line numbers
will be displayed at an interval equal to the absolute value
of the specified number, but will be given as positions
within the current module (source, macro, or <CODE>INCLUDE</CODE>) rather
than as a total statement count - the module name will also
be displayed.
<BR><BR>
A special case is the value zero (<B>'-q0'</B> or just <B>'-q'</B>) - this
will cause all console output, except for error messages,
to be suppressed.
<BR><BR><DT><B>(TIGCC)</B> <B>-r</B>
<DD>
Allows to disable specific optimizations:<BR>
<B>-rm</B> Disable the <CODE>MOVEM</CODE> -> <CODE>MOVE</CODE> optimization<BR>
<B>-ra</B> Disable the <CODE>ADD(A)/SUB(A)</CODE> -> <CODE>LEA</CODE> optimization<BR>
<B>-rl</B> Disable the <CODE>LEA</CODE> -> <CODE>ADDQ/SUBQ</CODE> optimization<BR>
You might use more than one <B>-r</B> switch (as in "<B>-rm -ra</B>") or combine them into a single switch (as in "<B>-rma</B>").
<BR><BR><DT><B>-s</B>
<DD>
Causes the object file to be written in Motorola S-record
format, rather than AmigaDOS format.  The default name for
an S-record file ends with <CODE>'.s'</CODE> rather than <CODE>'.o</CODE>; this can
still be overridden with the <B>'-o'</B> switch, though.
<BR><BR><DT><B>-t</B>
<DD>
Allows tabs in the source file to be passed through to the
listing file, rather than being expanded.  In addition, tabs
will be generated in the listing file to skip from the object
code to the source statement, etc.  This can greatly reduce
the size of the listing file, as well as making it quicker to
produce.  Do not use this option if you will be displaying or
listing the list file on a device which does not assume a tab
stop at every 8th position.
<BR><BR><DT><B>(TIGCC)</B> <B>-u</B>
<DD>
Disables automatic alignment of <CODE>DC.W</CODE>,
<CODE>DC.L</CODE>, <CODE>DCB.W</CODE>, <CODE>DCB.L</CODE>,
<CODE>DS.W</CODE>, <CODE>DS.L</CODE> and code.
<BR><BR><DT><B>(TIGCC)</B> <B>-v</B>
<DD>
Allows to set a variable in the command line (like <B>-d</B> with
<CODE>GCC</CODE>). The variable will be a <CODE>SET</CODE>, not <CODE>EQU</CODE> variable. Syntax:
"<B>-v</B>&lt;<I>name</I>&gt;[,&lt;<I>value</I>&gt;]" (without spaces, and without the
quotes). Note that &lt;<I>value</I>&gt; can only be a <B>NUMBER</B> at the
moment. (We might support symbols as values in a future
version.) The default value of &lt;<I>value</I>&gt; is 1.
<BR><BR><DT><B>-w</B>
<DD>
Specifies the sizes of fixed memory areas that <CODE>A68k</CODE> allocates
for its own use.  You should normally never have to specify
this switch, but it may be useful for tuning.
<BR><BR>
The first parameter gives the number of entries that the hash
table (used for searching the symbol table) will contain.
The default value of 2047 should be enough for all but the
very largest programs.  The assembly will not fail if this
value is too small, but may slow down if too many long hash
chains must be searched.  The hashing statistics displayed by
the <B>'-y'</B> switch (see below) can be used to tune this parameter.
I've heard that you should really specify a prime number for
this parameter, but I haven't gone into hashing theory enough
to know whether it's actually necessary.
<BR><BR>
The second parameter of the <B>'-w'</B> switch specifies the size (in
bytes) of the secondary heap, which is used to store nested
macro and <CODE>INCLUDE</CODE> file information (see below).  It defaults
to 1024, which should be enough unless you use very deeply
nested macros and/or <CODE>INCLUDE</CODE> files with long path names.
<BR><BR>
<TABLE><TR><TD><B>(TIGCC)</B></TD><TD>
The default sizes are 4095,2048 in the Win32 (since
v.2.71.F3a) and GNU/Linux (since v.2.71.F3c) versions.</TD></TR></TABLE>
<BR><BR>
You can specify either or both parameters.  For example:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-w4093</CODE></TD><TD CLASS="NOBORDER">secondary heap size remains at 1024 bytes</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-w,2000</CODE></TD><TD CLASS="NOBORDER">hash table size remains at 2047 entries</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-w4093,2000&nbsp;&nbsp;&nbsp;</CODE></TD><TD CLASS="NOBORDER">increases the size of both areas</TD></TR>
</TABLE>
<BR>
If you're really tight for memory, and are assembling small
modules, you can use this switch to shrink these areas below
their default sizes.  At the end of an assembly, a message
will be displayed giving the sizes actually used, in the form
of the <B>'-w'</B> command you would have to enter to allocate that much
space.  This is primarily useful to see how much secondary
heap space was used.
<BR><BR>
<B>Note:</B> All other memory used by <CODE>A68k</CODE> (e.g. the actual symbol
table) is allocated as required (currently in 8K chunks).
<BR><BR><DT><B>-x</B>
<DD>
Works the same as <B>'-l'</B> (see above), except that a symbol table
dump, including cross-reference information, will be added
to the end of the listing file.
<BR><BR><DT><B>-y</B>
<DD>
Causes hashing statistics to be displayed at the end of the
assembly.  First the number of symbols in the table is given,
followed by a summary of hash chains by length.  Chains with
length zero denote unused hash table entries.  Ideally (i.e.
if there were no collisions) there should be as many chains
with length 1 as there are symbols, and there should be no
chains of length 2 or greater.  I added this option to help
me tune my hashing algorithm, but you can also use it to see
whether you should allocate a larger hash table (using the
first parameter of the <B>'-w'</B> switch, see above).
<BR><BR><DT><B>-z</B>
<DD>
This switch was provided to help debug <CODE>A68k</CODE> itself.  It causes <CODE>A68k</CODE> to
list a range of source lines, complete with line number and
current location counter value, during both passes.  Lines
are listed immediately after they have been read from the
source file, before any processing occurs. Here are some examples of the <B>'-z'</B> switch:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-z</CODE></TD><TD CLASS="NOBORDER">lists all source lines</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z100,200&nbsp;&nbsp;&nbsp;</CODE></TD><TD CLASS="NOBORDER">lists lines 100 through 200</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z100</CODE></TD><TD CLASS="NOBORDER">lists all lines starting at 100</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z,100</CODE></TD><TD CLASS="NOBORDER">lists the first 100 lines</TD></TR>
</TABLE>
</DL>
