429 lines
16 KiB
Plaintext
429 lines
16 KiB
Plaintext
-*- text -*-
|
|
|
|
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.
|
|
|
|
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)
|
|
|
|
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.
|
|
|
|
Documentation
|
|
=============
|
|
|
|
The GAS release includes texinfo source for its manual, which can be processed
|
|
into `info' or `dvi' forms.
|
|
|
|
The DVI form is suitable for printing or displaying; the commands for doing
|
|
this vary from system to system. On many systems, `lpr -d' will print a DVI
|
|
file. On others, you may need to run a program such as `dvips' to convert the
|
|
DVI file into a form your system can print.
|
|
|
|
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
|
|
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.
|
|
To build the info files, you will need the `makeinfo' program. Type:
|
|
|
|
cd gas-2.2.1/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
|
|
======================================
|
|
|
|
The specifications used for hosts and targets in the `configure'
|
|
script are based on a three-part naming scheme, but some short
|
|
predefined aliases are also supported. The full naming scheme encodes
|
|
three pieces of information in the following pattern:
|
|
|
|
ARCHITECTURE-VENDOR-OS
|
|
|
|
For example, you can use the alias `sun4' as a HOST argument or in a
|
|
`--target=TARGET' option. The equivalent full name is
|
|
`sparc-sun-sunos4'.
|
|
|
|
The `configure' script accompanying GAS does not provide any query
|
|
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
|
|
===================
|
|
|
|
Here is a summary of the `configure' options and arguments that are
|
|
most often useful for building GAS. `configure' also has several other
|
|
options not listed here.
|
|
|
|
configure [--help]
|
|
[--prefix=DIR]
|
|
[--srcdir=PATH]
|
|
[--norecursion] [--rm]
|
|
[--target=TARGET] HOST
|
|
[--with-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'.
|
|
|
|
`-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.
|
|
|
|
`--target=TARGET'
|
|
Configure GAS for cross-assembling programs for the specified
|
|
TARGET. Without this option, GAS is configured to assemble .o files
|
|
that run on the same machine (HOST) as GAS itself.
|
|
|
|
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.
|
|
|
|
`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:
|
|
|
|
`--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.
|
|
|
|
`--with-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.
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|