| README for gdb-4.18 release |
| Updated 4 Apr 1999 by Jim Blandy |
| |
| This is GDB, the GNU source-level debugger. |
| A summary of new features is in the file `NEWS'. |
| |
| See the GDB home page at http://sourceware.cygnus.com/gdb/ for up to |
| date release information, mailing list links and archives, etc. |
| |
| |
| 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 other libraries all have directories of their own |
| underneath the gdb-4.18 directory. The idea is that a variety of GNU |
| tools can share a common copy of these things. Be aware of variation |
| over time--for example don't try to build gdb with a copy of bfd from |
| a release other than the gdb release (such as a binutils or gas |
| release), especially if the releases are more than a few weeks apart. |
| 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.18.tar.gz file, you'll find a directory |
| called `gdb-4.18', which contains: |
| |
| COPYING config.sub* libiberty/ opcodes/ |
| COPYING.LIB configure* mmalloc/ readline/ |
| Makefile.in configure.in move-if-change* sim/ |
| README etc/ mpw-README texinfo/ |
| bfd/ gdb/ mpw-build.in utils/ |
| config/ include/ mpw-config.in |
| config.guess* install.sh* mpw-configure |
| |
| To build GDB, you can just do: |
| |
| cd gdb-4.18 |
| ./configure |
| make |
| cp gdb/gdb /usr/local/bin/gdb (or wherever you want) |
| |
| This will configure and build all the libraries as well as GDB. |
| 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. |
| |
| GDB requires an ANSI C compiler. If you do not have an ANSI C |
| compiler for your system, you may be able to download and install the |
| GNU CC compiler. It is available via anonymous FTP from ftp.gnu.org, |
| in /pub/gnu/gcc (as a URL, that's ftp://ftp.gnu.org/pub/gnu/gcc). |
| |
| GDB can be used as a cross-debugger, running on a machine of one type |
| while debugging a program running on a machine of another type. See below. |
| |
| |
| More Documentation |
| ****************** |
| |
| 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/doc' subdirectory. The main Info file is |
| `gdb-4.18/gdb/doc/gdb.info', and it refers to subordinate files 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'. |
| |
| If you have `makeinfo' installed, and are in the top level GDB |
| source directory (`gdb-4.18', in the case of version 4.18), you can make |
| the Info file by typing: |
| |
| cd gdb/doc |
| make info |
| |
| If you want to typeset and print copies of this manual, you need |
| TeX, a program to print its DVI output files, and `texinfo.tex', the |
| Texinfo definitions file. This file is included in the GDB |
| distribution, in the directory `gdb-4.18/texinfo'. |
| |
| TeX is a typesetting program; it does not print files directly, but |
| produces output files called DVI files. To print a typeset document, |
| you need a program to print DVI files. If your system has TeX |
| installed, chances are it has such a program. The precise command to |
| use depends on your system; `lpr -d' is common; another (for PostScript |
| devices) is `dvips'. The DVI print command may require a file name |
| without any extension or 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 |
| `gdb-4.18/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.18/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. |
| |
| 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.18 distribution is in the `gdb-4.18' |
| directory. That directory contains: |
| |
| `gdb-4.18/{COPYING,COPYING.LIB}' |
| Standard GNU license files. Please read them. |
| |
| `gdb-4.18/bfd' |
| source for the Binary File Descriptor library |
| |
| `gdb-4.18/config*' |
| script for configuring GDB, along with other support files |
| |
| `gdb-4.18/gdb' |
| the source specific to GDB itself |
| |
| `gdb-4.18/include' |
| GNU include files |
| |
| `gdb-4.18/libiberty' |
| source for the `-liberty' free software library |
| |
| `gdb-4.18/mmalloc' |
| source for the GNU memory-mapped malloc package |
| |
| `gdb-4.18/opcodes' |
| source for the library of opcode tables and disassemblers |
| |
| `gdb-4.18/readline' |
| source for the GNU command-line interface |
| NOTE: The readline library is compiled for use by GDB, but will |
| not be installed on your system when "make install" is issued. |
| |
| `gdb-4.18/sim' |
| source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc) |
| |
| `gdb-4.18/intl' |
| source for the GNU gettext library, for internationalization. |
| This is slightly modified from the standalone gettext |
| distribution you can get from GNU. |
| |
| `gdb-4.18/texinfo' |
| The `texinfo.tex' file, which you need in order to make a printed |
| manual using TeX. |
| |
| `gdb-4.18/etc' |
| Coding standards, useful files for editing GDB, and other |
| miscellanea. |
| |
| `gdb-4.18/utils' |
| A grab bag of random utilities. |
| |
| |
| 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.18' directory. |
| |
| First switch to the `gdb-VERSION-NUMBER' source directory if you are |
| not already in it; then run `configure'. |
| |
| For example: |
| |
| cd gdb-4.18 |
| ./configure |
| make |
| |
| Running `configure' 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, |
| you may need to run `sh' on it explicitly: |
| |
| sh configure |
| |
| If you run `configure' from a directory that contains source |
| directories for multiple libraries or programs, such as the `gdb-4.18' |
| source directory for version 4.18, `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. |
| |
| For example, with version 4.18, type the following to configure only |
| the `bfd' subdirectory: |
| |
| cd gdb-4.18/bfd |
| ../configure |
| |
| 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 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 correctly (GNU `make' and SunOS 'make' are two that should), |
| running `make' in each of these directories 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. (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 4.18, you can build GDB in a separate |
| directory for a Sun 4 like this: |
| |
| cd gdb-4.18 |
| mkdir ../gdb-sun4 |
| cd ../gdb-sun4 |
| ../gdb-4.18/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 `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. |
| |
| 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 |
| 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 `gdb-4.18' (or in a separate configured directory configured with |
| `--srcdir=PATH/gdb-4.18'), you will build all the required libraries, |
| and then build GDB. |
| |
| 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 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 |
| 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.1.1 |
| % sh config.sub sun3 |
| m68k-sun-sunos4.1.1 |
| % sh config.sub decstation |
| mips-dec-ultrix4.2 |
| % sh config.sub hp300bsd |
| m68k-hp-bsd |
| % sh config.sub i386v |
| i386-pc-sysv |
| % sh config.sub i786v |
| Invalid configuration `i786v': machine `i786v' not recognized |
| |
| `config.sub' is also distributed in the GDB source directory |
| (`gdb-4.18', for version 4.18). |
| |
| |
| `configure' options |
| =================== |
| |
| 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 [--help] |
| [--prefix=DIR] |
| [--srcdir=PATH] |
| [--norecursion] [--rm] |
| [--enable-build-warnings] |
| [--target=TARGET] |
| [--host=HOST] |
| [HOST] |
| |
| 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 compatibly 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. |
| |
| `--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. |
| |
| `--enable-build-warnings' |
| When building the GDB sources, ask the compiler to warn about any |
| code which looks even vaguely suspicious. You should only using |
| this feature if you're compiling with GNU CC. It passes the |
| following flags: |
| -Wall |
| -Wpointer-arith |
| -Wstrict-prototypes |
| -Wmissing-prototypes |
| -Wmissing-declarations |
| |
| `--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. |
| |
| There is no convenient way to generate a list of all available |
| targets. |
| |
| `--host=HOST' |
| Configure GDB to run on the specified HOST. |
| |
| There is no convenient way to generate a list of all available |
| hosts. |
| |
| `HOST ...' |
| Same as `--host=HOST'. If you omit this, GDB will guess; it's |
| quite accurate. |
| |
| `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. |
| |
| |
| Languages other than C |
| ======================= |
| |
| See the GDB manual (gdb/doc/gdb.texinfo) for information on this. |
| |
| |
| 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 has |
| better kernel debugging, but the UC lawyers won't let FSF have it. |
| |
| |
| Remote debugging |
| ================= |
| |
| 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 an m68k, i386, or SPARC cpu and communicate properly with |
| the remote.c stub over a serial line. |
| |
| The directory gdb/gdbserver/ contains `gdbserver', a program that |
| allows remote debugging for Unix applications. gdbserver is only |
| supported for some native configurations, including Sun 3, Sun 4, |
| and Linux. |
| |
| There are a number of remote interfaces for talking to existing ROM |
| monitors and other hardware: |
| |
| remote-adapt.c AMD 29000 "Adapt" |
| remote-array.c Array Tech RAID controller |
| remote-bug.c Motorola BUG monitor |
| remote-d10v.c GDB protocol, talking to a d10v chip |
| remote-e7000.c Hitachi E7000 ICE |
| remote-eb.c AMD 29000 "EBMON" |
| remote-es.c Ericsson 1800 monitor |
| remote-est.c EST emulator |
| remote-hms.c Hitachi Micro Systems H8/300 monitor |
| remote-mips.c MIPS remote debugging protocol |
| remote-mm.c AMD 29000 "minimon" |
| remote-nindy.c Intel 960 "Nindy" |
| remote-nrom.c NetROM ROM emulator |
| remote-os9k.c PC running OS/9000 |
| remote-rdi.c ARM with Angel monitor |
| remote-rdp.c ARM with Demon monitor |
| remote-sds.c PowerPC SDS monitor |
| remote-sim.c Generalized simulator protocol |
| remote-st.c Tandem ST-2000 monitor |
| remote-udi.c AMD 29000 using the AMD "Universal Debug Interface" |
| remote-vx.c VxWorks realtime kernel |
| |
| Remote-vx.c and the vx-share subdirectory contain a remote interface for the |
| VxWorks realtime kernel, which communicates over TCP using the Sun |
| RPC library. This would be a useful starting point for other remote- |
| via-ethernet back ends. |
| |
| Remote-udi.c and the 29k-share subdirectory contain a remote interface |
| for AMD 29000 programs, which uses the AMD "Universal Debug Interface". |
| This allows GDB to talk to software simulators, emulators, and/or bare |
| hardware boards, via network or serial interfaces. Note that GDB only |
| provides an interface that speaks UDI, not a complete solution. You |
| will need something on the other end that also speaks UDI. |
| |
| |
| Reporting Bugs |
| =============== |
| |
| The correct address for reporting bugs found in gdb is |
| "bug-gdb@gnu.org". Please email all bugs, and all requests for |
| help with GDB, to that address. Please include the GDB version number |
| (e.g., gdb-4.18), and how you configured it (e.g., "sun4" or "mach386 |
| host, i586-intel-synopsys target"). Since GDB now supports so many |
| different configurations, it is important that you be precise about this. |
| If at all possible, you should include the actual banner that GDB prints |
| when it starts up, or failing that, the actual configure command that |
| you used when configuring GDB. |
| |
| For more information on how/whether to report bugs, see the GDB Bugs |
| section of the GDB manual (gdb/doc/gdb.texinfo). |
| |
| Known bugs: |
| |
| * Under Ultrix 4.2 (DECstation-3100) or Alphas under OSF/1, we have |
| seen problems with backtraces after interrupting the inferior out |
| of a read(). The problem is caused by ptrace() returning an |
| incorrect value for the frame pointer register (register 15 or |
| 30). As far as we can tell, this is a kernel problem. Any help |
| with this would be greatly appreciated. |
| |
| * Under Ultrix 4.4 (DECstation-3100), setting the TERMCAP environment |
| variable to a string without a trailing ':' can cause GDB to dump |
| core upon startup. Although the core file makes it look as though |
| GDB code failed, the crash actually occurs within a call to the |
| termcap library function tgetent(). The problem can be solved by |
| using the GNU Termcap library. |
| |
| Alphas running OSF/1 (versions 1.0 through 2.1) have the same buggy |
| termcap code, but GDB behaves strangely rather than crashing. |
| |
| * On DECstations there are warnings about shift counts out of range in |
| various BFD modules. None of them is a cause for alarm, they are actually |
| a result of bugs in the DECstation compiler. |
| |
| * Notes for the DEC Alpha using OSF/1: |
| The debugging output of native cc has two known problems; we view these |
| as compiler bugs. |
| The linker miscompacts symbol tables, which causes gdb to confuse the |
| type of variables or results in `struct <illegal>' type outputs. |
| dbx has the same problems with those executables. A workaround is to |
| specify -Wl,-b when linking, but that will increase the executable size |
| considerably. |
| If a structure has incomplete type in one file (e.g., "struct foo *" |
| without a definition for "struct foo"), gdb will be unable to find the |
| structure definition from another file. |
| It has been reported that the Ultrix 4.3A compiler on decstations has the |
| same problems. |
| |
| * Notes for Solaris 2.x, using the SPARCworks cc compiler: |
| You have to compile your program with the -xs option of the SPARCworks |
| compiler to be able to debug your program with gdb. |
| Under Solaris 2.3 you also need patch 101409-03 (Jumbo linker patch). |
| Under Solaris 2.2, if you have patch 101052 installed, make sure |
| that it is at least at revision 101052-06. |
| |
| * Under Irix 5 for SGIs, you must have installed the `compiler_dev.hdr' |
| subsystem that is on the IDO CD, otherwise you will get complaints |
| that certain files such as `/usr/include/syms.h' cannot be found. |
| |
| * Notes for BSD/386: |
| To compile gdb-4.18 on BSD/386, you must run the configure script and |
| its subscripts with bash. Here is an easy way to do this: |
| |
| bash -c 'CONFIG_SHELL=/bin/bash ./configure' |
| |
| (configure will report i386-unknown-bsd). Then, compile with the |
| standard "make" command. |
| |
| GDB can produce warnings about symbols that it does not understand. By |
| default, these warnings are disabled. You can enable them by executing |
| `set complaint 10' (which you can put in your ~/.gdbinit if you like). |
| I recommend doing this if you are working on a compiler, assembler, |
| linker, or GDB, since it will point out problems that you may be able |
| to fix. Warnings produced during symbol reading indicate some mismatch |
| between the object file and GDB's symbol reading code. In many cases, |
| it's a mismatch between the specs for the object file format, and what |
| the compiler actually outputs or the debugger actually understands. |
| |
| |
| X Windows versus GDB |
| ===================== |
| |
| You should check out DDD, the Data Display Debugger. Here's the blurb |
| from the DDD web site, http://www.cs.tu-bs.de/softech/ddd: |
| |
| The Data Display Debugger (DDD) is a popular graphical user |
| interface for command-line debuggers such as GDB, DBX, JDB, WDB, |
| XDB, the Perl debugger, and the Python debugger. Besides ``usual'' |
| front-end features such as viewing source texts, DDD has become |
| famous through its interactive graphical data display, where data |
| structures are displayed as graphs. A simple mouse click |
| dereferences pointers or views structure contents, updated each |
| time the program stops. Using DDD, you can reason about your |
| application by watching its data, not just by viewing it execute |
| lines of source code. |
| |
| Emacs users will very likely enjoy the Grand Unified Debugger mode; |
| try typing `M-x gdb RET'. |
| |
| Those interested in experimenting with a new kind of gdb-mode |
| should load gdb/gdba.el into GNU Emacs 19.25 or later. Comments |
| on this mode are also welcome. |
| |
| |
| Writing Code for GDB |
| ===================== |
| |
| There is a lot of information about writing code for GDB in the |
| internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. 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. |
| |
| If you are pondering writing anything but a short patch, especially |
| take note of the information about copyrights in the node Submitting |
| Patches. It can take quite a while to get all the paperwork done, so |
| we encourage you to start that process as soon as you decide you are |
| planning to work on something, or at least well ahead of when you |
| think you will be ready to submit the patches. |
| |
| |
| GDB Testsuite |
| ============= |
| |
| There is a DejaGNU based testsuite available for testing your newly |
| built GDB, or for regression testing GDBs with local modifications. |
| |
| Running the testsuite requires the prior installation of DejaGNU, |
| which is generally available via ftp; you'll need a pretty recent |
| release. Once DejaGNU is installed, you can run the tests in one of |
| two ways: |
| |
| (1) cd gdb-4.18/gdb (assuming you also unpacked gdb) |
| make check |
| |
| or |
| |
| (2) cd gdb-4.18/gdb/testsuite |
| make site.exp (builds the site specific file) |
| runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate) |
| |
| The second method gives you slightly more control in case of problems with |
| building one or more test executables or if you are using the testsuite |
| 'standalone', without it being part of the GDB source tree. |
| |
| See the DejaGNU documentation for further details. |
| |
| |
| (this is for editing this file with GNU emacs) |
| Local Variables: |
| mode: text |
| End: |