diff options
| -rw-r--r-- | gas/README | 517 |
1 files changed, 403 insertions, 114 deletions
@@ -1,139 +1,428 @@ -This is the beta-test version of the GNU assembler. (Probably -around Version 1.38, but check version.c which gets updated more -often than this readme.) - -These files are currently set up to allow you to compile all of the -versions of the assembler on the same machine. 'make all' compiles -all of them. The resulting executable names are: - - 68020 a68 - Vax avax - NS 32xxx a32k - Intel 80386 a386 - SPARC asparc - AMD 29000 asm29k - -The Makefile contains instructions on how to make one of the -assemblers compile as the default. - -Before you can compile the 68020 version of the assembler, you must -make m68k.h be a link to m-sun3.h , m-hpux.h or m-generic.h . If -you are on a SUN-3 (or other machine that uses a magic number of -(2 << 16) | OMAGIC type 'ln -s m-sun3.h m68k.h' else if you are on a -machine running HP-UX, type 'ln m-hpux.h m689k.h' else type -'ln -s m-generic.h m68k.h' If your machine does not support symbolic -links, omit the '-s'. - -See the instructions in the Makefile for compiling gas for the Sequent -Symmetry (dynix 3.0.12 + others?) or for the HP 9000/300 - -If your machine does not have both varargs.h and vfprintf(), but does have -_doprnt() add -DNO_VARARGS to the CFLAGS line in the makefile. If your -machine has neither vfprintf() or _doprnt(), you will have to change -messages.c in order to get readable error messages from the assembler. - -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 If you can't -get through to prep, try hack@gnu.ai.mit.edu or hack@media-lab.media.mit.edu +-*- text -*- -If you report a bug in GAS, please remember to include: + README for GAS 2.2.1 release + [cribbed largely from GDB's README file] -A description of exactly what went wrong. +This is version 2.2.1 of the GNU assembler. -The type of machine GAS was running on (VAX, 68020, etc), +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. -The Operating System GAS was running under. +Unpacking and Installation - Summary +==================================== -The options given to GAS. +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. -The actual input file that caused the problem. +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: -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. + cd gas-2.2.1 + ./configure + make + cp gas/as.new /usr/local/bin/as (or whereever) -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. +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. -To save us these delays and uncertainties, always send the input file -for the program that failed. +If you wish to build the DVI file, you will need to have TeX installed on your +system. You can rebuild it by typing: -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. + cd gas-2.2.1/gas/doc + make as.dvi ------------------------------- README.APOLLO --------------------------------- +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: -The changes required to get the GNU C compiler running on -Apollo 68K platforms are available via anonymous ftp from -labrea.stanford.edu (36.8.0.47) in the form of a compressed -tar file named "/pub/gnu/apollo-gcc-1.37.tar.Z". -The size of the file is 84145 bytes. + 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. -To build GCC for the Apollo you'll need the virgin FSF -distributions of bison-1.03, gas-1.34, and gcc-1.37. They -are also on labrea.stanford.edu as well as prep.ai.mit.edu. -My changes are to enable gas to produce Apollo COFF object -files and allow gcc to parse some of the syntax extensions -which appear in Apollo C header files. Note that the -COFF encapsulation technique cannot be used on the Apollo. - -The tar file should be unpacked in the directory containing -the gas-1.34 and gcc-1.37 directories; a few files will be overlaid, -and an APOLLO-GCC-README file will appear in the top directory. -This file contains detailed instructions on how to proceed. +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'. -These changes will only work for SR10.1 or later systems, using -the 6.6 or later version of the Apollo C compiler. +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. -If you do not have ftp access, I can mail you the changes in the -form of diffs; they are approximately 40K in length. If you request -them, be sure to give me a voice phone number so I can contact you -in case I can't send you mail; I've had several requests in the -past from people I can't contact. +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: -By the way, I'm working on getting the GNU C++ compiler running; -there are a couple problems to solve. I hope to be able to announce -the Apollo version shortly after the 1.37 version is released. + cd gas-2.2.1 + ./configure HOST + make -John Vasta Hewlett-Packard Apollo Systems Division -vasta@apollo.hp.com M.S. CHA-01-LT -(508) 256-6600 x6362 300 Apollo Drive, Chelmsford, MA 01824 -UUCP: {decwrl!decvax, mit-eddie, attunix}!apollo!vasta +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. -You might refer others who are interested in a similar thing. +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. -Kevin Buchs buchs@mayo.edu +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. ------------------------------- README.COFF ----------------------------------- +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. -If you have a COFF system, you may wish to aquire +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. - UUCP: osu-cis!~/gnu/coff/gnu-coff.tar.Z - or - FTP: tut.cis.ohio-state.edu:/pub/gnu/coff/gnu-coff.tar.Z +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. -These contain patches for gas that will make it produce COFF output. -I have never seen these patches, so I don't know how well they work. +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. |