--*- text -*-
+ README for GAS
- README for GAS 2.2.1 release
- [cribbed largely from GDB's README file]
-
-This is version 2.2.1 of the GNU assembler.
-
-A number of things have changed and the wonderful world of gas looks very
-different. There's still a lot of irrelevant garbage lying around that will
-be cleaned up in time. Documentation is scarce, as are logs of the changes
-made since the last gas release. My apologies, and I'll try to get something
-useful.
+A number of things have changed since version 1 and the wonderful
+world of gas looks very different. There's still a lot of irrelevant
+garbage lying around that will be cleaned up in time. Documentation
+is scarce, as are logs of the changes made since the last gas release.
+My apologies, and I'll try to get something useful.
Unpacking and Installation - Summary
====================================
-In this release, the GNU assembler ("gas") sources, the generic GNU include
-files, the BFD ("binary file description") library, and other libraries all
-have directories of their own underneath the gas-2.2.1 directory. The idea is
-that a variety of GNU tools can share a common copy of these things.
-Configuration scripts and makefiles exist to cruise up and down this directory
-tree and automatically build all the pieces in the right order.
-
-When you unpack the gas-2.2.1.tar.z file, you'll find a directory called
-`gas-2.2.1'. To build GAS, you can just do:
-
- cd gas-2.2.1
- ./configure
- make
- cp gas/as.new /usr/local/bin/as (or whereever)
+See ../binutils/README.
-This will configure and build all the libraries as well as GAS. If
-`configure' can't determine your system type, specify one as its argument,
-e.g., sun4 or decstation.
-
-If you get compiler warnings during this stage, see the `Reporting Bugs'
-section below; there are a few known problems.
-
-GAS can be used as a cross-assembler, running on a machine of one type while
-producing object files for a machine of another type. See below.
+To build just the assembler, make the target all-gas.
Documentation
=============
If you wish to build the DVI file, you will need to have TeX installed on your
system. You can rebuild it by typing:
- cd gas-2.2.1/gas/doc
+ cd gas/doc
make as.dvi
The Info form is viewable with the GNU Emacs `info' subsystem, or the
-standalone `info' program, available as part of the GNU Texinfo distribution.
+stand-alone `info' program, available as part of the GNU Texinfo distribution.
To build the info files, you will need the `makeinfo' program. Type:
- cd gas-2.2.1/gas/doc
+ cd gas/doc
make info
-Installing GAS
-==============
-
-GAS comes with a `configure' script that automates the process of preparing
-GAS for installation; you can then use `make' to build the program.
-
-The GAS distribution includes all the source code you need for GAS in a single
-directory, the name of which is usually composed by appending the version
-number to `gas'.
-
-The simplest way to configure and build GAS is to run `configure' from the
-`gas-VERSION-NUMBER' source directory, which in this example is the `gas-2.2.1'
-directory.
-
-First switch to the `gas-VERSION-NUMBER' source directory if you are not
-already in it; then run `configure'. Pass the identifier for the platform on
-which GAS will run as an argument. For example:
-
- cd gas-2.2.1
- ./configure HOST
- make
-
-where HOST is an identifier such as `sun4' or `decstation', that identifies
-the platform where GAS will run.
-
-Running `configure HOST' followed by `make' builds the `bfd', `opcode', and
-`libiberty' libraries, then `gas' itself. (Exception: For VMS, the `bfd'
-library is not used.) The configured source files, and the binaries, are left
-in the corresponding source directories.
-
-The `configure' program is a Bourne-shell (`/bin/sh') script; if your system
-does not recognize this automatically when you run a different shell, you may
-need to run `sh' on it explicitly:
-
- sh configure HOST
-
-If you run `configure' from a directory that contains source
-directories for multiple libraries or programs, such as the `gas-2.2.1'
-source directory for version 2.2.1, `configure' creates configuration
-files for every directory level underneath (unless you tell it not to,
-with the `--norecursion' option).
-
-You can run the `configure' script from any of the subordinate directories in
-the GAS distribution, if you only want to configure that subdirectory; but be
-sure to specify a path to it.
-
-For example, with version 2.2.1, type the following to configure only the `bfd'
-subdirectory:
-
- cd gas-2.2.1/bfd
- ../configure HOST
-
-Compiling GAS in another directory
-==================================
-
- If you want to run GAS versions for several host or target machines,
-you need a different `gas' compiled for each combination of host and
-target. `configure' is designed to make this easy by allowing you to
-generate each configuration in a separate subdirectory, rather than in
-the source directory. If your `make' program handles the `VPATH'
-feature (GNU `make' does), running `make' in each of these directories
-builds the `gas' program specified there.
-
- To build `gas in a separate directory, run `configure' with the
-`--srcdir' option to specify where to find the source. (You also need
-to specify a path to find `configure' itself from your working
-directory. If the path to `configure' would be the same as the
-argument to `--srcdir', you can leave out the `--srcdir' option; it
-will be assumed.)
-
- For example, with version 2.2.1, you can build GAS in a separate
-directory for a Sun 4 like this:
-
- cd gas-2.2.1
- mkdir ../gas-sun4
- cd ../gas-sun4
- ../gas-2.2.1/configure sun4
- make
-
- When `configure' builds a configuration using a remote source
-directory, it creates a tree for the binaries with the same structure
-(and using the same names) as the tree under the source directory. In
-the example, you'd find the Sun 4 library `libiberty.a' in the
-directory `gas-sun4/libiberty', and GAS itself in `gas-sun4/gas'.
-
- One popular reason to build several GAS configurations in separate
-directories is to configure GAS for cross-compiling (where GAS runs on
-one machine--the host--while debugging programs that run on another
-machine--the target). You specify a cross-debugging target by giving
-the `--target=TARGET' option to `configure'.
-
- When you run `make' to build a program or library, you must run it
-in a configured directory--whatever directory you were in when you
-called `configure' (or one of its subdirectories).
-
- The `Makefile' that `configure' generates in each source directory
-also runs recursively. If you type `make' in a source directory such
-as `gas-2.2.1' (or in a separate configured directory configured with
-`--srcdir=PATH/gas-2.2.1'), you will build all the required libraries,
-and then build GAS.
-
- When you have multiple hosts or targets configured in separate
-directories, you can run `make' on them in parallel (for example, if
-they are NFS-mounted on each of the hosts); they will not interfere
-with each other.
-
-
Specifying names for hosts and targets
======================================
`sparc-sun-sunos4'.
The `configure' script accompanying GAS does not provide any query
-facility to list all supported host and target names or aliases.
+facility to list all supported host and target names or aliases.
`configure' calls the Bourne shell script `config.sub' to map
abbreviations to full names; you can read the script, if you wish, or
you can use it to test your guesses on abbreviations--for example:
- % sh config.sub sun4
- sparc-sun-sunos411
- % sh config.sub sun3
- m68k-sun-sunos411
- % sh config.sub decstation
- mips-dec-ultrix42
- % sh config.sub hp300bsd
- m68k-hp-bsd
% sh config.sub i386v
i386-unknown-sysv
% sh config.sub i786v
Invalid configuration `i786v': machine `i786v' not recognized
-`config.sub' is also distributed in the GAS source directory
-(`gas-2.2.1', for version 2.2.1).
-
`configure' options
===================
configure [--help]
[--prefix=DIR]
[--srcdir=PATH]
- [--norecursion] [--rm]
- [--target=TARGET] HOST
+ [--host=HOST]
+ [--target=TARGET]
[--with-OPTION]
+ [--enable-OPTION]
You may introduce options with a single `-' rather than `--' if you
prefer; but you may abbreviate option names if you use `--'.
`--help'
- Display a quick summary of how to invoke `configure'.
+ Print a summary of the options to `configure', and exit.
`-prefix=DIR'
Configure the source to install programs and files under directory
`DIR'.
`--srcdir=PATH'
- *Warning: using this option requires GNU `make', or another `make'
- that implements the `VPATH' feature.*
- Use this option to make configurations in directories separate
- from the GAS source directories. Among other things, you can use
- this to build (or maintain) several configurations simultaneously,
- in separate directories. `configure' writes configuration
- specific files in the current directory, but arranges for them to
- use the source in the directory PATH. `configure' will create
- directories under the working directory in parallel to the source
- directories below PATH.
-
-`--norecursion'
- Configure only the directory level where `configure' is executed;
- do not propagate configuration to subdirectories.
-
-`--rm'
- Remove the configuration that the other arguments specify.
+ Look for the package's source code in directory DIR. Usually
+ `configure' can determine that directory automatically.
+
+`--host=HOST'
+ Configure GAS to run on the specified HOST. Normally the
+ configure script can figure this out automatically.
+
+ There is no convenient way to generate a list of all available
+ hosts.
`--target=TARGET'
Configure GAS for cross-assembling programs for the specified
There is no convenient way to generate a list of all available
targets.
-`--with-OPTION'
- These flags tell the program or library being configured to assume the
- use of certain programs, or to otherwise configure themselves differently
- from the default for the specified host/target combination. See below
- for a list of `--with' options recognized in the gas-2.2.1 distribution.
-
-`HOST ...'
- Configure GAS to run on the specified HOST.
-
- There is no convenient way to generate a list of all available
- hosts.
+`--enable-OPTION'
+ These flags tell the program or library being configured to
+ configure itself differently from the default for the specified
+ host/target combination. See below for a list of `--enable'
+ options recognized in the gas distribution.
`configure' accepts other options, for compatibility with configuring
other GNU tools recursively; but these are the only options that affect
GAS or its supporting libraries.
-The `--with' options recognized by software in the gas-2.2.1 distribution are:
+The `--enable' options recognized by software in the gas distribution are:
-`--with-minimal-bfd'
- This causes the BFD library, if it is used by the assembler, to only link
- in support for the specified target; by default, support for all targets
- known to BFD is linked in, even though the assembler generally won't
- be able to use them. This will probably be made a default, or replaced
- by a better mechanism, for gas-2.1.
+`--enable-targets=...'
+ This causes one or more specified configurations to be added to those for
+ which BFD support is compiled. Currently gas cannot use any format other
+ than its compiled-in default, so this option is not very useful.
-`--with-bfd-assembler'
+`--enable-bfd-assembler'
This causes the assembler to use the new code being merged into it to use
BFD data structures internally, and use BFD for writing object files.
- For most targets, this isn't supported yet. See `BFD CONVERSION' in the
- file `gas/NOTES'.
-
-Supported platforms
-===================
-
-At this point I believe gas to be ansi only code for most target cpu's. That
-is, there should be relatively few, if any host system dependencies. So
-porting (as a cross-assembler) to hosts not yet supported should be fairly
-easy. Porting to a new target shouldn't be too tough if it's a variant of one
-already supported.
-
-Native assembling should work on:
-
- sun3
- sun4
- 386bsd
- bsd/386?
- linux
- m68k hpux 8.0 (hpux 7.0 may be a problem)
- vax bsd, ultrix, vms
- hp9000s300
- decstation
- iris
- miniframe (m68k-sysv from Convergent Technologies)
- i386-aix (ps/2)
-
-For cross-assemblers, I believe hosting to work on any of the machines listed
-above, plus:
-
- rs6000
- sun386i
- at least some flavors of hpux (hpux 7.0 may be a problem)
- most flavors of sysV
-
-I believe that gas as a cross-assembler can currently be targetted for:
-
- 386bsd
- bsd/386?
- decstation-bsd (a.out format, to be used in BSD 4.4)
- ebmon29k
- go32 (DOS on i386, with DJGPP)
- h8/300, h8/500 (Hitachi)
- hp9000/300
- i386-aix (ps/2)
- i960-coff
- linux
- mips ecoff (decstation-ultrix, iris, mips magnum)
- nindy960
- sco386
- sun3
- sun4
- vax bsd or ultrix?
- vms
- vxworks68k
- vxworks960
- z8000 (Zilog)
-
-MIPS ECOFF support has been added, but GAS will not run a C-style
-preprocessor. If you want that, rename your file to have a ".S" suffix, and
-run gcc on it.
-
-Support for ns32k, tahoe, i860, m88k may be suffering from bitrot.
-
-Support for ELF is being worked on. It should be available in version 2.2.
-
-This version does not support the IBM RS/6000. I am not aware of any work
-being done to support it. If you are interested in working on it, please
-contact me.
-
-This version does not support the HP PA/RISC running HP/UX. A modified version
-of gas 1.36 which does (well enough for gcc) is available by ftp from
-jaguar.cs.utah.edu.
-
-If you try out gas on some host or target not listed above, please let me know
-the results, so I can update the list.
+ For most targets, this isn't supported yet. For most targets where it has
+ been done, it's already the default. So generally you won't need to use
+ this option.
Compiler Support Hacks
======================
-The assembler has been modified to support a feature that is potentially
-useful when assembling compiler output, but which may confuse assembly
-language programmers. If assembler encounters a .word pseudo-op of the form
-symbol1-symbol2 (the difference of two symbols), and the difference of those
-two symbols will not fit in 16 bits, the assembler will create a branch around
-a long jump to symbol1, and insert this into the output directly before the
-next label: The .word will (instead of containing garbage, or giving an error
-message) contain (the address of the long jump)-symbol2. This allows the
-assembler to assemble jump tables that jump to locations very far away into
-code that works properly. If the next label is more than 32K away from the
-.word, you lose (silently); RMS claims this will never happen. If the -K
-option is given, you will get a warning message when this happens.
+On a few targets, the assembler has been modified to support a feature
+that is potentially useful when assembling compiler output, but which
+may confuse assembly language programmers. If assembler encounters a
+.word pseudo-op of the form symbol1-symbol2 (the difference of two
+symbols), and the difference of those two symbols will not fit in 16
+bits, the assembler will create a branch around a long jump to
+symbol1, and insert this into the output directly before the next
+label: The .word will (instead of containing garbage, or giving an
+error message) contain (the address of the long jump)-symbol2. This
+allows the assembler to assemble jump tables that jump to locations
+very far away into code that works properly. If the next label is
+more than 32K away from the .word, you lose (silently); RMS claims
+this will never happen. If the -K option is given, you will get a
+warning message when this happens.
REPORTING BUGS IN GAS
=====================
-Bugs in gas should be reported to bug-gnu-utils@prep.ai.mit.edu. They may be
-cross-posted to bug-gcc if they affect the use of gas with gcc. They should
-not be reported just to bug-gcc, since I don't read that list, and therefore
-wouldn't see them.
-
-If you report a bug in GAS, please remember to include:
-
-A description of exactly what went wrong, and exactly what should have
-happened instead.
-
-The type of machine (VAX, 68020, etc) and operating system (BSD, SunOS, DYNIX,
-VMS, etc) GAS was running on.
-
-The configuration name(s) given to the "configure" script. The
-"config.status" file should have this information.
-
-The options given to GAS at run time.
-
-The actual input file that caused the problem.
-
-It is silly to report a bug in GAS without including an input file for GAS.
-Don't ask us to generate the file just because you made it from files you
-think we have access to.
+Bugs in gas should be reported to:
-1. You might be mistaken.
-2. It might take us a lot of time to install things to regenerate that file.
-3. We might get a different file from the one you got, and might not see any
-bug.
+ bug-binutils@gnu.org.
-To save us these delays and uncertainties, always send the input file for the
-program that failed. A smaller test case that demonstrates the problem is of
-course preferable, but be sure it is a complete input file, and that it really
-does demonstrate the problem; but if paring it down would cause large delays
-in filing the bug report, don't bother.
+They may be cross-posted to gcc-bugs@gnu.org if they affect the use of
+gas with gcc. They should not be reported just to gcc-bugs, since not
+all of the maintainers read that list.
-If the input file is very large, and you are on the internet, you may want to
-make it avaliable for anonymous FTP instead of mailing it. If you do, include
-instructions for FTP'ing it in your bug report.
+See ../binutils/README for what we need in a bug report.
+\f
+Copyright (C) 2012-2020 Free Software Foundation, Inc.
-If you expect to be contributing a large number of test cases, it would be
-helpful if you would look at the test suite included in the release (based on
-the Deja Gnu testing framework, available from the usual ftp sites) and write
-test cases to fit into that framework. This is certainly not required.
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
projects / deliverable / binutils-gdb.git / blobdiff