X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gas%2FREADME;h=d4fa416cf1fb2935d078d319f91873f1d7f7f810;hb=refs%2Fheads%2Fconcurrent-displaced-stepping-2020-04-01;hp=507b4542925e6511687dfad3c9a2f52fcb8101b7;hpb=e98fe4f7b54cbdf29aef9287bbb1bea8801dd05a;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/README b/gas/README index 507b454292..d4fa416cf1 100644 --- a/gas/README +++ b/gas/README @@ -1,43 +1,17 @@ --*- 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 ============= @@ -53,123 +27,16 @@ 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 + 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 ====================================== @@ -185,27 +52,16 @@ three pieces of information in the following pattern: `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 =================== @@ -217,38 +73,31 @@ options not listed here. 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 @@ -258,171 +107,64 @@ prefer; but you may abbreviate option names if you use `--'. 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. + +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.