X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2FREADME;h=33516ac9ea013cd3f66f91fc6a79dfe157f7f847;hb=64c311498e46cef6b70aa88577e7d7c382e0f7cc;hp=e8759c1d55e440ea6a04d6d1729bf4108d61bc1a;hpb=299ffc6418d380c1a2145f755b6a724feabca81b;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/README b/gdb/README index e8759c1d55..33516ac9ea 100644 --- a/gdb/README +++ b/gdb/README @@ -1,5 +1,4 @@ - README for gdb-5.3 release - Updated 5th September, 2002 by Andrew Cagney + README for GDB release This is GDB, the GNU source-level debugger. @@ -17,34 +16,27 @@ bugs. Unpacking and Installation -- quick overview ========================== - In this release, the GDB debugger sources, the generic GNU include + The release is provided as a gzipped tar file called +'gdb-VERSION.tar.gz', where VERSION is the version of GDB. + + 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-5.3 directory. The idea is that a variety of GNU +underneath the gdb-VERSION 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 release), +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 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-5.3.tar.gz file, you'll find a directory -called `gdb-5.3', which contains: - - COPYING config.sub intl missing opcodes - COPYING.LIB configure libiberty mkinstalldirs readline - Makefile.in configure.in libtool.m4 mmalloc sim - README djunpack.bat ltcf-c.sh move-if-change symlink-tree - bfd etc ltcf-cxx.sh mpw-README texinfo - config gdb ltcf-gcj.sh mpw-build.in utils - config-ml.in gettext.m4 ltconfig mpw-config.in ylwrap - config.guess include ltmain.sh mpw-configure - config.if install-sh md5.sum mpw-install + When you unpack the gdb-VERSION.tar.gz file, it will create a +source directory called `gdb-VERSION'. You can build GDB right in the source directory: - cd gdb-5.3 + cd gdb-VERSION ./configure make cp gdb/gdb /usr/local/bin/gdb (or wherever you want) @@ -58,24 +50,44 @@ You can build GDB in any empty build directory: mkdir build cd build - /gdb-5.3/configure + /gdb-VERSION/configure make cp gdb/gdb /usr/local/bin/gdb (or wherever you want) (Building GDB with DJGPP tools for MS-DOS/MS-Windows is slightly -different; see the file gdb-5.3/gdb/config/djgpp/README for details.) +different; see the file gdb-VERSION/gdb/config/djgpp/README for details.) 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., `./configure sun4' or `./configure decstation'. - If you get compiler errors during this stage, see the `Reporting + Make sure that your 'configure' line ends in 'gdb-VERSION/configure': + + /berman/migchain/source/gdb-VERSION/configure # RIGHT + /berman/migchain/source/gdb-VERSION/gdb/configure # WRONG + + The GDB package contains several subdirectories, such as 'gdb', +'bfd', and 'readline'. If your 'configure' line ends in +'gdb-VERSION/gdb/configure', then you are configuring only the gdb +subdirectory, not the whole GDB package. This leads to build errors +such as: + + make: *** No rule to make target `../bfd/bfd.h', needed by `gdb.o'. Stop. + + If you get other compiler errors during this stage, see the `Reporting Bugs' section below; there are a few known problems. GDB requires an ISO C (ANSI C) compiler. If you do not have an ISO C compiler for your system, you may be able to download and install the GNU CC compiler. It is available via anonymous FTP from the -directory `ftp://ftp.gnu.org/pub/gnu/gcc'. +directory `ftp://ftp.gnu.org/pub/gnu/gcc'. GDB also requires an ISO +C standard library. The GDB remote server, GDBserver, builds with some +non-ISO standard libraries - e.g. for Windows CE. + + GDB uses Expat, an XML parsing library, to implement some target-specific +features. Expat will be linked in if it is available at build time, or +those features will be disabled. The latest version of Expat should be +available from `http://expat.sourceforge.net'. 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. @@ -94,7 +106,7 @@ 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-5.3/gdb/doc/gdb.info', and it refers to subordinate files +`gdb-VERSION/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 @@ -106,8 +118,8 @@ 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-5.3', in the case of version 5.3), you can make -the Info file by typing: +source directory (`gdb-VERSION'), you can make the Info file by +typing: cd gdb/doc make info @@ -115,7 +127,7 @@ the Info file by typing: 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-5.3/texinfo'. +distribution, in the directory `gdb-VERSION/texinfo'. TeX is a typesetting program; it does not print files directly, but produces output files called DVI files. To print a typeset document, @@ -129,11 +141,11 @@ without any extension or a `.dvi' extension. 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-5.3/texinfo' directory. +`gdb-VERSION/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-5.3/gdb') and then type: +and print this manual. First switch to the `gdb' subdirectory of +the main source directory (for example, to `gdb-VERSION/gdb') and then type: make doc/gdb.dvi @@ -153,74 +165,58 @@ 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 5.3 distribution is in the `gdb-5.3' -directory. That directory contains: +a single directory. That directory contains: -`gdb-5.3/{COPYING,COPYING.LIB}' +`gdb-VERSION/{COPYING,COPYING.LIB}' Standard GNU license files. Please read them. -`gdb-5.3/bfd' +`gdb-VERSION/bfd' source for the Binary File Descriptor library -`gdb-5.3/config*' +`gdb-VERSION/config*' script for configuring GDB, along with other support files -`gdb-5.3/gdb' +`gdb-VERSION/gdb' the source specific to GDB itself -`gdb-5.3/include' +`gdb-VERSION/include' GNU include files -`gdb-5.3/libiberty' +`gdb-VERSION/libiberty' source for the `-liberty' free software library -`gdb-5.3/mmalloc' - source for the GNU memory-mapped malloc package - -`gdb-5.3/opcodes' +`gdb-VERSION/opcodes' source for the library of opcode tables and disassemblers -`gdb-5.3/readline' +`gdb-VERSION/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-5.3/sim' +`gdb-VERSION/sim' source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc) -`gdb-5.3/intl' - source for the GNU gettext library, for internationalization. - This is slightly modified from the standalone gettext - distribution you can get from GNU. - -`gdb-5.3/texinfo' +`gdb-VERSION/texinfo' The `texinfo.tex' file, which you need in order to make a printed manual using TeX. -`gdb-5.3/etc' +`gdb-VERSION/etc' Coding standards, useful files for editing GDB, and other miscellanea. -`gdb-5.3/utils' - A grab bag of random utilities. - Note: the following instructions are for building GDB on Unix or Unix-like systems. Instructions for building with DJGPP for MS-DOS/MS-Windows are in the file gdb/config/djgpp/README. 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-5.3' directory. +from the `gdb-VERSION' directory. - First switch to the `gdb-VERSION-NUMBER' source directory if you are + First switch to the `gdb-VERSION' source directory if you are not already in it; then run `configure'. For example: - cd gdb-5.3 + cd gdb-VERSION ./configure make @@ -236,20 +232,9 @@ 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-5.3' -source directory for version 5.3, `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 5.3, type the following to configure only -the `bfd' subdirectory: - - cd gdb-5.3/bfd - ../configure +directories for multiple libraries or programs, `configure' creates +configuration files for every directory level underneath (unless +you tell it not to, with the `--norecursion' option). 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' @@ -277,13 +262,13 @@ 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 5.3, you can build GDB in a separate + For example, you can build GDB in a separate directory for a Sun 4 like this: - cd gdb-5.3 + cd gdb-VERSION mkdir ../gdb-sun4 cd ../gdb-sun4 - ../gdb-5.3/configure + ../gdb-VERSION/configure make When `configure' builds a configuration using a remote source @@ -304,8 +289,8 @@ 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-5.3' (or in a separate configured directory configured with -`--srcdir=PATH/gdb-5.3'), you will build all the required libraries, +as `gdb-VERSION' (or in a separate configured directory configured with +`--srcdir=PATH/gdb-VERSION'), you will build all the required libraries, and then build GDB. When you have multiple hosts or targets configured in separate @@ -347,8 +332,7 @@ you can use it to test your guesses on abbreviations--for example: % sh config.sub i786v Invalid configuration `i786v': machine `i786v' not recognized -`config.sub' is also distributed in the GDB source directory -(`gdb-5.3', for version 5.3). +`config.sub' is also distributed in the GDB source directory. `configure' options @@ -390,6 +374,16 @@ prefer; but you may abbreviate option names if you use `--'. directories under the working directory in parallel to the source directories below PATH. +`--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. + `--norecursion' Configure only the directory level where `configure' is executed; do not propagate configuration to subdirectories. @@ -410,6 +404,11 @@ prefer; but you may abbreviate option names if you use `--'. -Wparentheses -Wpointer-arith +`--enable-werror' + Treat compiler warnings as werrors. Use this only with GCC. It + adds the -Werror flag to the compiler, which will fail the + compilation if the compiler outputs any warning messages. + `--target=TARGET' Configure GDB for cross-debugging programs running on the specified TARGET. Without this option, GDB is configured to debug programs @@ -418,15 +417,95 @@ prefer; but you may abbreviate option names if you use `--'. 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. +`--with-gdb-datadir=PATH' + Set the GDB-specific data directory. GDB will look here for + certain supporting files or scripts. This defaults to the `gdb' + subdirectory of `datadir' (which can be set using `--datadir'). + +`--with-relocated-sources=DIR' + Sets up the default source path substitution rule so that + directory names recorded in debug information will be + automatically adjusted for any directory under DIR. DIR should + be a subdirectory of GDB's configured prefix, the one mentioned + in the `--prefix' or `--exec-prefix' options to configure. This + option is useful if GDB is supposed to be moved to a different + place after it is built. + +`--enable-64-bit-bfd' + Enable 64-bit support in BFD on 32-bit hosts. + +`--disable-gdbmi' + Build GDB without the GDB/MI machine interface. + +`--enable-tui' + Build GDB with the text-mode full-screen user interface (TUI). + Requires a curses library (ncurses and cursesX are also + supported). + +`--enable-gdbtk' + Build GDB with the gdbtk GUI interface. Requires TCL/Tk to be + installed. + +`--with-libunwind-ia64' + Use the libunwind library for unwinding function call stack on ia64 + target platforms. + See http://www.nongnu.org/libunwind/index.html for details. + +`--with-curses' + Use the curses library instead of the termcap library, for + text-mode terminal operations. + +`--enable-profiling' Enable profiling of GDB itself. Necessary if you + want to use the "maint set profile" command for profiling GDB. + Requires the functions `monstartup' and `_mcleanup' to be present + in the standard C library used to build GDB, and also requires a + compiler that supports the `-pg' option. + +`--with-system-readline' + Use the readline library installed on the host, rather than the + library supplied as part of GDB tarball. + +`--with-expat' + Build GDB with the libexpat library. (Done by default if + libexpat is installed and found at configure time.) This library + is used to read XML files supplied with GDB. If it is + unavailable, some features, such as remote protocol memory maps, + target descriptions, and shared library lists, that are based on + XML files, will not be available in GDB. If your host does not + have libexpat installed, you can get the latest version from + http://expat.sourceforge.net. + +`--with-python[=PATH]' + Build GDB with Python scripting support. (Done by default if + libpython is present and found at configure time.) Python makes + GDB scripting much more powerful than the restricted CLI + scripting language. If your host does not have Python installed, + you can find it on http://www.python.org/download/. The oldest + version of Python supported by GDB is 2.4. The optional argument + PATH says where to find the Python headers and libraries; the + configure script will look in PATH/include for headers and in + PATH/lib for the libraries. + +`--without-included-regex' + Don't use the regex library included with GDB (as part of the + libiberty library). This is the default on hosts with version 2 + of the GNU C library. + +`--with-sysroot=DIR' + Use DIR as the default system root directory for libraries whose + file names begin with `/lib' or `/usr/lib'. (The value of DIR + can be modified at run time by using the "set sysroot" command.) + If DIR is under the GDB configured prefix (set with `--prefix' or + `--exec-prefix' options), the default system root will be + automatically adjusted if and when GDB is moved to a different + location. + +`--with-system-gdbinit=FILE' + Configure GDB to automatically load a system-wide init file. + FILE should be an absolute file name. If FILE is in a directory + under the configured prefix, and GDB is moved to another location + after being built, the location of the system-wide init file will + be adjusted accordingly. `configure' accepts other options, for compatibility with configuring other GNU tools recursively; but these are the only options that affect @@ -442,45 +521,20 @@ 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 +allows remote debugging for Unix applications. GDBserver is only supported for some native configurations, including Sun 3, Sun 4, and Linux. +The file gdb/gdbserver/README includes further notes on GDBserver; in +particular, it explains how to build GDBserver for cross-debugging +(where GDBserver runs on the target machine, which is of a different +architecture than the host machine running GDB). 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-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 in GDB @@ -494,13 +548,13 @@ method is to use the World Wide Web: As an alternative, the bug report can be submitted, via e-mail, to the address "bug-gdb@gnu.org". - When submitting a bug, please include the GDB version number (e.g., -gdb-5.3), and how you configured it (e.g., "sun4" or "mach386 host, + When submitting a bug, please include the GDB version number, 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. +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 Reporting Bugs chapter of the GDB manual (gdb/doc/gdb.texinfo). @@ -512,7 +566,7 @@ Graphical interface to GDB -- X Windows, MS Windows Several graphical interfaces to GDB are available. You should check: - http://www.gnu.org/software/gdb/gui/ + http://www.gnu.org/software/gdb/links/ for an up-to-date list. @@ -550,26 +604,60 @@ ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot. Once DejaGNU is installed, you can run the tests in one of the following ways: - (1) cd gdb-5.3 + (1) cd gdb-VERSION make check-gdb or - (2) cd gdb-5.3/gdb + (2) cd gdb-VERSION/gdb make check or - (3) cd gdb-5.3/gdb/testsuite + (3) cd gdb-VERSION/gdb/testsuite make site.exp (builds the site specific file) runtest -tool gdb GDB=../gdb (or GDB= as appropriate) +When using a `make'-based method, you can use the Makefile variable +`RUNTESTFLAGS' to pass flags to `runtest', e.g.: + + make RUNTESTFLAGS=--directory=gdb.cp check + +If you use GNU make, you can use its `-j' option to run the testsuite +in parallel. This can greatly reduce the amount of time it takes for +the testsuite to run. In this case, if you set `RUNTESTFLAGS' then, +by default, the tests will be run serially even under `-j'. You can +override this and force a parallel run by setting the `make' variable +`FORCE_PARALLEL' to any non-empty value. Note that the parallel `make +check' assumes that you want to run the entire testsuite, so it is not +compatible with some dejagnu options, like `--directory'. + The last 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. + +Copyright and License Notices +============================= + +Most files maintained by the GDB Project contain a copyright notice +as well as a license notice, usually at the start of the file. + +To reduce the length of copyright notices, consecutive years in the +copyright notice can be combined into a single range. For instance, +the following list of copyright years... + + 1986, 1988, 1989, 1991-1993, 1999, 2000, 2007, 2008, 2009, 2010, 2011 + +... is abbreviated into: + + 1986, 1988-1989, 1991-1993, 1999-2000, 2007-2011 + +Every year of each range, inclusive, is a copyrightable year that +could be listed individually. + (this is for editing this file with GNU emacs) Local Variables: