From 846058edd87298c2397b11ee77400697cb91e089 Mon Sep 17 00:00:00 2001 From: John Gilmore Date: Sat, 24 Aug 1991 00:15:18 +0000 Subject: [PATCH] Update README. --- gdb/README | 415 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 269 insertions(+), 146 deletions(-) diff --git a/gdb/README b/gdb/README index d052c996022..a6e18ebf34e 100644 --- a/gdb/README +++ b/gdb/README @@ -1,119 +1,146 @@ - README for gdb-3.98 beta release - John Gilmore 31 July 91 - -This is GDB, the GNU source-level debugger, presently running under -un*x. This is a beta test version of GDB version 4, and has not been -extensively tested. It surely has some bugs, both bugs that were -present in version 3, and new bugs. If your favorite bugfix is not -yet present here, I encourage you to port it into this version and -then send the diffs to bug-gdb@prep.ai.mit.edu. + README for gdb-4.0 release + John Gilmore 23 Aug 91 +This is GDB, the GNU source-level debugger, presently running under un*x. A summary of features new since gdb-3.5 is in the file `WHATS.NEW'. - Unpacking and Installation +Unpacking and Installation -- quick overview +========================== This release moves the generic GNU include files, the BFD ("binary file description") library, the getopt routines, obstacks, and the readline -library into the parent directory of gdb. The idea is that a variety -of GNU tools can share a common copy of these things. +library into the parent directory of the gdb source files. The idea is +that a variety of GNU tools can share a common copy of these things. -These generic files are packaged separately from GDB, in a tar file -called "bfd.ilrt-3.98.tar.Z". ("ilrt" stands for include, libiberty, -readline, texinfo). Unpack that tar file in the same directory in -which you unpacked the gdb-3.98.tar.Z file, so that for example the -'bfd' directory sits next to the 'gdb' directory. The whole top-level -directory will look like this with `ls -F': +These generic files are packaged together with the directory containing +the source code for GDB, for now. When you unpack the gdb-4.0.tar.Z +file, you'll get a directory called `gdb-4.0', which contains: - Makefile.in configure* include/ texinfo/ - README.configure configure.in libiberty/ - bfd/ gdb/ readline/ + Makefile.in bfd/ configure.in libiberty/ + README config.sub* gdb/ readline/ + README.configure configure* include/ texinfo/ -Once you have this stuff unpacked, and your current directory is here, -you can type: +To build GDB, you can just do: + cd gdb-4.0 ./configure HOSTNAME make + cp gdb/gdb /usr/local/bin/gdb (or wherever you want) -and all the libraries, as well as GDB will be configured and built. +This will configure and build all the libraries as well as GDB. If you get compiler warnings during this stage, see the `Reporting Bugs' section below; there are a few known problems. 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. You -configure it this way by specifying `./configure host -target=target'; -see below. +while debugging a program running on a machine of another type. See below. + + +More Documentation +================== + + The GDB 4.0 release includes an already-formatted reference card, ready +for printing on a PostScript printer, as `gdb-4.0/gdb/refcard.ps'. It +uses the most common PostScript fonts: the Times family, Courier, +and Symbol. If you have a PostScript printer you can print the +reference card by just sending `refcard.ps' to the printer. + + The release also includes the online Info version of the manual +already formatted: the main Info file is `gdb-4.0/gdb/gdb.info', and +it refers to subordinate files matching `gdb.info*' in the same +directory. + + If you want to make these Info files yourself from the GDB +manual's source, you need the GNU `makeinfo' program. Once you have +it, you can type + + cd gdb-4.0/gdb + make gdb.info + +to make the Info file. + + If you want to format and print copies of this manual, you need +several things: + + * TeX, the public domain typesetting program written by Donald + Knuth, must be installed on your system and available through + your execution path. + + * `gdb-4.0/texinfo': TeX macros defining the GNU Documentation + Format. + + * *A DVI output program.* TeX doesn't actually make marks on + paper; it produces output files called DVI files. If your + system has TeX installed, chances are it has a program for + printing out these files; one popular example is `dvips', which + can print DVI files on PostScript printers. + +Once you have these things, you can type + cd gdb-4.0/gdb + make gdb.dvi - More Documentation +to format the text of this manual, and print it with the usual output +method for TeX DVI files at your site. -The GDB manual is much expanded and improved. For online browsing, -gdb/gdb.info is the main file, and there are gdb/gdb.info-1 through -6 -files that can be installed into your main `info' tree. If you want a -printed version of the manual, you can run, from the GDB source -directory, + If you want to print the reference card, but don't have a PostScript +printer, or want to print using Computer Modern fonts instead, you can +still print it if you have TeX. Format the reference card by typing - make gdb.dvi + cd gdb-4.0/gdb + make refcard.dvi -to make the TeX device-independent output file. This assumes you have -a running TeX on your system. The source for the GDB manual is in -doc/gdb.texinfo (and a few other files it includes), provided with -this distribution. The Makefile attempts to use the texinfo.tex -supplied as part of the BFD-and-libraries tar file, since the manual -uses Texinfo-2 which is not in common use yet. +The GDB reference card is designed to print in landscape mode on US +"letter" size paper; that is, on a sheet 11 inches wide by 8.5 +inches high. You will need to specify this form of printing as an +option to your DVI output program. - Configuration Details (extracted from gdb.texinfo) +Installing GDB +============== - GDB is distributed with a `configure' script that automates the -process of preparing GDB for installation; you can then use `make' -to build the `gdb' program. + 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 `configure' script that's specific to GDB is distributed in -the main GDB source directory. However, building GDB also requires -several other directories of source common to multiple GNU programs. -These directories (GNU libraries and includes) are distributed -separately, but their `configure' scripts and `Makefile's are -designed to work together. To ensure that GDB's `Makefile' can find -all the pieces, you should make a single overall directory to hold -the directories of source for GNU libraries and includes, and you -should install the GDB source directory there too. In this -Appendix, we refer to the directory of GNU source directories as GNUSRC. + The gdb distribution includes all the source code you need for gdb +in a single directory `gdb-4.0'. That directory in turn contains: - At a minimum, to build GDB you need the directories +`gdb-4.0/configure' + Overall script for configuring GDB and all its supporting + libraries. -`GNUSRC/gdb' +`gdb-4.0/gdb' the source specific to GDB itself -`GNUSRC/bfd' +`gdb-4.0/bfd' source for the Binary File Descriptor Library -`GNUSRC/include' +`gdb-4.0/include' GNU include files -`GNUSRC/libiberty' +`gdb-4.0/libiberty' source for the `-liberty' free software library -`GNUSRC/readline' +`gdb-4.0/readline' source for the GNU command-line interface -Each of these directories has its own `configure' script. GNUSRC has -an overall `configure' script, which is distributed with the GNU -libraries and includes. +Each of these directories has its own `configure' script, which are +used by the overall `configure' script in `gdb-4.0'. - `configure' is designed to be called recursively, so it is most -convenient to run `configure' from the GNUSRC directory. The -simplest way to configure and build GDB is the following: + It is most convenient to run `configure' from the `gdb-4.0' +directory. The simplest way to configure and build GDB is the +following: - cd GNUSRC + cd gdb-4.0 ./configure HOST make -where HOST is something like `sun4' or `vax', that identifies the -platform where GDB will run. This builds the three libraries `bfd', -`readline', and `libiberty', then `gdb' itself. The configured -source files, and the binaries, are left in the corresponding source -directories. +where HOST is something like `sun4' or `decstation', that identifies +the platform where GDB will run. This builds the three libraries +`bfd', `readline', and `libiberty', then `gdb' itself. The +configured source files, and the binaries, are left in the +corresponding source directories. You can install `gdb' anywhere; it has no hardwired paths. However, you should make sure that the shell on your path (named by @@ -121,122 +148,216 @@ the `SHELL' environment variable) is publicly readable; some systems refuse to let GDB debug child processes whose programs are not readable, and GDB uses the shell to start your program. - - Configuration Subdirectories - - If you build GDB for several host or target machines, and if your -`make' program handles the `VPATH' feature (GNU `make' does), it is -most convenient instead to build the different GDB configurations in -subdirectories (separate from the source). `configure' does this -for you when you simultaneously specify several configurations; but -it's a good habit even for a single configuration. You can specify -the use of subdirectories using the `+forcesubdirs' option -(abbreviated `+f'). For example, you can build GDB on a Sun 4 as -follows: - - cd GNUSRC - ./configure +f sun4 - cd Host-sun4/Target-sun4 +Configuration Subdirectories +============================ + + 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. 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. + + `configure' creates these subdirectories for you when you +simultaneously specify several configurations; but it's a good habit +even for a single configuration. You can specify the use of +subdirectories using the `+subdirs' option (abbreviated `+sub'). +For example, you can build GDB on a Sun 4 as follows: + + cd gdb-4.0 + ./configure +sub sun4 + cd Host-sparc-sun-sunos4/Target-sparc-sun-sunos4 make When `configure' uses subdirectories to build programs or -libraries, it creates nested directories `Host-HOST/Target-MACHINE'. -This is because GDB can be configured for cross-compiling: GDB can -run on one machine (the host) while debugging programs that run on -another machine (the target). You specify cross-debugging targets -by giving the `+target=MACHINE' option to `configure'. Specifying -only hosts still gives you two levels of subdirectory for each host, -with the same machine-name suffix on both. On the other hand, -whenever you specify both hosts and targets on the same command -line, `configure' creates all combinations of the hosts and targets you -list. +libraries, it creates nested directories `Host-HOST/Target-TARGET'. +(As you see in the example, the names used for HOST and TARGET may +be expanded from your `configure' argument; *note Config Names::.). +`configure' uses these two directory levels because GDB can be +configured for cross-compiling: GDB can run on one machine (the +host) while debugging programs that run on another machine (the +target). You specify cross-debugging targets by giving the +`+target=TARGET' option to `configure'. Specifying only hosts still +gives you two levels of subdirectory for each host, with the same +configuration suffix on both; that is, if you give any number of +hosts but no targets, GDB will be configured for native debugging on +each host. On the other hand, whenever you specify both hosts and +targets on the same command line, `configure' creates all +combinations of the hosts and targets you list. When you run `make' to build a program or library, you must run it in a configured directory. If you made a single configuration, without subdirectories, run `make' in the source directory. If you -have `Host-HOST/Target-MACHINE' subdirectories, run `make' in those +have `Host-HOST/Target-TARGET' subdirectories, run `make' in those subdirectories. Each `configure' and `Makefile' under each source directory runs -recursively, so that typing `make' in GNUSRC (or in a -`GNUSRC/Host-HOST/Target-MACHINE' subdirectory) builds all the +recursively, so that typing `make' in `gdb-4.0' (or in a +`gdb-4.0/Host-HOST/Target-TARGET' subdirectory) builds all the required libraries, then GDB. - If you run `configure' from a directory (such as GNUSRC) that + If you run `configure' from a directory (such as `gdb-4.0') that contains source directories for multiple libraries or programs, -`configure' creates the `Host-HOST/Target-MACHINE' subdirectories in +`configure' creates the `Host-HOST/Target-TARGET' subdirectories in each library or program's source directory. For example, typing: - cd GNUSRC - configure sun4 +target=vx960 + cd gdb-4.0 + configure sun4 +target=vxworks960 creates the following directories: - GNUSRC/Host-sun4/Target-vx960 - GNUSRC/bfd/Host-sun4/Target-vx960 - GNUSRC/gdb/Host-sun4/Target-vx960 - GNUSRC/libiberty/Host-sun4/Target-vx960 - GNUSRC/readline/Host-sun4/Target-vx960 + gdb-4.0/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + gdb-4.0/bfd/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + gdb-4.0/gdb/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + gdb-4.0/libiberty/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + gdb-4.0/readline/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + +The `Makefile' in + + gdb-4.0/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + +will `cd' to the appropriate lower-level directories, for example: -The `Makefile' in `GNUSRC/Host-sun4/Target-vx960' will `cd' to the -appropriate lower-level directories (such as -`GNUSRC/bfd/Host-sun4/Target-vx960'), building each in turn. + gdb-4.0/bfd/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks + +building each in turn. When you have multiple hosts or targets configured, 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. - - `configure' Options +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, but the full name of that configuration +specifies that the architecture is `sparc', the vendor is `sun', and +the operating system is `sunos4'. + + The following table shows all the architectures, hosts, and OS +prefixes that `configure' recognizes in GDB 4.0. Entries in the "OS +prefix" +column ending in a `*' may be followed by a release number. + + + ARCHITECTURE VENDOR OS prefix + ------------+-------------+------------- + | | + a29k | altos | aix* + alliant | aout | aout + arm | apollo | bout + c1 | att | bsd* + c2 | bout | coff + i386 | coff | ctix* + i860 | convergent | dynix* + i960 | convex | esix* + m68000 | dec | hpux* + m68k | encore | isc* + m88k | gould | mach* + mips | hp | newsos* + ns32k | ibm | nindy* + pyramid | intel | none + rs6000 | isi | osf* + rtpc | little | sco* + sparc | mips | sunos* + tahoe | motorola | sysv* + tron | ncr | ultrix* + vax | next | unos* + | none | v88r* + | sco | vms* + | sequent | vxworks* + | sgi | + | sony | + | sun | + | unicom | + | utek | + | wrs | + + *Warning:* Many combinations of architecture, vendor, and OS are + untested. + + The `configure' script accompanying GDB 4.0 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 + % sh config.sub sun3 + m68k-sun-sunos4 + % sh config.sub decstation + mips-dec-ultrix + % sh config.sub hp300bsd + m68k-hp-bsd + % sh config.sub i386v + i386-none-sysv + % sh config.sub i486v + *** No vendor: configuration `i486v' not recognized + +`configure' Options +=================== Here is a summary of all the `configure' options and arguments that you might use for building GDB: - configure [+destdir=DIR] [+forcesubdirs] [+norecur] [+rm] - [+target=MACHINE...] HOST... + configure [+destdir=DIR] [+subdirs] [+norecur] [+rm] + [+target=TARGET...] HOST... You may introduce options with the character `-' rather than `+' if -you prefer; but options introduced with `+' may be truncated. +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'. -`+forcesubdirs' +`+subdirs' Write configuration specific files in subdirectories of the form - Host-MACHINE/Target-MACHINE + Host-HOST/Target-TARGET (and configure the `Makefile' to write binaries there too). Without this option, if you specify only one configuration for GDB, `configure' will use the same directory for source, configured files, and binaries. This option is used automatically if you specify more than one HOST or more than - one `+target=MACHINE' option on the `configure' command line. + one + `+target=TARGET' option on the `configure' command line. `+norecur' Configure only the directory where `configure' is executed; do not propagate configuration to subdirectories. `+rm' - Remove the configuration specified by other arguments. + Remove the configuration that the other arguments specify. -`+target=MACHINE ...' +`+target=TARGET ...' Configure GDB for cross-debugging programs running on each - specified MACHINE. You may specify as many `+target' options - as you wish. To see a list of available targets, execute `ls - tconfig' in the GDB source directory. Without this option, GDB - is configured to debug programs that run on the same machine - (HOST) as GDB itself. + specified TARGET. You may specify as many `+target' options as + you wish. 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 ...' Configure GDB to run on each specified HOST. You may specify as - many host names as you wish. To see a list of available hosts, - execute `ls xconfig' in the GDB source directory. + many host names as you wish. + + There is no convenient way to generate a list of all available + hosts. `configure' accepts other options, for compatibility with configuring other GNU tools recursively; but these are the only options that @@ -248,10 +369,11 @@ affect GDB or its supporting libraries. C++ support has been integrated into gdb. GDB should work with FORTRAN programs. (If you have problems, please send a bug report; you may have to refer to some FORTRAN variables with a trailing underscore). -There is an effort to produce a GDB that works with Modula-2. I am not -aware of anyone who is working on getting gdb to use the syntax of any -other language. Pascal programs which use sets, subranges, file -variables, or nested functions will not currently work. +Andrew Beers has produced a GDB that works with Modula-2, which will +appear in gdb-4.1. I am not aware of anyone who is working on getting +gdb to use the syntax of any other language. Pascal programs which use +sets, subranges, file variables, or nested functions will not currently +work. Kernel debugging @@ -298,17 +420,15 @@ distributed with GDB version 3). Currently it just works over UDP The correct address for reporting bugs found in gdb is "bug-gdb@prep.ai.mit.edu". Please email all bugs to that address. -"mcheck.c", line 32, will produce a pointer conversion warning, which -can be ignored. - -When gdb reads object files produced by the Sun bundled C compiler, -you will often get a "bad block start address patched" message. You -can shut off such messages with the command `set complaint 0' (which -you can put in your ~/.gdbinit if you like). Messages like this -during symbol reading indicate some mismatch between the object file -and GDB's symbol reading code (in this case, it's a mismatch -between the specs for the object file format, and what Sun's compiler -actually outputs). +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). If you port gdb to a new machine, please send the required changes to bug-gdb@prep.ai.mit.edu. If your changes are more than a few @@ -453,6 +573,9 @@ sets up some simple things to make debugging gdb easier. The "info" command, when executed without a subcommand in a gdb being debugged by gdb, will pop you back up to the top level gdb. See .gdbinit for details. +I strongly recommend printing out the reference card and using it. +Send reference-card suggestions to bug-gdb@prep.ai.mit.edu, just like bugs. + If you use emacs, you will probably want to do a "make TAGS" after you configure your distribution; this will put the machine dependent routines for your local machine where they will be accessed first by a -- 2.30.2