gas/doc/as.1

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