This is the beta-test version of the GNU assembler. (Probably around Version 1.35, but check version.c which gets updated more often than this readme.) 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. These files are currently set up to allow you to compile all of the versions of the assembler (68020, VAX, ns32k, and i386) on the same machine. To compile the 68020 version, type 'make a68'. To compile the VAX version, type 'make avax'. To compile the ns32k version, type 'make a32k'. To compile the Intel 80386 version, type 'make a386'. 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. 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 If you report a bug in GAS, please remember to include: A description of exactly what went wrong. The type of machine GAS was running on (VAX, 68020, etc), The Operating System GAS was running under. The options given to GAS. 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. 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. ------------------------------ README.APOLLO --------------------------------- 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. 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. These changes will only work for SR10.1 or later systems, using the 6.6 or later version of the Apollo C compiler. 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. 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. 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 ------------------------------------ You might refer others who are interested in a similar thing. Kevin Buchs buchs@mayo.edu ------------------------------ README.COFF ----------------------------------- If you have a COFF system, you may wish to aquire UUCP: osu-cis!~/gnu/coff/gnu-coff.tar.Z or FTP: tut.cis.ohio-state.edu:/pub/gnu/coff/gnu-coff.tar.Z 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.
1) You should be aware that GNU-C, as with any other decent compiler, will do things when optimization is turned on that you may not expect. Sometimes intermediate results are not written to variables, if they are only used in one place, and sometimes variables that are not used at all will not be written to the symbol table. Also, parameters to inline functions are often inaccessible. You can see the assembly code equivalent by using KP7 in the debugger, and from this you can tell if in fact a variable should have the value that you expect. You can find out if a variable lives withing a register by doing a 'show symbol/addr'. 2) Overly complex data types, such as: int (*(*(*(*(*(* sarr6)[1])[1])[2])[3])[4])[5]; will not be debugged properly, since the debugging record overflows an internal debugger buffer. gcc-as will convert these to *void as far as the debugger symbol table is concerned, which will avoid any problems, and the assembler will give you a message informing you that this has happened. 3) You must, of course, compile and link with /debug. If you link without debug, you still get traceback table in the executable, but there is no symbol table for variables. 4) Included in the patches to VMS.C are fixes to two bugs that are unrelated to the changes that I have made. One of these made it impossible to debug small programs sometimes, and the other caused the debugger to become confused about which routine it was in, and give this incorrect info in tracebacks. 5) If you are using the GNU-C++ compiler, you should modify the compiler driver file GNU_CC:[000000]GCC.COM (or GXX.COM). If you have a seperate GXX.COM, then you need to change one line in GXX.COM to: $ if f$locate("D",p2) .ne. P2_Length then Debug = " ""-G0""" Notice zero---> ^ If you are using a GCC.COM that does both C and C++, add the following lines to GCC.COM: $! $! Use old style debugging records for VMS $! $ if (Debug.nes."" ).and. Plus then Debug = " ""-G0""" after the variables Plus and Debug are set. The reason for this, is that C++ compiler by default generates debugging records that are more complex, with many new syntactical elements that allow for the new features of the language. The -G0 switch tells the C++ compiler to use the old style debugging records. Until the debugger understands C++ there is not any point to try and use the expanded syntax. 6) When you have nested scopes, i.e.: main(){ int i; {int i; {int i; };};} and you say "EXAM i" the debugger needs to figure out which variable you actually want to reference. I have arranged things to define a block to the debugger when you use brackets to enter a new scope, so in the example above, the variables would be described as: TEST\main\i TEST\main\$0\i TEST\main\$0\$0\i At each level, the block name is a number with a dollar sign prefix, the numbers start with 0 and count upward. When you say EXAM i, the debugger looks at the current PC, and decides which block it is currently in. It works from the innermost level outward until it finds a block that has the variable "i" defined. You can always specify the scope explicitly. 7) With C++, there can be a lot of inline functions, and it would be rather restrictive to force the user to debug the program by converting all of the inline functions to normal functions. What I have done is to essentially "add" (with the debugger) source lines from the include files that contain the inline functions. Thus when you step into an inline function it appears as if you have called the function, and you can examine variables and so forth. There are several *very* important differences, however. First of all, since there is no function call involved, you cannot step over the inline function call - you always step into it. Secondly, since the same source lines are used in many locations, there is a seperate copy of the source for *each* usage. Without this, breakpoints do not work, since we must have a 1-to-1 mapping between source lines and PC. Since you cannot step over inline function calls, it can be a real pain if you are not really interested in what is going on for that function call. What I have done is to use the "-D" switch for the assembler to toggle the following behavior. With the "-D" switch, all inline functions are included in the object file, and you can debug everything. Without the "-D" switch (default case with VMS implementation), inline functions are included *only* if they did not come from system header files (i.e. from GNU_CC_INCLUDE: or GNU_GXX_INCLUDE:). Thus, without the switch the user only debugs his/her own inline functions, and not the system ones. (This is especially useful if you do a lot of stream I/O in C++). This probably will not provide enough granularity for many users, but for now this is still somewhat experimental, and I would like to reflect upon it and get some feedback before I go any further. Possible solutions include an interactive prompting, a logical name, or a new command line option in gcc.c (which is then passed through somehow to the guts of the assembler). The inline functions from header files appear after the source code for the source file. This has the advantage that the source file itself is numbered with the same line numbers that you get with an editor. In addition, the entire header file is not included, since the assembler makes a list of the min and max source lines that are used, and only includes those lines from the first to the last actually used. (It is easy to change it to include the whole file). 8) When you are debugging C++ objects, the object "this" is refered to as "$this". Actually, the compiler writes it as ".this", but the period is not good for the debugger, so I have a routine to convert it to a $. (It actually converts all periods to $, but only for variables, since this was intended to allow us to access "this". 9) If you use the asm("...") keyword for global symbols, you will not be able to see that symbol with the debugger. The reason is that there are two records for the symbol stored in the data structures of the assembler. One contains the info such as psect number and offset, and the other one contains the information having to do with the data type of the variable. In order to debug as symbol, you need to be able to coorelate these records, and the only way to do this is by name. The record with the storage attributes will take the name used in the asm directive, and the record that specifies the data type has the actual variable name, and thus when you use the asm directive to change a variable name, the symbol becomes invisible. 10) Older versions of the compiler ( GNU-C 1.37.92 and earlier) place global constants in the text psect. This is unfortunate, since to the linker this appears to be an entry point. I sent a patch to the compiler to RMS, which will generate a .const section for these variables, and patched the assembler to put these variables into a psect just like that for normal variables, except that they are marked NOWRT. static constants are still placed in the text psect, since there is no need for any external access.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.