| 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. |