Tools: MPW
Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Support

MPW Command Reference


Asm

Tool

SYNTAX

Asm [file1] [file2]… [-addrsize size] [-blksize blocks] [-c[heck]]
[-case on | obj[ect] | off] [-d[efine] name[=value] |
&name[=[value]][,name[=value] | &name[=[value]]…]]
[-e[rrlog] errLogFile] [-f] [-font fontName | fontName,fontSize |
,fontSize] [-h] [-i pathname[,pathname]…] [-l] [-lo listingName]
[-model near | far | cfmseg] [-o objName] [-p]
[-pagesize l | l,w | ,w] [-print mode[,mode]…] [-s]
[-sym on | full | off] [-t] [-w] [-wb]

DESCRIPTION

Assembler for the classic 68K and CFM-68K runtime architectures.

The Asm tool assembles one or more text files. By convention, assembly-language source filenames end with the ".a" suffix. Once assembled, each file of the form file.a yields an object file of the form file.a.o. In the same way, if you choose not to use the ".a" convention, a source file of the form file, when assembled, yields an object file of the form file.o. The assembler creates this object file in the same directory as the source file.

In addition to assembling programs under the default behavior, Asm allows you to

check for errors in the source instead of producing an object file (-c)

produce a listing of the source (-s or -l). A listing file can be generated regardless of whether an object file is created

generate symbolic debugging information (-sym on | full | off)

INPUT

If you do not specify any filenames, Asm assembles standard input. You can terminate input by pressing Command-Enter or entering an END directive preceded by a blank space. If you use the latter method, the assembler requires a new line immediately following the END directive.

The assembler can also take input from "dump" files when a LOAD directive is used in the source.

OUTPUT

The assembler produces an object file for each source file specified as input. Normally, each object file is written to the same directory as the source file and is given a filename created by adding the suffix .o to the name of the source file. You can use the -o option to override the output directory or the name of the object file. If you assemble standard input instead of source files, the assembler creates an object file of the name a.o in the current directory.

If you specify either -s or -l, the assembler creates a listing file for each source file. Unless you specify a different directory or filename (-lo listingName), each listing file is written to the same directory as the source file and is given a filename created by adding the suffix ".lst" to the source filename. If you assemble standard input instead of source files, the assembler writes the listing to standard output.

The assembler can also produce a dump file when given the assembler directive DUMP.

Note
Under certain conditions the assembler creates working files that are deleted if the assembler terminates normally. If assembly does not terminate normally, these files may remain. For example, when a listing file is requested, the assembler creates a temporary working file called #AsmWorkFile#. If the expression evaluation stack gets too large to be held in memory, it is written to a file named #AsmSpillFile# in the same directory as the source file. •

The assembler normally writes error and warning messages to standard output. You can create an error log file by specifying a filename parameter to the -e option. This file is created only if errors are detected; warnings alone are not sufficient to cause the assembler to create this file, although warnings are included in its content. If you do not specify a full pathname, Asm creates the error file in the current directory.

Error messages have this format:

### message
File "filename"; Line linenumber

This format allows you to go directly to the source of the error by selecting and executing the text after the three pound signs (###). File and Line are defined as MPW Shell commands: File, which is defined in the Startup file as an alias for Target, makes the file filename open as the target window, and Line finds the line number on which the error was detected.

Note
If an I/O error occurs during assembly, the assembler reads from the MPW file SysErrs.err. If an error message appears stating that the error message file was not found, it means that the assembler was unable to find this file. •

STATUS

Asm can return the following status codes:

0

no errors detected in any of the files assembled

1

parameter or option errors

2

syntax errors

3

execution aborted by assembler

PARAMETERS

file1 [file2]…

Specifies one or more assembly-language source files to be assembled.

OPTIONS

If you specify redundant or conflicting options, the assembler does not issue an error or warning message but simply uses the last option specified. Options can appear in any order, except for -case on, which must be placed before any -define options if you wish to preserve the case of the specified identifiers.

Some options have equivalent directives that can be placed in the source file. Where there is such a directive, an explanation of the directive is provided with the option.

-addrsize size

Sets the size in digits of address displays in the listing, where size is a number between 4 and 8. The default number of digits is 5.

-blksize blocks

Specifies the number of 512 byte blocks in the assembler's text file I/O buffer. The parameter blocks is a number between 6 and 62.

If you omit this option, the assembler sets the size of blocks based on whether there is enough memory space or not. If it determines that there is enough memory space, it sets the value of blocks to 16 (8192 bytes); otherwise it sets it to 6 (3072 bytes).

This option permits optimization of I/O performance (for example, transfer rate for text file input, load/dump files, and listing output) as a function of the disk device being used. However, note that increasing the value of blocks reduces the amount of memory available for other assembly-language structures, such as symbol tables.

-c[heck]

Checks syntax only, without generating an object file.

-case on | obj[ect] | off

Sets the case mode of the Asm command. This option does not override an explicit CASE directive in the source.

on

Distinguishes between uppercase and lowercase letters in nonmacro names. This option is the same as the CASE ON assembly-language directive, which also forces the assembler to distinguish between uppercase and lowercase letters. The assembler always ignores case in macro names.

Note
To preserve the case of names declared by using -define, -case on must precede -define on the command line. •

obj[ect]

Preserves the case of module, EXPORT, IMPORT, and ENTRY names only in the generated object file. In all other instances the assembler ignores case, and its behavior is the same as with the preset CASE OFF directive, which forces the assembler to treat uppercase and lowercase letters the same.

off

Ignores the case of letters in all identifiers (the default). You can use this option on the command line to reverse the effect of one of the other case modes. For example, if you turn case on before a -define option to preserve the case of the identifiers that you specify, you can turn it off again after -define on the command line with -case off.

-d[efine] name[=value] | &name[=[value]][,name[=value] | &name[=[value]]…]

Defines the identifier name as having the specified value. You can use either or both of these syntax forms in a single -d[efine] option depending on the types of identifiers being defined.

The first form (name[=value]) can be used for nonmacro identifiers, and the second (&name[=[value]]) for macro identifiers.

name

Specifies the identifier, whether nonmacro or macro, that Asm defines.

To preserve the case of names that you specify, precede -define on the command line with the -case on option. You can turn case off again after -define if you wish with the -case off option.

value

Specifies the value of the identifier. When defining a nonmacro identifier, only a decimal integer can be specified as the value. In this case, omitting value causes name to have a default value of 1.

When defining a macro identifier, either a decimal integer or a string constant can be used for the value. Omitting =value causes Asm to assume the default value 1. Omitting just value causes value to default to the null string.

This option is equivalent to placing the directive

name EQU value

at the beginning of the source file or, in the case of macro identifiers, to declaring the name a global arithmetic symbol (GBLA for an integer value) or global character macro symbol (GBLC for a string value) and placing one of the following directives at the beginning of the source file:

       GBLA &name
&name SETA value

or

       GBLC &name
&name SETC value

To test whether name is defined, use the function &Type.

You can define more than one name by specifying multiple -d options or multiple name[=value] or name[=[value]] parameters separated by commas. See the Examples for a sample command line.

-e[rrlog] errLogFile

Writes all errors and warnings to the specified error log file. If Asm generates only warnings, no error file is created. This option is the same as the ERRLOG 'errLogFile' directive, which also creates a log file containing the error messages and warnings generated during assembly.

-f

Suppresses page ejects. This is the same as the PRINT NOPAGE directive, which suppresses page ejects in the assembly listing.

-font fontName | fontName,fontSize | ,fontSize

Sets the listing file's font name and size. To use this option, you must also generate a listing file by specifying either -s or -l.

fontName

Specifies the listing file's font. Normally Asm writes the listing file in Monaco. Note that you must use a monospaced font to ensure correct formatting of the listing file.

fontSize

Specifies the numeric font size. The default font size is 7.

-h

Suppresses page headers. This option is the same as PRINT NOHDR, which suppresses header lines in the assembly listing.

-i pathname[,pathname]…

Directs Asm to search additional directories for include and load files. The maximum number of directories you can specify with this option (or with the {AIncludes} variable) is 15. If the number of directories exceeds this, the assembler returns an error rather than searching.

If the include file in the source code indicates a full pathname, Asm searches for the file at that location. If the include file indicates a partial pathname, the assembler automatically searches the additional directories in this order:

1. The current directory.
2. The directory containing the current input file.
3. The directories specified as -i parameters, in the order given.
4. The directories specified in the MPW Shell variable {AIncludes}.

In addition to specifying more than one pathname parameter, you can use this option more than once on a command line to specify additional directories to search.

-l

Generates a full listing of the source. This option generates a text file containing a representation of the generated object code next to each assembly source line. The listing is generated in the same directory as the source file.

If you use standard input for the source code, Asm writes the listing to standard output. Otherwise Asm writes the listing to file.a.lst (where file.a is the source filename).

-lo listingName

Specifies a different filename or directory for the listing file. If listingName does not end with a colon, the assembler writes the listing to the file listingName in the current directory. Listings for multiple source files, which would otherwise be placed in separate listing files, are appended to this listing file. The listing scratch file also appears in the current directory.

If listingName ends with a colon, the assembler writes the listing in file.a.lst (where file.a is the source filename) as usual but places this file in the directory listingName. The listing scratch file also appears in this directory.

You must specify either -l or -s to use this option; however, the options need not appear in any particular order.

-model near | far | cfmseg

Determines whether the assembler uses references to 32-bit addresses for MPW's "32-bit everything." The far option removes the 32 KB (16 bit) restriction on the size of code segments. Note that this does not affect the size of data segments. Data segments can be greater than 32 KB for both near and far.

near

Assembles normally with 16-bit references (the default). Under -model near, the assembler generates code references as 16-bit offsets from the A5 or the PC registers, as appropriate.

far

Generates 32-bit load-time relocatable references. If you specify -model far, the assembler generates 32-bit load-time relocatable references for imported code references that use the syntax (xxxx).L for the absolute long addressing mode. All other syntactically correct references are generated as described for -model near.

cfmseg

Generates a CFM-68K runtime compatible object file.

-o objName

Specifies a different filename or directory for the generated object file. If objName does not end with a colon, the assembler writes the object file to the file objName. In this case, you can assemble only one source file at a time.

If objName ends with a colon, the assembler writes the object file in file.a.o as usual (where file.a is the source filename) but places this file in the directory objName. In this case, you can assemble more than one source file at a time.

-p

Writes progress and summary information (including modules, includes, loads, dumps, number of errors and warnings, and compilation time) to diagnostic output. This option is the same as the PRINT STAT directive, which lists each module identifier to diagnostic output as it is encountered in the source.

-pagesize l | l,w | ,w

Sets the listing page size. The default settings assume you are using the MPW Print command with the Monaco 7 font and printing on a LaserWriter. You must specify either -l or -s to use this option; however, the options need not be specified in any particular order.

l

Specifies the length of the listing page in lines, where l is any integer greater than or equal to 30. The default page length is 75 lines.

w

Specifies the width of the listing page in characters, where w is any integer between 70 and 160. The default page width is 126 characters.

-print mode[,mode]…

Sets the printing mode for listings. You can specify multiple print options or one or more of the following PRINT directive options for the mode parameters.

[NO]DATA

[show only the first line] or show up to 90 bytes

[NO]GEN

[no] macro expansions

[NO]HDR

[no] page headings

[NO]LITS

[no] literals

[NO]MCALL

[no] macro calls

[NO]MDIR

[no] macro directives

[NO]OBJ

[no] object code

[NO]PAGE

[no] page ejects

[NO]STAT

[no] progress information

[NO]SYM

[no] symbol table display

[NO]WARN

[no] warnings

Note that Asm provides the alternative of single-letter options for some of the settings: -f (NOPAGE), -h (NOHDR), -p (STAT), and -w (NOWARN). Additionally, generating a listing with -s automatically sets the print mode to NOOBJ, while generating a listing with -l sets it to OBJ.

Note
Specifying a print mode does not automatically generate a listing; you must also specify either -l or -s. •

-s

Generates a shortened form of the listing file. This option sets the print mode to be the same as the NOOBJ directive, which suppresses object code in the listing. The listing is generated in the same directory as the source file.

If standard input is used for the source code, Asm writes the listing to standard output. Otherwise, Asm writes the listing to file.a.lst. If you also specify -l, the rightmost option takes precedence.

-sym on | full | off

Determines whether the assembler generates symbolic debugging information.

on | full

Generates complete object file records containing symbolic debugger information. The parameters on and full are equivalent.

The symbolic information generated by the assembler consists of

Module Begin (entry) OMF records for identifiers defined by the PROC, FUNC, and MAIN directives

Local Identifier OMF records for all EQU and SET identifiers except for those identifiers defined in the files included from the {AIncludes} folder

Local Label OMF records for the local code labels

off

Does not generate object file records containing symbolic debugging information.

-t

Writes assembly time and number of lines to diagnostic output even if you do not specify progress (-p) information.

-w

Suppresses warning messages. This option is the same as PRINT NOWARN, which suppresses the display and counting of warning messages in the assembly listing.

-wb

Suppresses branch warning messages only.

EXAMPLES

The following command line assembles the Sample.a and MemorySrc.a source files, producing object files Sample.a.o and MemorySrc.a.o. The assembler suppresses all warnings and generates two listing files: Sample.a.lst and MemorySrc.a.lst. Specifying -l instead of -s generates a listing with object code displayed.

Asm Sample.a MemorySrc.a -w -l

You can use two syntax forms for -d[efine] parameters. The following command line uses both, defining the nonmacro identifier debug1 as having the default value 1 and the macro identifier debug as having the string value "on."

Asm MemorySrc.a -d debug1,&debug="'on'"

Note
The Sample.a and MemorySrc.a source files are located in the AExamples: folder. •

SEE ALSO

PPCAsm

 
 


Last Updated July 2000