Using the Assembler

This chapter describes how to run the as assembler, which produces an object file from one or more files of assembly language source code.

Command Syntax

To run the assembler, type the following command in a shell:

as [ option ] ... [ file ] ...

You can specify one or more command-line options. These assembler options are described in Assembler Options.

You can specify one or more files containing assembly language source code. If no files are specified, as uses the standard input (stdin) for the assembly source input.

Assembler Options

The following command-line options are recognized by the assembler:

-o

-o name

The name argument after -o is used as the name of the as output file, instead of a.out.

--

--

Use the standard input (stdin) for the assembly source input.

-f

-f

Fast; no need to run app (the assembler preprocessor). This option is intended for use by compilers that produce assembly code in a strict “clean” format that specifies exactly where whitespace can go. The app preprocessor needs to be run on handwritten assembly files and on files that have been preprocessed by cpp (the C preprocessor). This typically is needed when assembler files are assembled through the use of the cc(1) command, which automatically runs the C preprocessor on assembly source files. The assembler preprocessor strips out excess spaces, turns each character surrounded by single quotation marks into a decimal constant, and turns occurrences of:

# number filename level

into:

.line number;.file filename

The assembler preprocessor can also be turned off by starting the assembly file with #NO_APP\n. When the assembler preprocessor has been turned off in this way, it can be turned on and off with pairs of #APP\n and #NO_APP\n at the beginning of lines. This is used by the compiler to wrap assembly statements produced from asm() statements.

-g

-g

Produce debugging information for the symbolic debugger gdb(1) so the assembly source can be debugged symbolically. For include files (included by the C preprocessor’s #include or by the assembler directive .include) that produce instructions in the (__TEXT,__text) section, the include file must be included while a .text directive is in effect (that is, there must be a .text directive before the include) and end with the a .text directive in effect (at the end of the include file). Otherwise the debugger will have trouble dealing with that assembly file.

-v

-v

Print the version of the assembler (both the OS X version and the GNU version that it is based on).

-n

-n

Don’t assume that the assembly file starts with a .text directive.

-I

-Idir

Add dir to the list of directories to search for files included with the .include directive. The default place to search is the current directory.

-L

-L

Save defined labels beginning with an L (the compiler generates these temporary labels). Temporary labels are normally discarded to save space in the resulting symbol table.

-V

-V

Print the path and the command-line invocation of the assembler that the assembler driver is using.

-W

-W

Suppress warnings.

-dynamic

-dynamic

Enables dynamic linking features. This is the default.

-static

-static

Causes the assembler to treat any dynamic linking features as an error. This also causes the .text directive to not include the pure_instructions section attribute.

Architecture Options

The program /usr/bin/as is a driver that executes assemblers for specific target architectures. If no target architecture is specified, it defaults to the architecture of the host it is running on.

-arch

-arch arch_type

Specifies the target architecture, arch_type, the assembler to be executed and the architecture of the resulting object file. The target assemblers for each architecture are in /usr/libexec/gcc/darwin/arch_type/as or /usr/local/libexec/gcc/darwin/arch_type/as. The specified target architecture can be processor specific, in which case the resulting object file is marked for the specific processor. See then man page arch(3) for the current list of specific processor names for the -arch option.

-force_cpusubtype_ALL

-force_cpusubtype_ALL

Set the architecture of the resulting object file to the ALL type regardless of the instructions in the assembly input.

-arch_multiple

-arch_multiple

This is used by the cc(1) driver program when it is run with multiple -archarch_type flags and instructs programs like as(1) that, if it prints any messages, to precede them with one line stating the program name—in this case as—and the architecture (from the -archarch_type flag) to distinguish which architecture the error messages refer to. This flag is accepted only by the actual assemblers (in /lib/arch_type/as) and not by the assembler driver, /bin/as.

PowerPC-Specific Options

The following sections describe the options specific to the PowerPC architecture.

-no_ppc601

-no_ppc601

Treat any PowerPC 601 instructions as an error.

-static_branch_prediction_Y_bit

-static_branch_prediction_Y_bit

Treat a single trailing + or - after a conditional PowerPC branch instruction as a static branch prediction that sets the Y bit in the opcode. Pairs of trailing ++ or -- always set the AT bits. This is the default for OS X.

-static_branch_prediction_AT_bits

-static_branch_prediction_AT_bits

Treat a single trailing + or - after a conditional Power PC branch instruction as a static branch prediction sets the AT bits in the opcode. Pairs of trailing ++ or -- always set the AT bits, but with this option a warning is issued if that syntax is used. With this flag the assembler behaves like the IBM tools.