More Documentation
==================
- The GDB 4.4 release includes an already-formatted reference card,
-ready for printing on a PostScript printer, as
-`gdb-4.4/gdb/refcard.ps'. It uses the most common PostScript fonts:
-the Times family, Courier, and Symbol. If you have a PostScript
+ 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 release also includes the online Info version of this manual
-already formatted: the main Info file is `gdb-4.4/gdb/gdb.info', and it
-refers to subordinate files matching `gdb.info*' in the same directory.
+ If all you have is TeX, format the GDB reference card by typing:
- 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
+ make refcard.dvi
- cd gdb-4.4/gdb
- make gdb.info
+ 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.
-to make the Info file.
+ 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.
- If you want to format and print copies of the manual, you need
-several things:
+ 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.
- * TeX, the public domain typesetting program written by Donald
- Knuth, must be installed on your system and available through
- your execution path.
+ If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as `texinfo-format-buffer' or
+`makeinfo'.
- * `gdb-4.4/texinfo': TeX macros defining the GNU Documentation
- Format.
+ 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
+the Info file by typing:
- * *A DVI output program.* TeX does not 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.
+ cd gdb
+ make gdb.info
-Once you have these things, you can type
+ If you want to typeset and print copies of this manual, you need
+TeX, a printing program such as `lpr', and `texinfo.tex', the Texinfo
+definitions file.
+
+ TeX is 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 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-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:
- cd gdb-4.4/gdb
make gdb.dvi
-to format the text of this manual, and print it with the usual output
-method for TeX DVI files at your site.
-
- If you want to print the reference card, but do not have a
-PostScript printer, or you want to use Computer Modern fonts instead,
-you can still print it if you have TeX. Format the reference card by
-typing
-
- cd gdb-4.4/gdb
- make refcard.dvi
-
-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.
-
-
Installing GDB
==============
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 `gdb-4.4'. That directory in turn contains:
+ 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'
+directory. That directory contains:
`gdb-4.4/configure (and supporting files)'
script for configuring GDB and all its supporting libraries.
`gdb-4.4/readline'
source for the GNU command-line interface
-It is most convenient to run `configure' from the `gdb-4.4' directory.
- The simplest way to configure and build GDB is the following:
+ 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.
+
+ 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
./configure HOST
make
-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
+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.
`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 HOST'.
+you may need to run `sh' on it explicitly:
+
+ sh configure HOST
- 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,
-to configure only the `bfd' subdirectory,
+ 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
+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.4, type the following to configure only
+the `bfd' subdirectory:
cd gdb-4.4/bfd
../configure HOST
- You can install `gdb' anywhere; it has no hardwired paths. Simply
-copy `gdb/gdb' to the desired directory.
+ 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.
- However, you should make sure that the shell on your path (named by
-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
-============================
+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. 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 is 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 this way on a Sun 4 as follows:
+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.
- cd gdb-4.4
- ./configure +sub sun4
- cd H-sun4/T-sun4
- make
+ 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.)
- When `configure' uses subdirectories to build programs or
-libraries, it creates nested directories `H-HOST/T-TARGET'.
-`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.
-
- If you run `configure' from a directory (notably, `gdb-4.4') that
-contains source directories for multiple libraries or programs,
-`configure' creates the `H-HOST/T-TARGET' subdirectories in each
-library or program's source directory. For example, typing:
+ For example, with version 4.4, you can build GDB in a separate
+directory for a Sun 4 like this:
cd gdb-4.4
- configure sun4 +target=vxworks960
+ mkdir ../gdb-sun4
+ cd ../gdb-sun4
+ ../gdb-4.4/configure --srcdir=../gdb-4.4 sun4
+ make
-creates the following directories:
+ 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'.
- gdb-4.4/H-sun4/T-vxworks960
- gdb-4.4/bfd/H-sun4/T-vxworks960
- gdb-4.4/gdb/H-sun4/T-vxworks960
- gdb-4.4/libiberty/H-sun4/T-vxworks960
- gdb-4.4/readline/H-sun4/T-vxworks960
+ One popular use for building 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. If you made a single configuration,
-without subdirectories, run `make' in the source directory. If you
-have `H-HOST/T-TARGET' subdirectories, run `make' in those
-subdirectories.
+in a configured directory--whatever directory you were in when you
+called `configure' (or one of its subdirectories).
The `Makefile' generated by `configure' for each source directory
-runs recursively, so that typing `make' in `gdb-4.4' (or in a
-`gdb-4.4/H-HOST/T-TARGET' subdirectory) builds all the required
-libraries, then GDB.
+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,
+then build GDB.
- 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.
-
- You can also use the `+objdir=ALTROOT' option to have the
-configured files placed in a parallel directory structure rather than
-alongside the source files; *note configure Options::..
+ 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
`sparc-sun-sunos4'.
The following table shows all the architectures, hosts, and OS
-prefixes that `configure' recognizes in GDB 4.4. Entries in the "OS
-prefix" column ending in a `*' may be followed by a release number.
+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
xmp | |
ymp | |
- *Warning:* `configure' can represent a very large number of
+ *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 4.4 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
+ 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 i486v
*** Configuration "i486v" not recognized
-`config.sub' is also distributed in the directory `gdb-4.4'.
+`config.sub' is also distributed in the GDB source directory
+(`gdb-4.4', for version 4.4).
`configure' Options
Here is a summary of all the `configure' options and arguments that
you might use for building GDB:
- configure [+destdir=DIR] [+subdirs]
- [+objdir=ALTROOT] [+norecursion] [+rm]
- [+target=TARGET...] HOST...
+ configure [--destdir=DIR] [--srcdir=PATH]
+ [--norecursion] [--rm]
+ [--target=TARGET] HOST
-You may introduce options with the character `-' rather than `+' if
-you prefer; but you may abbreviate option names if you use `+'.
+You may introduce options with a single `-' rather than `--' if you
+prefer; but you may abbreviate option names if you use `--'.
-`+destdir=DIR'
+`--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
+ `--destdir=/usr/local', for example, `make install' creates
`/usr/local/bin/gdb'.
-`+subdirs'
- Write configuration specific files in subdirectories of the form
-
- H-HOST/T-TARGET
-
- (and configure the `Makefile' to generate object code in
- subdirectories of this form as well). 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=TARGET' option on the `configure' command
- line.
-
-`+norecursion'
- Configure only the directory where `configure' is executed; do not
- propagate configuration to subdirectories.
-
-`+objdir=ALTROOT'
- ALTROOT is an alternative directory used as the root for
- configured files. `configure' will create directories under
- ALTROOT in parallel to the source directories. If you use
- `+objdir=ALTROOT' with `+subdirs', `configure' also builds the
- `H-HOST/T-TARGET' subdirectories in the directory tree rooted in
- ALTROOT.
-
-`+rm'
+`--srcdir=PATH'
+ 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.
-`+target=TARGET ...'
- Configure GDB for cross-debugging programs running on each
- specified TARGET. You may specify as many `+target' options as
- you wish. Without this option, GDB is configured to debug
+`--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 ...'
- Configure GDB to run on each specified HOST. You may specify as
- many host names as you wish.
+ Configure GDB to run on the specified HOST.
There is no convenient way to generate a list of all available
hosts.
Languages other than C
-C++ support has been integrated into gdb. Partial Modula-2 support is
-now in GDB. GDB should work with FORTRAN programs. (If you have
-problems, please send a bug report; you may have to refer to some
+GDB provides some support for debugging C++ progams. Partial Modula-2
+support is now in 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). 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,
projects / binutils-gdb.git / commitdiff