readme

早期freebsd实现

		README for gdb-4.7 release
    Stu Grossman & John Gilmore 	23 October 1992

This is GDB, the GNU source-level debugger, presently running under un*x.
A summary of new features is in the file `NEWS'.


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.7 directory.  The idea is that a variety of GNU tools can
share a common copy of these things.  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.7.tar.Z file, you'll get a directory called
`gdb-4.7', which contains:

  COPYING.LIB      config/          configure.texi   mmalloc/
  Makefile.in      config.sub*      gdb/             move-if-change*
  README           configure*       glob/            opcodes/
  bfd/             configure.in     include/         readline/
  cfg-paper.texi   configure.man    libiberty/       texinfo/

To build GDB, you can just do:

	cd gdb-4.7
	./configure HOSTTYPE		(e.g. sun4, decstation)
	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 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.  See below.


More Documentation
******************

   The GDB 4 release includes an already-formatted reference card, ready
for printing with PostScript or GhostScript, in the `gdb' subdirectory
of the main source directory--in `gdb-4.7/gdb/refcard.ps' of the
version 4.7 release. If you can use PostScript or GhostScript with your
printer, you can print the reference card immediately with `refcard.ps'.

   The release also includes the source for the reference card.  You
can format it, using TeX, by typing:

     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.

   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' 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.  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.7', in the case of version 4.7), you can make
the Info file by typing:

     cd gdb
     make gdb.info

   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.7/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
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.7 distribution is in the `gdb-4.7'
directory.  That directory contains:

`gdb-4.7/configure (and supporting files)'
     script for configuring GDB and all its supporting libraries.

`gdb-4.7/gdb'
     the source specific to GDB itself

`gdb-4.7/bfd'
     source for the Binary File Descriptor library

`gdb-4.7/include'
     GNU include files

`gdb-4.7/libiberty'
     source for the `-liberty' free software library

`gdb-4.7/opcodes'
     source for the library of opcode tables and disassemblers

`gdb-4.7/readline'
     source for the GNU command-line interface

`gdb-4.7/glob'
     source for the GNU filename pattern-matching subroutine

`gdb-4.7/mmalloc'
     source for the GNU memory-mapped malloc package

   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.7' 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.7
     ./configure HOST
     make

where HOST is an identifier such as `sun4' or `decstation', that
identifies the platform where GDB will run.

   Running `configure HOST' 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 HOST

   If you run `configure' from a directory that contains source
directories for multiple libraries or programs, such as the `gdb-4.7'
source directory for version 4.7, `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.7, type the following to configure only
the `bfd' subdirectory:

     cd gdb-4.7/bfd
     ../configure HOST

   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'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.

   To build `gdb' in a separate directory, run `configure' with the
`--srcdir' option to specify where to find the source. (You'll 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.7, you can build GDB in a separate
directory for a Sun 4 like this:

     cd gdb-4.7
     mkdir ../gdb-sun4
     cd ../gdb-sun4
     ../gdb-4.7/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' generated by `configure' for each source directory
also runs recursively.  If you type `make' in a source directory such
as `gdb-4.7' (or in a separate configured directory configured with
`--srcdir=PATH/gdb-4.7'), you will build all the required libraries,
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, but 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-sunos411
     % sh config.sub sun3
     m68k-sun-sunos411
     % sh config.sub decstation
     mips-dec-ultrix42
     % sh config.sub hp300bsd
     m68k-hp-bsd
     % sh config.sub i386v
     i386-unknown-sysv
     % sh config.sub i786v