gas/doc/as.1

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