asl.1

万能汇编工具

.B -p

Instruct AS to write out the shared symbol definitions in a format suitable
for including into a Pascal or Modula-2 program.  The file's name is
constructed by replacing the source file's extension with '.inc'. See the
user manual for more information about symbol sharing.
.TP
.B -q or -quiet
Turn on silent assembly mode.  In silent compilation mode, AS will not
do any console output except for warning and error messages.
.TP
.B -r [pass number]
Tell AS to output warnings when a situation appears in a source file that
forces another pass of assembly.  Such situations either take place when a symbol
is undefined in the first pass or a symbol's value has changed compared to the 
previous pass.  This option is useful to track down sources of excessive
multi-passing, but be aware that it might yield a fairly large number of
warnings, especially in the first pass.  Optionally, a pass number may be added
to this option to inhibit output until a certain pass is reached.
.TP
.B -s

Add a section list to the assembly listing.  A section list contains
all sections that have been defined in the source files, marking their
nesting level by different levels of indentation.   This option only
makes sense when the generation of an assembly listing has been turned
on via the
.B -L
or
.B -l
parameters.
.TP
.B -t <mask>
Turn on or off parts of the assembly listing that have no individual
command line parameter.  AS internally keeps an integer value whose bits
represent certain components of the listing.  A positive command line
parameter (-t or /t) sets the bits set in <mask>, whereas a negated
parameter (+t) resets the bits set in <mask>.  The individual bits have
the following meaning: bit 0 = source lines and generated machine code,
bit 1 = symbol table, bit 2 = macro table, bit 3 = function table, bit 4 =
line numbering.
.TP
.B -u

Tell AS to do additional bookkeeping about which address ranges have been
used by the assembled program.  This option enables the detection of overlapping
memory usage.  If an assembly listing has been turned on via the
.B -L
or
.B -l
parameters, it will also contain a list of all used memory areas.
.TP
.B -U 

Force AS to operate in case-sensitive mode.  By default, names of symbols,
macros, user-defined functions and sections are treated in a case-insensitive
manner.
.TP
.B -w

Suppress output of warnings.
.TP
.B -x

Turn on extended error reporting.  With extended error reporting, several
error and warning messages will also print the item that created the message,
e.g. the name of an unknown instruction.  When this option is given twice, 
the erroneous source line is additinally printed.

.SH PRESETTING PARAMETERS

Parameters need not neccessarily be given in the command line itself.  Before
processing of command line parameters starts, AS will look if the
.B ASCMD
environment variable is defined.  If it exists, its contents will be
treated as additional command line parameters whose syntax is absolutely 
equal to normal command line parameters.  An exception is made if the 
variable's contents start with a '@' sign; in such a case, the string after
the '@' sign is treated as the name of a file that contains the options.
Such a file (also called a 'key file') has the advantage that it allows
the options to be written in different lines, and it does not have a size
limit.  Some operating systems (like MS-DOS) have a length limit on 
command lines and environment variable contents, so the key file may be
your only option if you have a lot of lengthy parameters for AS.

As parameters given in the
.B ASCMD
environment variable or a key file are processed prior to the command line
itself, and can therefore be overridden by command line parameters.

.SH NATIONAL LANGUAGE SUPPORT

AS supports the needs of different languages and countries in the sense that
it will try to adapt to the language and date/time formats valid for the
current environment.  Upon startup, the COUNTRY setting made in the
CONFIG.SYS file is queried for DOS and OS/2 implementations of AS.  For
UNIX systems, AS tries to read the LC_TIME resp. LC_MESSAGES environment
variables to find out the correct format for date/time outputs resp. the
local language.  If this fails, the LC_ALL and finally LANG variables are
probed.  If none of these environment variables points to a specific local
environment resp. contains a locale specification unknown to AS, the
standard english/C locale is used.

The messages AS can output in different languages are stored in separate
files with the extension '.msg' .  AS will search for these files in the
following directories:

- The current directory

- The directory the executable of AS was loaded from (only on DOS platforms version >=3.0 or if path was explicitly specified)

- The directory specified in the AS_MSGPATH environment variable resp. the directories listed in the PATH environment variable if AS_MSGPATH does not exist.

- The LIBDIR directory set at compile time from the Makefile.


.SH RETURN CODES

Depending on the assembly's turnout, 
.B asl
will generate different return codes:
.TP
.B 0
No errors, warnings might have occured.
.TP
.B 1
No command line parameters were given, AS printed a short list
of possible command line parameters and terminated thereafter.
.TP
.B 2
Errors occured during assembly of at least one source file, no 
code file was generated for the corresponding source file(s).
.TP
.B 3
A fatal error occured during assembly that forced immediate
program termination.  Code files may be generated, but are probably
unusuable.
.TP
.B 4
Program termination already occured during initialization.  This
might be either due to a incorrect command line parameter or an error
during loading the program's overlay file (only possible on MS-DOS).
.TP
.B 255
During initialization, an internal error happened that should not
occur.  If the reaction is reproducable, note down the situation and
send a bug report to the author.

.SH EXAMPLES

To assemble a source file
.B file1.asm
without any additional bells and whistles, use:
.PP
.B asl file1
.PP
which will create an output file
.B file1.p
given that there are no errors.  If you additionally want a listing and
rename the output file to
.B a.out,
use
.PP
.B asl -L file1 -o a.out
.PP
To make the listing as comprehensive as possible and to get more detailed
error messages, use:
.PP
.B asl -LuCIs -t 16 -nx file1

.SH TIPS

calling AS without any parameters will print a short help containing all
command line parameters and implemented target processors, while calling
with command line parameters but without any source file name will result
in AS asking for a source file name on the console.

.SH SEE ALSO

plist(1), pbind(1), p2hex(1), p2bin(1)

.SH HISTORY

AS originally appeared as a DOS program in 1989, written in
Borland-Pascal, and was ported to C and UNIX in 1996.  

.SH BUGS

There are too many options.

Command line interpreters of some operating systems reserve some 
characters for their own use, so it might be necessary to give
command line parameters with certain tricks (e.g., with the help
of escape characters).

.SH AUTHOR(S)

Alfred Arnold ([e-mail]), and a few others...