diff options
author | John Gilmore <gnu@cygnus> | 1992-10-23 07:53:03 +0000 |
---|---|---|
committer | John Gilmore <gnu@cygnus> | 1992-10-23 07:53:03 +0000 |
commit | c50c519792a2f283cef6fd09e9196d07d031ee18 (patch) | |
tree | 010b47e2927f03b8d00f526e01a7bbca0a15b98a /gdb/README | |
parent | 3214c51c62556d7288d1310ec9e0ae6ae0d667fc (diff) | |
download | fsf-binutils-gdb-c50c519792a2f283cef6fd09e9196d07d031ee18.zip fsf-binutils-gdb-c50c519792a2f283cef6fd09e9196d07d031ee18.tar.gz fsf-binutils-gdb-c50c519792a2f283cef6fd09e9196d07d031ee18.tar.bz2 |
* Makefile.in (VERSION): gdb-4.7 release.
* README: Update for gdb-4.7.
Diffstat (limited to 'gdb/README')
-rw-r--r-- | gdb/README | 343 |
1 files changed, 173 insertions, 170 deletions
@@ -1,8 +1,8 @@ - README for gdb-4.4 release - John Gilmore & Stu Grossman 31 Jan 1992 + README for gdb-4.7 release + Stu Grossman & John Gilmore 23 October 1992 This is GDB, the GNU source-level debugger, presently running under un*x. -A summary of new features is in the file `WHATS.NEW'. +A summary of new features is in the file `NEWS'. Unpacking and Installation -- quick overview @@ -10,22 +10,24 @@ Unpacking and Installation -- quick overview In this release, the GDB debugger sources, the generic GNU include files, the BFD ("binary file description") library, the readline library, -and a miscellaneous library all have directories of their own underneath -the gdb-4.4 directory. The idea is that a variety of GNU tools can +and other libraries all have directories of their own underneath +the gdb-4.7 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 gdb-4.4.tar.Z file, you'll get a directory called -`gdb-4.4', which contains: +When you unpack the gdb-4.7.tar.Z file, you'll get a directory called +`gdb-4.7', which contains: - DOC.configure bfd/ configure* glob/ readline/ - Makefile.in config/ configure.in include/ texinfo/ - README config.sub* gdb/ libiberty/ + COPYING.LIB config/ configure.texi mmalloc/ + Makefile.in config.sub* gdb/ move-if-change* + README configure* glob/ opcodes/ + bfd/ configure.in include/ readline/ + cfg-paper.texi configure.man libiberty/ texinfo/ To build GDB, you can just do: - cd gdb-4.4 + cd gdb-4.7 ./configure HOSTTYPE (e.g. sun4, decstation) make cp gdb/gdb /usr/local/bin/gdb (or wherever you want) @@ -39,16 +41,16 @@ while debugging a program running on a machine of another type. See below. More Documentation -================== +****************** - The GDB 4 release includes an already-formatted reference card, -ready for printing on a PostScript or GhostScript printer, in the `gdb' -subdirectory of the main source directory--in `gdb-4.4/gdb/refcard.ps' -of the version 4.4 release. If you have a PostScript or GhostScript -printer, you can print the reference card by just sending `refcard.ps' -to the printer. + The GDB 4 release includes an already-formatted reference card, ready +for printing with PostScript or GhostScript, in the `gdb' subdirectory +of the main source directory--in `gdb-4.7/gdb/refcard.ps' of the +version 4.7 release. If you can use PostScript or GhostScript with your +printer, you can print the reference card immediately with `refcard.ps'. - If all you have is TeX, format the GDB reference card by typing: + The release also includes the source for the reference card. You +can format it, using TeX, by typing: make refcard.dvi @@ -57,25 +59,27 @@ to the printer. high. You will need to specify this form of printing as an option to your DVI output program. - All the documentation for GDB comes as part of the online -distribution. The documentation is written in Texinfo format, -which is a documentation system that uses a single source file to -produce both on-line information and a printed manual. You can use -one of the Info formatting commands to create the on-line version of -the documentation and TeX (or `texi2roff') to typeset the printed -version. + All the documentation for GDB comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and TeX (or `texi2roff') to typeset the printed version. - GDB includes an already formatted copy of the on-line Info version -of this manual in the `gdb' subdirectory. The main Info file is + GDB includes an already formatted copy of the on-line Info version of +this manual in the `gdb' subdirectory. The main Info file is `gdb-VERSION-NUMBER/gdb/gdb.info', and it refers to subordinate files -matching `gdb.info*' in the same directory. +matching `gdb.info*' in the same directory. If necessary, you can +print out these files, or read them with any editor; but they are +easier to read using the `info' subsystem in GNU Emacs or the +standalone `info' program, available as part of the GNU Texinfo +distribution. If you want to format these Info files yourself, you need one of the -Info formatting programs, such as `texinfo-format-buffer' or -`makeinfo'. +Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. If you have `makeinfo' installed, and are in the top level GDB -source directory (`gdb-4.4', in the case of version 4.4), you can make +source directory (`gdb-4.7', in the case of version 4.7), you can make the Info file by typing: cd gdb @@ -95,70 +99,79 @@ a `.dvi' extension. TeX also requires a macro definitions file called `texinfo.tex'. This file tells TeX how to typeset a document written in Texinfo -format. On its own, TeX cannot read, much less typeset a Texinfo -file. `texinfo.tex' is distributed with GDB and is located in the +format. On its own, TeX cannot read, much less typeset a Texinfo file. + `texinfo.tex' is distributed with GDB and is located in the `gdb-VERSION-NUMBER/texinfo' directory. - If you have TeX and a DVI printer program installed, you can -typeset and print this manual. First switch to the the `gdb' -subdirectory of the main source directory (for example, to -`gdb-4.4/gdb') and then type: + If you have TeX and a DVI printer program installed, you can typeset +and print this manual. First switch to the the `gdb' subdirectory of +the main source directory (for example, to `gdb-4.7/gdb') and then type: make gdb.dvi + Installing GDB -============== +*************** GDB comes with a `configure' script that automates the process of preparing GDB for installation; you can then use `make' to build the -`gdb' program. +program. - The GDB distribution includes all the source code you need for GDB -in a single directory, whose name is usually composed by appending the + The GDB distribution includes all the source code you need for GDB in +a single directory, whose name is usually composed by appending the version number to `gdb'. - For example, the GDB version 4.4 distribution is in the `gdb-4.4' + For example, the GDB version 4.7 distribution is in the `gdb-4.7' directory. That directory contains: -`gdb-4.4/configure (and supporting files)' +`gdb-4.7/configure (and supporting files)' script for configuring GDB and all its supporting libraries. -`gdb-4.4/gdb' +`gdb-4.7/gdb' the source specific to GDB itself -`gdb-4.4/bfd' - source for the Binary File Descriptor Library +`gdb-4.7/bfd' + source for the Binary File Descriptor library -`gdb-4.4/include' +`gdb-4.7/include' GNU include files -`gdb-4.4/libiberty' +`gdb-4.7/libiberty' source for the `-liberty' free software library -`gdb-4.4/readline' +`gdb-4.7/opcodes' + source for the library of opcode tables and disassemblers + +`gdb-4.7/readline' source for the GNU command-line interface +`gdb-4.7/glob' + source for the GNU filename pattern-matching subroutine + +`gdb-4.7/mmalloc' + source for the GNU memory-mapped malloc package + The simplest way to configure and build GDB is to run `configure' from the `gdb-VERSION-NUMBER' source directory, which in this example -is the `gdb-4.4' directory. +is the `gdb-4.7' directory. - First switch to the `gdb-VERSION-NUMBER' source directory if you -are not already in it; then run `configure'. Pass the identifier for -the platform on which GDB will run as an argument. + First switch to the `gdb-VERSION-NUMBER' source directory if you are +not already in it; then run `configure'. Pass the identifier for the +platform on which GDB will run as an argument. For example: - cd gdb-4.4 + cd gdb-4.7 ./configure HOST make where HOST is an identifier such as `sun4' or `decstation', that identifies the platform where GDB will run. - These `configure' and `make' commands build the three libraries `bfd', -`readline', and `libiberty', then `gdb' itself. The configured source -files, and the binaries, are left in the corresponding source -directories. + Running `configure HOST' followed by `make' builds the `bfd', +`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. +The configured source files, and the binaries, are left in the +corresponding source directories. `configure' is a Bourne-shell (`/bin/sh') script; if your system does not recognize this automatically when you run a different shell, @@ -167,51 +180,53 @@ 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 `gdb-4.4' -source directory for version 4.4, `configure' creates configuration +directories for multiple libraries or programs, such as the `gdb-4.7' +source directory for version 4.7, `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 GDB distribution, if you only want to configure -that subdirectory; but be sure to specify a path to it. +directories in the GDB distribution, if you only want to configure that +subdirectory; but be sure to specify a path to it. - For example, with version 4.4, type the following to configure only + For example, with version 4.7, type the following to configure only the `bfd' subdirectory: - cd gdb-4.4/bfd + cd gdb-4.7/bfd ../configure HOST - You can install `gdb' anywhere; it has no hardwired paths. -However, you should make sure that the shell on your path (named by -the `SHELL' environment variable) is publicly readable. Remember that -GDB uses the shell to start your program--some systems refuse to let -GDB debug child processes whose programs are not readable. + You can install `gdb' anywhere; it has no hardwired paths. However, +you should make sure that the shell on your path (named by the `SHELL' +environment variable) is publicly readable. Remember that GDB uses the +shell to start your program--some systems refuse to let GDB debug child +processes whose programs are not readable. Compiling GDB in Another Directory -================================== +=================================== If you want to run GDB versions for several host or target machines, -you'll need a different `gdb' 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' +you'll need a different `gdb' 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 then builds the `gdb' program specified there. To build `gdb' in a separate directory, run `configure' with the -`--srcdir' option to specify where to find the source. (Remember, -you'll also need to specify a path to find `configure' itself from -your working directory.) +`--srcdir' option to specify where to find the source. (You'll 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 4.4, you can build GDB in a separate + For example, with version 4.7, you can build GDB in a separate directory for a Sun 4 like this: - cd gdb-4.4 + cd gdb-4.7 mkdir ../gdb-sun4 cd ../gdb-sun4 - ../gdb-4.4/configure --srcdir=../gdb-4.4 sun4 + ../gdb-4.7/configure sun4 make When `configure' builds a configuration using a remote source @@ -220,7 +235,7 @@ directory, it creates a tree for the binaries with the same structure the example, you'd find the Sun 4 library `libiberty.a' in the directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. - One popular use for building several GDB configurations in separate + One popular reason to build several GDB configurations in separate directories is to configure GDB for cross-compiling (where GDB runs on one machine--the host--while debugging programs that run on another machine--the target). You specify a cross-debugging target by giving @@ -232,8 +247,8 @@ called `configure' (or one of its subdirectories). The `Makefile' generated by `configure' for each source directory also runs recursively. If you type `make' in a source directory such -as `gdb-4.4' (or in a separate configured directory configured with -`--srcdir=PATH/gdb-4.4'), you will build all the required libraries, +as `gdb-4.7' (or in a separate configured directory configured with +`--srcdir=PATH/gdb-4.7'), you will build all the required libraries, then build GDB. When you have multiple hosts or targets configured in separate @@ -243,7 +258,7 @@ 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 @@ -252,49 +267,10 @@ 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, but the equivalent full name is + For example, you can use the alias `sun4' as a HOST argument or in a +`--target=TARGET' option, but the equivalent full name is `sparc-sun-sunos4'. - The following table shows all the architectures, hosts, and OS -prefixes that `configure' recognizes in GDB version 4.4. Entries in -the "OS prefix" column ending in a `*' may be followed by a release -number. - - - ARCHITECTURE VENDOR OS prefix - ------------+--------------------------+--------------------------- - | | - 580 | altos hp | aix* msdos* - a29k | amd ibm | amigados newsos* - alliant | amdahl intel | aout nindy* - arm | aout isi | bout osf* - c1 | apollo little | bsd* sco* - c2 | att mips | coff sunos* - cray2 | bcs motorola | ctix* svr4 - h8300 | bout ncr | dgux* sym* - i386 | bull next | dynix* sysv* - i860 | cbm nyu | ebmon ultrix* - i960 | coff sco | esix* unicos* - m68000 | convergent sequent | hds unos* - m68k | convex sgi | hpux* uts - m88k | cray sony | irix* v88r* - mips | dec sun | isc* vms* - ns32k | encore unicom | kern vxworks* - pyramid | gould utek | mach* - romp | hitachi wrs | - rs6000 | | - sparc | | - tahoe | | - tron | | - vax | | - xmp | | - ymp | | - - *Warning:* `configure' can represent a very large number of - combinations of architecture, vendor, and OS. There is by no - means support available for all possible combinations! - The `configure' script accompanying GDB 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 @@ -302,51 +278,57 @@ 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-sunos4 + sparc-sun-sunos411 % sh config.sub sun3 - m68k-sun-sunos4 + m68k-sun-sunos411 % sh config.sub decstation - mips-dec-ultrix + mips-dec-ultrix42 % sh config.sub hp300bsd m68k-hp-bsd % sh config.sub i386v - i386-none-sysv - % sh config.sub i486v - *** Configuration "i486v" not recognized + i386-unknown-sysv + % sh config.sub i786v + Invalid configuration `i786v': machine `i786v' not recognized `config.sub' is also distributed in the GDB source directory -(`gdb-4.4', for version 4.4). +(`gdb-4.7', for version 4.7). `configure' Options -=================== +==================== - Here is a summary of all the `configure' options and arguments that -you might use for building GDB: + Here is a summary of the `configure' options and arguments that are +most often useful for building GDB. `configure' also has several other +options not listed here. *note : (configure.info)What Configure Does, +for a full explanation of `configure'. - configure [--destdir=DIR] [--srcdir=PATH] + configure [--help] + [--prefix=DIR] + [--srcdir=PATH] [--norecursion] [--rm] [--target=TARGET] HOST You may introduce options with a single `-' rather than `--' if you prefer; but you may abbreviate option names if you use `--'. -`--destdir=DIR' - DIR is an installation directory *path prefix*. After you - configure with this option, `make install' will install GDB as - `DIR/bin/gdb', and the libraries in `DIR/lib'. If you specify - `--destdir=/usr/local', for example, `make install' creates - `/usr/local/bin/gdb'. +`--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 GDB 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. + 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; @@ -356,9 +338,9 @@ prefer; but you may abbreviate option names if you use `--'. Remove the configuration that the other arguments specify. `--target=TARGET' - Configure GDB for cross-debugging programs running on the - specified TARGET. Without this option, GDB is configured to debug - programs that run on the same machine (HOST) as GDB itself. + Configure GDB for cross-debugging programs running on the specified + TARGET. Without this option, GDB is configured to debug programs + that run on the same machine (HOST) as GDB itself. There is no convenient way to generate a list of all available targets. @@ -370,11 +352,13 @@ prefer; but you may abbreviate option names if you use `--'. hosts. `configure' accepts other options, for compatibility with configuring -other GNU tools recursively; but these are the only options that -affect GDB or its supporting libraries. +other GNU tools recursively; but these are the only options that affect +GDB or its supporting libraries. + - Languages other than C +Languages other than C +======================= GDB provides some support for debugging C++ progams. Partial Modula-2 support is now in GDB. GDB should work with FORTRAN programs. (If you @@ -385,20 +369,22 @@ language. Pascal programs which use sets, subranges, file variables, or nested functions will not currently work. - Kernel debugging +Kernel debugging +================= I have't done this myself so I can't really offer any advice. Remote debugging over serial lines works fine, but the kernel debugging -code in here has not been tested in years. Van Jacobson claims to have -better kernel debugging. +code in here has not been tested in years. Van Jacobson has +better kernel debugging, but the UC lawyers won't let FSF have it. - Remote debugging +Remote debugging +================= -The files m68k-stub.c and i386-stub.c contain two examples of remote -stubs to be used with remote.c. They are designeded to run standalone -on a 68k or 386 cpu and communicate properly with the remote.c stub -over a serial line. +The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of +remote stubs to be used with remote.c. They are designed to run +standalone on a 68k, 386, or SPARC cpu and communicate properly with +the remote.c stub over a serial line. The file rem-multi.shar contains a general stub that can probably run on various different flavors of unix to allow debugging over a @@ -407,6 +393,7 @@ serial line from one machine to another. Some working remote interfaces for talking to existing ROM monitors are: remote-eb.c AMD 29000 "EBMON" + remote-hms.c Hitachi Micro Systems H8/300 monitor remote-nindy.c Intel 960 "Nindy" remote-adapt.c AMD 29000 "Adapt" remote-mm.c AMD 29000 "minimon" @@ -417,11 +404,12 @@ RPC library. This would be a useful starting point for other remote- via-ethernet back ends. - Reporting Bugs +Reporting Bugs +=============== The correct address for reporting bugs found in gdb is "bug-gdb@prep.ai.mit.edu". Please email all bugs to that address. -Please include the GDB version number (e.g. gdb-4.4), and how +Please include the GDB version number (e.g. gdb-4.7), and how you configured it (e.g. "sun4" or "mach386 host, i586-intel-synopsys target"). @@ -443,14 +431,15 @@ the compiler actually outputs or the debugger actually understands. If you port gdb to a new machine, please send the required changes to bug-gdb@prep.ai.mit.edu. There's lots of information about doing your -own port in the file gdb-4.4/gdb/doc/gdbint.texinfo, which you can +own port in the file gdb-4.7/gdb/doc/gdbint.texinfo, which you can print out, or read with `info' (see the Makefile.in there). If your changes are more than a few lines, obtain and send in a copyright assignment from gnu@prep.ai.mit.edu, as described in the section -`Writing Code for GDB'. +`Writing Code for GDB' below. - X Windows versus GDB +X Windows versus GDB +===================== xgdb is obsolete. We are not doing any development or support of it. @@ -462,7 +451,14 @@ an editor while debugging I suggest trying gdb-mode in gnu-emacs (Try typing M-x gdb RETURN). Comments on this mode are welcome. - Writing Code for GDB +Writing Code for GDB +===================== + +Documentation about GDB's internals is in the subdirectory doc, as +`gdbint.texinfo'. In particular, there is a `cookbook' there on how +to port GDB to a new machine. You can read it by hand, print it +by using TeX and texinfo, or process it into an `info' file for use +with Emacs' info mode or the standalone `info' program. We appreciate having users contribute code that is of general use, but for it to be included in future GDB releases it must be cleanly @@ -496,6 +492,12 @@ defined(SYSV). If you use an #ifdef on some symbol that is defined in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you have #include'd the relevant header file in that module! +There is a list of all known `feature-test macros' in gdbint.texinfo. +Each such macro should be defined (or left undefined) in a host-dependent, +target-dependent, or native-dependent include file. Not all of the +macros are cleanly separated this way, yet. As you make changes, move +the code toward cleanliness. + It is better to replace entire routines which may be system-specific, rather than put in a whole bunch of hooks which are probably not going to be helpful for any purpose other than your changes. For example, @@ -531,7 +533,8 @@ to use infptrace.c at all. The same was true of core_file_command and exec_file_command. - Debugging gdb with itself +Debugging gdb with itself +========================== If gdb is limping on your machine, this is the preferred way to get it fully functional. Be warned that in some ancient Unix systems, like |