contrib/binutils/gas/doc/as.1

   1 .\" Copyright (c) 1991, 1992, 1996, 1997, 1998 Free Software Foundation
   2 .\" See section COPYING for conditions for redistribution
   3 .\" $FreeBSD$
   4 .TH as 1 "29 March 1996" "cygnus support" "GNU Development Tools"
   5
   6 .SH NAME
   7 GNU as \- the portable GNU assembler.
   8
   9 .SH SYNOPSIS
  10 .na
  11 .B as
  12 .RB "[\|" \-a "[\|" dhlns "\|]" \c
  13 \&[\|\=\c
  14 .I file\c
  15 \&\|]\|]
  16 .RB "[\|" \-D "\|]"
  17 .RB "[\|" \-\-defsym\ SYM=VAL "\|]"
  18 .RB "[\|" \-f "\|]"
  19 .RB "[\|" \-\-gstabs "\|]"
  20 .RB "[\|" \-I
  21 .I path\c
  22 \&\|]
  23 .RB "[\|" \-K "\|]"
  24 .RB "[\|" \-L "\|]"
  25 .RB "[\|" \-M\ |\ \-\-mri "\|]"
  26 .RB "[\|" \-o
  27 .I objfile\c
  28 \&\|]
  29 .RB "[\|" \-R "\|]"
  30 .RB "[\|" \-\-traditional\-format "\|]"
  31 .RB "[\|" \-v "\|]"
  32 .RB "[\|" \-w "\|]"
  33 .RB "[\|" \-\^\- "\ |\ " \c
  34 .I files\c
  35 \&\|.\|.\|.\|]
  36
  37 .I i960-only options:
  38 .br
  39 .RB "[\|" \-ACA "\||\|" \-ACA_A "\||\|" \-ACB\c
  40 .RB "\||\|" \-ACC "\||\|" \-AKA "\||\|" \-AKB\c
  41 .RB "\||\|" \-AKC "\||\|" \-AMC "\|]"
  42 .RB "[\|" \-b "\|]"
  43 .RB "[\|" \-no-relax "\|]"
  44
  45 .I m680x0-only options:
  46 .br
  47 .RB "[\|" \-l "\|]"
  48 .RB "[\|" \-mc68000 "\||\|" \-mc68010 "\||\|" \-mc68020 "\|]"
  49 .ad b
  50
  51 .SH DESCRIPTION
  52 GNU \c
  53 .B as\c
  54 \& is really a family of assemblers.
  55 If you use (or have used) the GNU assembler on one architecture, you
  56 should find a fairly similar environment when you use it on another
  57 architecture.  Each version has much in common with the others,
  58 including object file formats, most assembler directives (often called
  59 \c
  60 .I pseudo-ops)\c
  61 \& and assembler syntax.
  62
  63 For information on the syntax and pseudo-ops used by GNU \c
  64 .B as\c
  65 \&, see `\|\c
  66 .B as\c
  67 \|' entry in \c
  68 .B info \c
  69 (or the manual \c
  70 .I
  71 .I
  72 Using as: The GNU Assembler\c
  73 \&).
  74
  75 \c
  76 .B as\c
  77 \& is primarily intended to assemble the output of the GNU C
  78 compiler \c
  79 .B gcc\c
  80 \& for use by the linker \c
  81 .B ld\c
  82 \&.  Nevertheless,
  83 we've tried to make \c
  84 .B as\c
  85 \& assemble correctly everything that the native
  86 assembler would.
  87 This doesn't mean \c
  88 .B as\c
  89 \& always uses the same syntax as another
  90 assembler for the same architecture; for example, we know of several
  91 incompatible versions of 680x0 assembly language syntax.
  92
  93 Each time you run \c
  94 .B as\c
  95 \& it assembles exactly one source
  96 program.  The source program is made up of one or more files.
  97 (The standard input is also a file.)
  98
  99 If \c
 100 .B as\c
 101 \& is given no file names it attempts to read one input file
 102 from the \c
 103 .B as\c
 104 \& standard input, which is normally your terminal.  You
 105 may have to type \c
 106 .B ctl-D\c
 107 \& to tell \c
 108 .B as\c
 109 \& there is no more program
 110 to assemble.  Use `\|\c
 111 .B \-\^\-\c
 112 \|' if you need to explicitly name the standard input file
 113 in your command line.
 114
 115 .B as\c
 116 \& may write warnings and error messages to the standard error
 117 file (usually your terminal).  This should not happen when \c
 118 .B as\c
 119 \& is
 120 run automatically by a compiler.  Warnings report an assumption made so
 121 that \c
 122 .B as\c
 123 \& could keep assembling a flawed program; errors report a
 124 grave problem that stops the assembly.
 125
 126 .SH OPTIONS
 127 .TP
 128 .BR \-a
 129 Turn on assembly listings.  There are various suboptions.
 130 .B d
 131 omits debugging directives.
 132 .B h
 133 includes the high level source code; this is only available if the
 134 source file can be found, and the code was compiled with
 135 .B \-g.
 136 .B l
 137 includes an assembly listing.
 138 .B n
 139 omits forms processing.
 140 .B s
 141 includes a symbol listing.
 142 .B =
 143 .I file
 144 sets the listing file name; this must be the last suboption.
 145 The default suboptions are
 146 .B hls.
 147 .TP
 148 .B \-D
 149 This option is accepted only for script compatibility with calls to
 150 other assemblers; it has no effect on \c
 151 .B as\c
 152 \&.
 153 .TP
 154 .B \-\-defsym SYM=VALUE
 155 Define the symbol SYM to be VALUE before assembling the input file.
 156 VALUE must be an integer constant.  As in C, a leading 0x indicates a
 157 hexadecimal value, and a leading 0 indicates an octal value.
 158 .TP
 159 .B \-f
 160 ``fast''--skip preprocessing (assume source is compiler output).
 161 .TP
 162 .BI "\-I\ " path
 163 Add
 164 .I path
 165 to the search list for
 166 .B .include
 167 directives.
 168 .TP
 169 .B \-\-gstabs
 170 Generate stabs debugging information for each assembler line.  This
 171 may help debugging assembler code, if the debugger can handle it.
 172 .TP
 173 .B \-K
 174 Issue warnings when difference tables altered for long displacements.
 175 .TP
 176 .B \-L
 177 Keep (in symbol table) local symbols, starting with `\|\c
 178 .B L\c
 179 \|'
 180 .TP
 181 .B \-M, \-\-mri
 182 Assemble in MRI compatibility mode.
 183 .TP
 184 .BI "\-o\ " objfile
 185 Name the object-file output from \c
 186 .B as
 187 .TP
 188 .B \-R
 189 Fold data section into text section
 190 .TP
 191 .B \-\-traditional\-format
 192 Use same format as native assembler, when possible.
 193 .TP
 194 .B \-v
 195 Announce \c
 196 .B as\c
 197 \& version
 198 .TP
 199 .B \-W, \-\-no-warn
 200 Suppress warning messages.
 201 .TP
 202 .B \-\-fatal\-warnings
 203 Consider warnings to be fatal.
 204 .TP
 205 .B \-\-warn
 206 Just warn on warnings.
 207 .TP
 208 .IR "\-\^\-" "\ |\ " "files\|.\|.\|."
 209 Source files to assemble, or standard input (\c
 210 .BR "\-\^\-" ")"
 211 .TP
 212 .BI \-A var
 213 .I
 214 (When configured for Intel 960.)
 215 Specify which variant of the 960 architecture is the target.
 216 .TP
 217 .B \-b
 218 .I
 219 (When configured for Intel 960.)
 220 Add code to collect statistics about branches taken.
 221 .TP
 222 .B \-no-relax
 223 .I
 224 (When configured for Intel 960.)
 225 Do not alter compare-and-branch instructions for long displacements;
 226 error if necessary.
 227 .TP
 228 .B \-l
 229 .I
 230 (When configured for Motorola 68000).
 231 .br
 232 Shorten references to undefined symbols, to one word instead of two.
 233 .TP
 234 .BR "\-mc68000" "\||\|" "\-mc68010" "\||\|" "\-mc68020"
 235 .I
 236 (When configured for Motorola 68000).
 237 .br
 238 Specify what processor in the 68000 family is the target (default 68020)
 239
 240 .PP
 241 Options may be in any order, and may be
 242 before, after, or between file names.  The order of file names is
 243 significant.
 244
 245 `\|\c
 246 .B \-\^\-\c
 247 \|' (two hyphens) by itself names the standard input file
 248 explicitly, as one of the files for \c
 249 .B as\c
 250 \& to assemble.
 251
 252 Except for `\|\c
 253 .B \-\^\-\c
 254 \|' any command line argument that begins with a
 255 hyphen (`\|\c
 256 .B \-\c
 257 \|') is an option.  Each option changes the behavior of
 258 \c
 259 .B as\c
 260 \&.  No option changes the way another option works.  An
 261 option is a `\|\c
 262 .B \-\c
 263 \|' followed by one or more letters; the case of
 264 the letter is important.   All options are optional.
 265
 266 The `\|\c
 267 .B \-o\c
 268 \|' option expects exactly one file name to follow.  The file
 269 name may either immediately follow the option's letter (compatible
 270 with older assemblers) or it may be the next command argument (GNU
 271 standard).
 272
 273 These two command lines are equivalent:
 274 .br
 275 .B
 276 as\ \ \-o\ \ my\-object\-file.o\ \ mumble.s
 277 .br
 278 .B
 279 as\ \ \-omy\-object\-file.o\ \ mumble.s
 280
 281 .SH "SEE ALSO"
 282 .RB "`\|" as "\|'"
 283 entry in
 284 .B
 285 info\c
 286 \&;
 287 .I
 288 Using as: The GNU Assembler\c
 289 \&;
 290 .BR gcc "(" 1 "),"
 291 .BR ld "(" 1 ")."
 292
 293 .SH COPYING
 294 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
 295 .PP
 296 Permission is granted to make and distribute verbatim copies of
 297 this manual provided the copyright notice and this permission notice
 298 are preserved on all copies.
 299 .PP
 300 Permission is granted to copy and distribute modified versions of this
 301 manual under the conditions for verbatim copying, provided that the
 302 entire resulting derived work is distributed under the terms of a
 303 permission notice identical to this one.
 304 .PP
 305 Permission is granted to copy and distribute translations of this
 306 manual into another language, under the above conditions for modified
 307 versions, except that this permission notice may be included in
 308 translations approved by the Free Software Foundation instead of in
 309 the original English.