* Emacs:: Using _GDBN__ under GNU Emacs
* _GDBN__ Bugs:: Reporting bugs in _GDBN__
* Renamed Commands::
+* Formatting Documentation:: How to format and print GDB documentation
* Installing GDB:: Installing GDB
* Copying:: GNU GENERAL PUBLIC LICENSE
* Index:: Index
* Separate Objdir:: Compiling _GDBN__ in another directory
* Config Names:: Specifying names for hosts and targets
* configure Options:: Summary of options for configure
-* Formatting Documentation:: How to format and print GDB documentation
@end menu
@node Summary, New Features, Top, Top
@xref{Renamed Commands}, for details on what commands were renamed.
@item Shared Libraries
-GDB 4 can debug programs and core files that use SunOS shared
-libraries.
+GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
+shared libraries.
@item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation} for
@itemx -mapped
@emph{Warning: this option depends on operating system facilities that are not
supported on all systems.}@*
-If memory-mapped files are available through the @code{mmap} system
-call, you can use this option to get _GDBN__ to write out the symbols
-for your program in a reusable file. Next time _GDBN__ starts up (if the
-program hasn't changed), it will map in symbol information from this
-auxiliary symbol file, rather than spending time reading the symbol
-table from the executable program.
+If memory-mapped files are available on your system through the @code{mmap}
+system call, you can use this option
+to cause _GDBN__ to write the symbols from your
+program into a reusable file in the current directory. If the program you are debugging is
+called @file{/tmp/fred}, the mapped symbol file will be @file{./fred.syms}.
+Future _GDBN__ debugging sessions will notice the presence of this file,
+and will quickly map in symbol information from it, rather than reading
+the symbol table from the executable program.
+
+The @file{.syms} file is specific to the host machine on which _GDBN__ is run.
+It holds an exact image of _GDBN__'s internal symbol table. It cannot be
+shared across multiple host platforms.
+
+@item -r
+@itemx -readnow
+Read each symbol file's entire symbol table immediately, rather than
+the default, which is to read it incrementally as it is needed.
+This makes startup slower, but makes future operations faster.
@end table
+The @code{-mapped} and @code{-readnow} options are typically combined in order to
+build a @file{.syms} file that contains complete symbol information.
+A simple GDB invocation to do nothing but build a @file{.syms} file for future
+use is:
+
+@example
+ gdb -batch -nx -mapped -readnow programname
+@end example
+
_if__(!_GENERIC__)
@node Mode Options, Mode Options, File Options, Invoking _GDBN__
_fi__(!_GENERIC__)
is, _GDBN__ will map in the symbol table from
@file{@var{filename}.syms}, starting up more quickly. See the
descriptions of the options @samp{-mapped} and @samp{-readnow} (available
-with @code{file}, @code{symbol-file}, or @code{add-symbol-file}), for
-more information.
+on the command line, and with the commands @code{file}, @code{symbol-file},
+or @code{add-symbol-file}), for more information.
@item file
@code{file} with no argument makes _GDBN__ discard any information it
If memory-mapped files are available on your system through the
@code{mmap} system call, you can use another option, @samp{-mapped}, to
-get _GDBN__ to write out the symbols for your program in a reusable
-file. Next time _GDBN__ starts up (if the program hasn't changed), it
-will map in symbol information from this auxiliary symbol file, rather
-than spending time reading the symbol table from the executable program.
-Using the @samp{-mapped} option has the same effect as starting _GDBN__
-with the @samp{-m} command-line option.
+cause _GDBN__ to write the symbols for your program into a reusable
+file. Future _GDBN__ debugging sessions will map in symbol information
+from this auxiliary symbol file (if the program hasn't changed), rather
+than spending time reading the symbol table from the executable
+program. Using the @samp{-mapped} option has the same effect as
+starting _GDBN__ with the @samp{-mapped} command-line option.
You can use both options together, to make sure the auxiliary symbol
file has all the symbol information for your program.
+The @code{.syms} file is specific to the host machine on which GDB is run.
+It holds an exact image of GDB's internal symbol table. It cannot be
+shared across multiple host platforms.
+
The auxiliary symbol file for a program called @var{myprog} is called
@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
than the corresponding executable), _GDBN__ will always attempt to use
@cindex shared libraries
-_GDBN__ supports the SunOS shared library format. _GDBN__ automatically
-loads symbol definitions from shared libraries when you use the
-@code{run} command, or when you examine a core file. (Before you issue
-the @code{run} command, _GDBN__ will not understand references to a
-function in a shared library, however---unless you are debugging a core
-file).
+_GDBN__ supports SunOS, SVR4, and IBM RS/6000 shared libraries.
+_GDBN__ automatically loads symbol definitions from shared libraries
+when you use the @code{run} command, or when you examine a core file.
+(Before you issue the @code{run} command, _GDBN__ will not understand
+references to a function in a shared library, however---unless you are
+debugging a core file).
@c FIXME: next _GDBN__ release should permit some refs to undef
@c FIXME...symbols---eg in a break cmd---assuming they are from a shared lib
-@c FIXME: still only SunOS??
@table @code
@item info share
@include inc-hist.texi
@end iftex
-@node Renamed Commands, Installing GDB, _GDBN__ Bugs, Top
+@node Renamed Commands, Formatting Documentation, _GDBN__ Bugs, Top
@appendix Renamed Commands
The following commands were renamed in GDB 4, in order to make the
@end tex
@c END TEXI2ROFF-KILL
-@node Installing GDB, Copying, Renamed Commands, Top
+@node Formatting Documentation, Installing GDB, Renamed Commands, Top
+@appendix Formatting the Documentation
+
+@cindex GDB reference card
+@cindex reference card
+The GDB 4 release includes an already-formatted reference card, ready
+for printing on a PostScript or GhostScript printer, in the @file{gdb}
+subdirectory of the main source directory---in
+@file{gdb-_GDB_VN__/gdb/refcard.ps} of the version _GDB_VN__ release. If you have
+a PostScript or GhostScript printer, you can print the reference card
+by just sending @file{refcard.ps} to the printer.
+
+The release also includes the source for the reference card. You
+can format it, using @TeX{}, by typing:
+
+@example
+make refcard.dvi
+@end example
+
+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 @sc{dvi} output program.
+
+@cindex 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 @code{texi2roff}) to typeset the printed version.
+
+GDB includes an already formatted copy of the on-line Info version of
+this manual in the @file{gdb} subdirectory. The main Info file is
+@file{gdb-@var{version-number}/gdb/gdb.info}, and it refers to
+subordinate files matching @samp{gdb.info*} in the same directory.
+
+If you want to format these Info files yourself, you need one of the
+Info formatting programs, such as @code{texinfo-format-buffer} or
+@code{makeinfo}.
+
+If you have @code{makeinfo} installed, and are in the top level GDB
+source directory (@file{gdb-_GDB_VN__}, in the case of version _GDB_VN__), you can
+make the Info file by typing:
+
+@example
+cd gdb
+make gdb.info
+@end example
+
+If you want to typeset and print copies of this manual, you need
+@TeX{}, a printing program such as @code{lpr}, and @file{texinfo.tex},
+the Texinfo definitions file.
+
+@TeX{} is typesetting program; it does not print files directly, but
+produces output files called @sc{dvi} files. To print a typeset
+document, you need a program to print @sc{dvi} files. If your system
+has @TeX{} installed, chances are it has such a program. The precise
+command to use depends on your system; @kbd{lpr -d} is common; another
+is @kbd{dvips}. The @sc{dvi} print command may require a file name
+without any extension or a @samp{.dvi} extension.
+
+@TeX{} also requires a macro definitions file called
+@file{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. @file{texinfo.tex} is distributed with GDB
+and is located in the @file{gdb-@var{version-number}/texinfo}
+directory.
+
+If you have @TeX{} and a @sc{dvi} printer program installed, you can
+typeset and print this manual. First switch to the the @file{gdb}
+subdirectory of the main source directory (for example, to
+@file{gdb-_GDB_VN__/gdb}) and then type:
+
+@example
+make gdb.dvi
+@end example
+
+@node Installing GDB, Copying, Formatting Documentation, Top
@appendix Installing GDB
@cindex configuring GDB
@cindex installation
the source specific to GDB itself
@item gdb-_GDB_VN__/bfd
-source for the Binary File Descriptor Library
+source for the Binary File Descriptor library
@item gdb-_GDB_VN__/include
GNU include files
@item gdb-_GDB_VN__/readline
source for the GNU command-line interface
+
+@item gdb-_GDB_VN__/glob
+source for the GNU filename pattern-matching subroutine
+
+@item gdb-_GDB_VN__/mmalloc
+source for the GNU memory-mapped malloc package
@end table
The simplest way to configure and build GDB is to run @code{configure}
where @var{host} is an identifier such as @samp{sun4} or
@samp{decstation}, that identifies the platform where GDB will run.
-This sequence of @code{configure} and @code{make} builds the three
-libraries @file{bfd}, @file{readline}, and @file{libiberty}, then
+This sequence of @code{configure} and @code{make} builds the @file{bfd},
+@file{readline}, @file{mmalloc}, and @file{libiberty} libraries, then
@code{gdb} itself. The configured source files, and the binaries, are
left in the corresponding source directories.
* Separate Objdir:: Compiling GDB in another directory
* Config Names:: Specifying names for hosts and targets
* configure Options:: Summary of options for configure
-* Formatting Documentation:: How to format and print GDB documentation
@end menu
@node Separate Objdir, Config Names, Installing GDB, Installing GDB
To build @code{gdb} in a separate directory, run @code{configure}
with the @samp{--srcdir} option to specify where to find the source.
-(Remember, you'll also need to specify a path to find @code{configure}
-itself from your working directory.)
+(You'll also need to specify a path to find @code{configure}
+itself from your working directory. If the path to @code{configure}
+would be the same as the argument to @samp{--srcdir}, you can leave out
+the @samp{--srcdir} option; it will be assumed.)
For example, with version _GDB_VN__, you can build GDB in a separate
directory for a Sun 4 like this:
cd gdb-_GDB_VN__
mkdir ../gdb-sun4
cd ../gdb-sun4
-../gdb-_GDB_VN__/configure --srcdir=../gdb-_GDB_VN__ sun4
+../gdb-_GDB_VN__/configure sun4
make
@end group
@end example
@code{config.sub} is also distributed in the GDB source
directory (@file{gdb-_GDB_VN__}, for version _GDB_VN__).
-@node configure Options, Formatting Documentation, Config Names, Installing GDB
+@node configure Options, , Config Names, Installing GDB
@section @code{configure} Options
Here is a summary of all the @code{configure} options and arguments that
you might use for building GDB:
@example
-configure @r{[}--destdir=@var{dir}@r{]} @r{[}--srcdir=@var{path}@r{]}
+configure @r{[}--srcdir=@var{path}@r{]}
@r{[}--norecursion@r{]} @r{[}--rm@r{]}
@r{[}--target=@var{target}@r{]} @var{host}
@end example
@samp{--}.
@table @code
-@item --destdir=@var{dir}
-@var{dir} is an installation directory @emph{path prefix}. After you
-configure with this option, @code{make install} will install GDB as
-@file{@var{dir}/bin/gdb}, and the libraries in @file{@var{dir}/lib}.
-If you specify @samp{--destdir=/usr/local}, for example, @code{make
-install} creates @file{/usr/local/bin/gdb}.
-
@item --srcdir=@var{path}
@strong{Warning: using this option requires GNU @code{make}, or another
@code{make} that implements the @code{VPATH} feature.}@*
configuring other GNU tools recursively; but these are the only
options that affect GDB or its supporting libraries.
-@node Formatting Documentation, , configure Options, Installing GDB
-@section Formatting the Documentation
-
-All the documentation for GDB, including this manual, comes as part of
-the 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 @code{texi2roff}) to typeset the
-printed version.
-
-GDB includes an already formatted copy of the on-line Info version of
-this manual in the @file{gdb} subdirectory. The main Info file is
-@file{gdb-@var{version-number}/gdb/gdb.info}, and it refers to
-subordinate files matching @samp{gdb.info*} in the same directory.
-
-If you want to format these Info files yourself, you need one of the
-Info formatting programs, such as @code{texinfo-format-buffer} or
-@code{makeinfo}.
-
-If you have @code{makeinfo} installed, and are in the top level GDB
-source directory (@file{gdb-_GDB_VN__}, in the case of version _GDB_VN__), you can
-make the Info file by typing:
-
-@example
-cd gdb
-make gdb.info
-@end example
-
-If you want to typeset and print copies of this manual, you need
-@TeX{}, a printing program such as @code{lpr}, and @file{texinfo.tex},
-the Texinfo definitions file.
-
-@TeX{} is typesetting program; it does not print files directly, but
-produces output files called @sc{dvi} files. To print a typeset
-document, you need a program to print @sc{dvi} files. If your system
-has @TeX{} installed, chances are it has such a program. The precise
-command to use depends on your system; @kbd{lpr -d} is common; another
-is @kbd{dvips}. The @sc{dvi} print command may require a file name
-without any extension or a @samp{.dvi} extension.
-
-@TeX{} also requires a macro definitions file called
-@file{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. @file{texinfo.tex} is distributed with GDB
-and is located in the @file{gdb-@var{version-number}/texinfo}
-directory.
-
-If you have @TeX{} and a @sc{dvi} printer program installed, you can
-typeset and print this manual. First switch to the the @file{gdb}
-subdirectory of the main source directory (for example, to
-@file{gdb-_GDB_VN__/gdb}) and then type:
-
-@example
-make gdb.dvi
-@end example
-
-@cindex GDB reference card
-@cindex reference card
-In addition to the manual, the GDB 4 release includes a three-column
-reference card. Format the GDB reference card by typing:
-
-@example
-make refcard.dvi
-@end example
-
-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 @sc{dvi} output program.
-
-The GDB 4 release includes an already-formatted reference card, ready
-for printing on a PostScript or GhostScript printer, in the @file{gdb}
-subdirectory of the main source directory---in
-@file{gdb-4.2/gdb/refcard.ps} of the version 4.2 release. If you have
-a PostScript or GhostScript printer, you can print the reference card
-by just sending @file{refcard.ps} to the printer.
-
@node Copying, Index, Installing GDB, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991
projects / binutils-gdb.git / commitdiff