as

AS(1)                        General Commands Manual                       AS(1)



NAME
       as - Mac OS X Mach-O GNU-based assemblers

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

DESCRIPTION
       The as command translates assembly code in the named files to object
       code.  If no files are specified, as reads from stdin.  All undefined
       symbols in the assembly are treated as global.  The output of the
       assembly is left in the file a.out by default.

       The program /usr/bin/as is actually 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.

OPTIONS
       -o name
              Name the output file name instead of a.out.

       -arch arch_type
              Specifies the target architecture, arch_type, of the assembler to
              be executed.  The target assemblers for each architecture are in
              /usr/libexec/gcc/darwin/arch_type/as or
              /usr/local/libexec/gcc/darwin/arch_type/as.  There is only one
              assembler for an architecture family.  If the specified target
              architecture is a machine-specific implementation, the assembler
              for that architecture family is executed (e.g.,
              /usr/libexec/gcc/darwin/ppc/as for -arch ppc604e).  See arch(3)
              for the currently known arch_types.

       -arch_multiple
              Precede any displayed messages with a line stating the program
              name (as) and the architecture (from the -arch arch_type flag), to
              distinguish which architecture the error messages refer to.  When
              the cc(1) driver program is run with multiple -arch flags, it
              invokes as with the -arch_multiple option.

       -force_cpusubtype_ALL
              By default, the assembler will produce the CPU subtype ALL for the
              object file it is assembling if it finds no implementation-
              specific instructions.  Also by default, the assembler will allow
              implementation-specific instructions and will combine the CPU
              subtype for those specific implementations.  The combining of
              specific implementations is architecture-dependent; if some
              combination of instructions is not allowed, an error is generated.
              With the optional -force_cpusubtype_ALL flag, all instructions are
              allowed and the object file's CPU subtype will be the ALL subtype.
              If the target architecture specified is a machine-specific
              implementation (e.g., -arch ppc603, -arch i486), the assembler
              will flag as errors instructions that are not supported on that
              architecture, and it will produce an object file with the CPU
              subtype for that specific implementation (even if no
              implementation-specific instructions are used).  The
              -force_cpusubtype_ALL flag is the default for all x86 and x86_64
              architectures.

       -dynamic
              Enables dynamic linking features.  This is the default.

       -static
              Causes the assembler to treat as an error any features for dynamic
              linking.  Also causes the .text directive to not include the
              pure_instructions section attribute.

       --     Use stdin for the assembly source input.

       -n     Instructs the assembler not to assume that the assembly file
              starts with a .text directive.  Use this option when an output
              file is not to contain a (__TEXT,__text) section or this section
              is not to be first one in the output file.

       -f     Fast; no need for the assembler preprocessor (``app'').  The
              assembler preprocessor can also be turned off by starting the
              assembly file with "#NO_APP\n".  This is intended for use by
              compilers which produce assembly code in a strict "clean" format
              that specifies exactly where whitespace can go.  The assembler
              preprocessor needs to be run on hand-written assembly files and/or
              files that have been preprocessed by the C preprocessor cpp.  This
              is typically 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 single-quoted characters into a
              decimal constants, and turns # <number> <filename> <level> into
              .line <number>;.file <filename>  pairs.  When the assembler
              preprocessor has been turned off by a "#NO_APP\n" at the start of
              a file, it can be turned back on and off again with pairs of
              "#APP\n" and "#NO_APP\n" at the beginnings of lines.  This is used
              by the compiler to wrap assembly statements produced from asm()
              statements.

       -g     Produce debugging information for the symbolic debugger gdb(1) so
              that the assembly source can be debugged symbolically.  The
              debugger depends on correct use of the C preprocessor's #include
              directive or the assembler's .include directive:  Any include file
              that produces instructions in the (__TEXT,__text) section must be
              included while a .text directive is in effect.  In other words,
              there must be a .text directive before the include, and the .text
              directive must still be in effect at the end of the include file.
              Otherwise, the debugger will get confused when in that assembly
              file.

       -v     Display the version of the assembler (both the Mac OS X version
              and the GNU version it is based on).

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

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

       -W     Suppress warnings.

       -L     Save non-global defined labels beginning with an 'L'; these labels
              are normally discarded to save space in the resultant symbol
              table.  The compiler generates such temporary labels.

       -q     Use the clang(1) integrated assembler instead of the GNU based
              system assembler.  This is the default for the x86 and arm
              architectures.

       -Q     Use the GNU based system assembler. Note that Apple's built-in
              system assemblers are deprecated; programs that rely on these
              asssemblers should move to the clang(1) integrated assembler
              instead, using the -q flag.

Assembler options for the PowerPC processors
       -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 Mac OS X.

       -static_branch_prediction_AT_bits
              Treat a single trailing '+' or '-' after a conditional PowerPC
              branch instruction as a static branch prediction that 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 this syntax is
              used.  With this flag the assembler behaves like the IBM tools.

       -no_ppc601
              Treat any PowerPC 601 instructions as an error.

FILES
       a.out     output file

SEE ALSO
       cc(1), ld(1), nm(1), otool(1), arch(3), Mach-O(5)



Apple Inc.                        June 23, 2020                            AS(1)