gas/README

   1 -*- text -*-
   2
   3                 README for GAS 2.2.1 release
   4           [cribbed largely from GDB's README file]
   5
   6 This is version 2.2.1 of the GNU assembler.
   7
   8 A number of things have changed and the wonderful world of gas looks very
   9 different.  There's still a lot of irrelevant garbage lying around that will
  10 be cleaned up in time.  Documentation is scarce, as are logs of the changes
  11 made since the last gas release.  My apologies, and I'll try to get something
  12 useful.
  13
  14 Unpacking and Installation - Summary
  15 ====================================
  16
  17 In this release, the GNU assembler ("gas") sources, the generic GNU include
  18 files, the BFD ("binary file description") library, and other libraries all
  19 have directories of their own underneath the gas-2.2.1 directory.  The idea is
  20 that a variety of GNU tools can share a common copy of these things.
  21 Configuration scripts and makefiles exist to cruise up and down this directory
  22 tree and automatically build all the pieces in the right order.
  23
  24 When you unpack the gas-2.2.1.tar.z file, you'll find a directory called
  25 `gas-2.2.1'.  To build GAS, you can just do:
  26
  27         cd gas-2.2.1
  28         ./configure
  29         make
  30         cp gas/as.new /usr/local/bin/as (or whereever)
  31
  32 This will configure and build all the libraries as well as GAS.  If
  33 `configure' can't determine your system type, specify one as its argument,
  34 e.g., sun4 or decstation.
  35
  36 If you get compiler warnings during this stage, see the `Reporting Bugs'
  37 section below; there are a few known problems.
  38
  39 GAS can be used as a cross-assembler, running on a machine of one type while
  40 producing object files for a machine of another type.  See below.
  41
  42 Documentation
  43 =============
  44
  45 The GAS release includes texinfo source for its manual, which can be processed
  46 into `info' or `dvi' forms.
  47
  48 The DVI form is suitable for printing or displaying; the commands for doing
  49 this vary from system to system.  On many systems, `lpr -d' will print a DVI
  50 file.  On others, you may need to run a program such as `dvips' to convert the
  51 DVI file into a form your system can print.
  52
  53 If you wish to build the DVI file, you will need to have TeX installed on your
  54 system.  You can rebuild it by typing:
  55
  56         cd gas-2.2.1/gas/doc
  57         make as.dvi
  58
  59 The Info form is viewable with the GNU Emacs `info' subsystem, or the
  60 standalone `info' program, available as part of the GNU Texinfo distribution.
  61 To build the info files, you will need the `makeinfo' program.  Type:
  62
  63         cd gas-2.2.1/gas/doc
  64         make info
  65
  66 Installing GAS
  67 ==============
  68
  69 GAS comes with a `configure' script that automates the process of preparing
  70 GAS for installation; you can then use `make' to build the program.
  71
  72 The GAS distribution includes all the source code you need for GAS in a single
  73 directory, the name of which is usually composed by appending the version
  74 number to `gas'.
  75
  76 The simplest way to configure and build GAS is to run `configure' from the
  77 `gas-VERSION-NUMBER' source directory, which in this example is the `gas-2.2.1'
  78 directory.
  79
  80 First switch to the `gas-VERSION-NUMBER' source directory if you are not
  81 already in it; then run `configure'.  Pass the identifier for the platform on
  82 which GAS will run as an argument.  For example:
  83
  84         cd gas-2.2.1
  85         ./configure HOST
  86         make
  87
  88 where HOST is an identifier such as `sun4' or `decstation', that identifies
  89 the platform where GAS will run.
  90
  91 Running `configure HOST' followed by `make' builds the `bfd', `opcode', and
  92 `libiberty' libraries, then `gas' itself.  (Exception: For VMS, the `bfd'
  93 library is not used.)  The configured source files, and the binaries, are left
  94 in the corresponding source directories.
  95
  96 The `configure' program is a Bourne-shell (`/bin/sh') script; if your system
  97 does not recognize this automatically when you run a different shell, you may
  98 need to run `sh' on it explicitly:
  99
 100         sh configure HOST
 101
 102 If you run `configure' from a directory that contains source
 103 directories for multiple libraries or programs, such as the `gas-2.2.1'
 104 source directory for version 2.2.1, `configure' creates configuration
 105 files for every directory level underneath (unless you tell it not to,
 106 with the `--norecursion' option).
 107
 108 You can run the `configure' script from any of the subordinate directories in
 109 the GAS distribution, if you only want to configure that subdirectory; but be
 110 sure to specify a path to it.
 111
 112 For example, with version 2.2.1, type the following to configure only the `bfd'
 113 subdirectory:
 114
 115      cd gas-2.2.1/bfd
 116      ../configure HOST
 117
 118 Compiling GAS in another directory
 119 ==================================
 120
 121    If you want to run GAS versions for several host or target machines,
 122 you need a different `gas' compiled for each combination of host and
 123 target.  `configure' is designed to make this easy by allowing you to
 124 generate each configuration in a separate subdirectory, rather than in
 125 the source directory.  If your `make' program handles the `VPATH'
 126 feature (GNU `make' does), running `make' in each of these directories
 127 builds the `gas' program specified there.
 128
 129    To build `gas in a separate directory, run `configure' with the
 130 `--srcdir' option to specify where to find the source. (You also need
 131 to specify a path to find `configure' itself from your working
 132 directory.  If the path to `configure' would be the same as the
 133 argument to `--srcdir', you can leave out the `--srcdir' option; it
 134 will be assumed.)
 135
 136    For example, with version 2.2.1, you can build GAS in a separate
 137 directory for a Sun 4 like this:
 138
 139      cd gas-2.2.1
 140      mkdir ../gas-sun4
 141      cd ../gas-sun4
 142      ../gas-2.2.1/configure sun4
 143      make
 144
 145    When `configure' builds a configuration using a remote source
 146 directory, it creates a tree for the binaries with the same structure
 147 (and using the same names) as the tree under the source directory.  In
 148 the example, you'd find the Sun 4 library `libiberty.a' in the
 149 directory `gas-sun4/libiberty', and GAS itself in `gas-sun4/gas'.
 150
 151    One popular reason to build several GAS configurations in separate
 152 directories is to configure GAS for cross-compiling (where GAS runs on
 153 one machine--the host--while debugging programs that run on another
 154 machine--the target).  You specify a cross-debugging target by giving
 155 the `--target=TARGET' option to `configure'.
 156
 157    When you run `make' to build a program or library, you must run it
 158 in a configured directory--whatever directory you were in when you
 159 called `configure' (or one of its subdirectories).
 160
 161    The `Makefile' that `configure' generates in each source directory
 162 also runs recursively.  If you type `make' in a source directory such
 163 as `gas-2.2.1' (or in a separate configured directory configured with
 164 `--srcdir=PATH/gas-2.2.1'), you will build all the required libraries,
 165 and then build GAS.
 166
 167    When you have multiple hosts or targets configured in separate
 168 directories, you can run `make' on them in parallel (for example, if
 169 they are NFS-mounted on each of the hosts); they will not interfere
 170 with each other.
 171
 172
 173 Specifying names for hosts and targets
 174 ======================================
 175
 176    The specifications used for hosts and targets in the `configure'
 177 script are based on a three-part naming scheme, but some short
 178 predefined aliases are also supported.  The full naming scheme encodes
 179 three pieces of information in the following pattern:
 180
 181      ARCHITECTURE-VENDOR-OS
 182
 183    For example, you can use the alias `sun4' as a HOST argument or in a
 184 `--target=TARGET' option.  The equivalent full name is
 185 `sparc-sun-sunos4'.
 186
 187    The `configure' script accompanying GAS does not provide any query
 188 facility to list all supported host and target names or aliases.
 189 `configure' calls the Bourne shell script `config.sub' to map
 190 abbreviations to full names; you can read the script, if you wish, or
 191 you can use it to test your guesses on abbreviations--for example:
 192
 193      % sh config.sub sun4
 194      sparc-sun-sunos411
 195      % sh config.sub sun3
 196      m68k-sun-sunos411
 197      % sh config.sub decstation
 198      mips-dec-ultrix42
 199      % sh config.sub hp300bsd
 200      m68k-hp-bsd
 201      % sh config.sub i386v
 202      i386-unknown-sysv
 203      % sh config.sub i786v
 204      Invalid configuration `i786v': machine `i786v' not recognized
 205
 206 `config.sub' is also distributed in the GAS source directory
 207 (`gas-2.2.1', for version 2.2.1).
 208
 209
 210 `configure' options
 211 ===================
 212
 213    Here is a summary of the `configure' options and arguments that are
 214 most often useful for building GAS.  `configure' also has several other
 215 options not listed here.
 216
 217      configure [--help]
 218                [--prefix=DIR]
 219                [--srcdir=PATH]
 220                [--norecursion] [--rm]
 221                [--target=TARGET] HOST
 222                [--with-OPTION]
 223
 224 You may introduce options with a single `-' rather than `--' if you
 225 prefer; but you may abbreviate option names if you use `--'.
 226
 227 `--help'
 228      Display a quick summary of how to invoke `configure'.
 229
 230 `-prefix=DIR'
 231      Configure the source to install programs and files under directory
 232      `DIR'.
 233
 234 `--srcdir=PATH'
 235      *Warning: using this option requires GNU `make', or another `make'
 236      that implements the `VPATH' feature.*
 237      Use this option to make configurations in directories separate
 238      from the GAS source directories.  Among other things, you can use
 239      this to build (or maintain) several configurations simultaneously,
 240      in separate directories.  `configure' writes configuration
 241      specific files in the current directory, but arranges for them to
 242      use the source in the directory PATH.  `configure' will create
 243      directories under the working directory in parallel to the source
 244      directories below PATH.
 245
 246 `--norecursion'
 247      Configure only the directory level where `configure' is executed;
 248      do not propagate configuration to subdirectories.
 249
 250 `--rm'
 251      Remove the configuration that the other arguments specify.
 252
 253 `--target=TARGET'
 254      Configure GAS for cross-assembling programs for the specified
 255      TARGET.  Without this option, GAS is configured to assemble .o files
 256      that run on the same machine (HOST) as GAS itself.
 257
 258      There is no convenient way to generate a list of all available
 259      targets.
 260
 261 `--with-OPTION'
 262      These flags tell the program or library being configured to assume the
 263      use of certain programs, or to otherwise configure themselves differently
 264      from the default for the specified host/target combination.  See below
 265      for a list of `--with' options recognized in the gas-2.2.1 distribution.
 266
 267 `HOST ...'
 268      Configure GAS to run on the specified HOST.
 269
 270      There is no convenient way to generate a list of all available
 271      hosts.
 272
 273 `configure' accepts other options, for compatibility with configuring
 274 other GNU tools recursively; but these are the only options that affect
 275 GAS or its supporting libraries.
 276
 277 The `--with' options recognized by software in the gas-2.2.1 distribution are:
 278
 279 `--with-minimal-bfd'
 280      This causes the BFD library, if it is used by the assembler, to only link
 281      in support for the specified target; by default, support for all targets
 282      known to BFD is linked in, even though the assembler generally won't
 283      be able to use them.  This will probably be made a default, or replaced
 284      by a better mechanism, for gas-2.1.
 285
 286 `--with-bfd-assembler'
 287      This causes the assembler to use the new code being merged into it to use
 288      BFD data structures internally, and use BFD for writing object files.
 289      For most targets, this isn't supported yet.  See `BFD CONVERSION' in the
 290      file `gas/NOTES'.
 291
 292 Supported platforms
 293 ===================
 294
 295 At this point I believe gas to be ansi only code for most target cpu's.  That
 296 is, there should be relatively few, if any host system dependencies.  So
 297 porting (as a cross-assembler) to hosts not yet supported should be fairly
 298 easy.  Porting to a new target shouldn't be too tough if it's a variant of one
 299 already supported.
 300
 301 Native assembling should work on:
 302
 303         sun3
 304         sun4
 305         386bsd
 306         bsd/386?
 307         linux
 308         m68k hpux 8.0 (hpux 7.0 may be a problem)
 309         vax bsd, ultrix, vms
 310         hp9000s300
 311         decstation
 312         iris
 313         miniframe (m68k-sysv from Convergent Technologies)
 314         i386-aix (ps/2)
 315
 316 For cross-assemblers, I believe hosting to work on any of the machines listed
 317 above, plus:
 318
 319         rs6000
 320         sun386i
 321         at least some flavors of hpux (hpux 7.0 may be a problem)
 322         most flavors of sysV
 323
 324 I believe that gas as a cross-assembler can currently be targetted for:
 325
 326         386bsd
 327         bsd/386?
 328         decstation-bsd (a.out format, to be used in BSD 4.4)
 329         ebmon29k
 330         go32 (DOS on i386, with DJGPP)
 331         h8/300, h8/500 (Hitachi)
 332         hp9000/300
 333         i386-aix (ps/2)
 334         i960-coff
 335         linux
 336         mips ecoff (decstation-ultrix, iris, mips magnum)
 337         nindy960
 338         sco386
 339         sun3
 340         sun4
 341         vax bsd or ultrix?
 342         vms
 343         vxworks68k
 344         vxworks960
 345         z8000 (Zilog)
 346
 347 MIPS ECOFF support has been added, but GAS will not run a C-style
 348 preprocessor.  If you want that, rename your file to have a ".S" suffix, and
 349 run gcc on it.
 350
 351 Support for ns32k, tahoe, i860, m88k may be suffering from bitrot.
 352
 353 Support for ELF is being worked on.  It should be available in version 2.2.
 354
 355 This version does not support the IBM RS/6000.  I am not aware of any work
 356 being done to support it.  If you are interested in working on it, please
 357 contact me.
 358
 359 This version does not support the HP PA/RISC running HP/UX.  A modified version
 360 of gas 1.36 which does (well enough for gcc) is available by ftp from
 361 jaguar.cs.utah.edu.
 362
 363 If you try out gas on some host or target not listed above, please let me know
 364 the results, so I can update the list.
 365
 366 Compiler Support Hacks
 367 ======================
 368
 369 The assembler has been modified to support a feature that is potentially
 370 useful when assembling compiler output, but which may confuse assembly
 371 language programmers.  If assembler encounters a .word pseudo-op of the form
 372 symbol1-symbol2 (the difference of two symbols), and the difference of those
 373 two symbols will not fit in 16 bits, the assembler will create a branch around
 374 a long jump to symbol1, and insert this into the output directly before the
 375 next label: The .word will (instead of containing garbage, or giving an error
 376 message) contain (the address of the long jump)-symbol2.  This allows the
 377 assembler to assemble jump tables that jump to locations very far away into
 378 code that works properly.  If the next label is more than 32K away from the
 379 .word, you lose (silently); RMS claims this will never happen.  If the -K
 380 option is given, you will get a warning message when this happens.
 381
 382
 383 REPORTING BUGS IN GAS
 384 =====================
 385
 386 Bugs in gas should be reported to bug-gnu-utils@prep.ai.mit.edu.  They may be
 387 cross-posted to bug-gcc if they affect the use of gas with gcc.  They should
 388 not be reported just to bug-gcc, since I don't read that list, and therefore
 389 wouldn't see them.
 390
 391 If you report a bug in GAS, please remember to include:
 392
 393 A description of exactly what went wrong, and exactly what should have
 394 happened instead.
 395
 396 The type of machine (VAX, 68020, etc) and operating system (BSD, SunOS, DYNIX,
 397 VMS, etc) GAS was running on.
 398
 399 The configuration name(s) given to the "configure" script.  The
 400 "config.status" file should have this information.
 401
 402 The options given to GAS at run time.
 403
 404 The actual input file that caused the problem.
 405
 406 It is silly to report a bug in GAS without including an input file for GAS.
 407 Don't ask us to generate the file just because you made it from files you
 408 think we have access to.
 409
 410 1. You might be mistaken.
 411 2. It might take us a lot of time to install things to regenerate that file.
 412 3. We might get a different file from the one you got, and might not see any
 413 bug.
 414
 415 To save us these delays and uncertainties, always send the input file for the
 416 program that failed.  A smaller test case that demonstrates the problem is of
 417 course preferable, but be sure it is a complete input file, and that it really
 418 does demonstrate the problem; but if paring it down would cause large delays
 419 in filing the bug report, don't bother.
 420
 421 If the input file is very large, and you are on the internet, you may want to
 422 make it avaliable for anonymous FTP instead of mailing it.  If you do, include
 423 instructions for FTP'ing it in your bug report.
 424
 425 If you expect to be contributing a large number of test cases, it would be
 426 helpful if you would look at the test suite included in the release (based on
 427 the Deja Gnu testing framework, available from the usual ftp sites) and write
 428 test cases to fit into that framework.  This is certainly not required.