fix RCS Id strings

[moira.git] / gdb / README

/************************************************************************/
/*	
/*			Instructions for Installing GDB
/*	
/*			    Noah Mendelsohn
/*			     April 22, 1987
/*	
/*	Copyright (C) 1987 Massachusetts Institute of Technology
/*	
/*			=========================
/*	
/*	NOTE:  GDB is not currently a supported service of Project Athena
/*	or of any other MIT organization.  It is a set of programs which
/*	I have written while working for Project Athena and which I
/*	am making available to the MIT community in the hope that they
/*	will prove useful.  The decision as to whether GDB will become
/*	supported is not mine to make.   If you wish to express an opinion,
/*	you should write a note including the following people on the
/*	distibution:
/*	
/*		Prof. Steve Lerman    (lerman@athena.mit.edu)
/*		Prof. Jerry Saltzer   (Saltzer@athena.mit.edu)
/*		Dan Geer	      (geer@athena.mit.edu)
/*		Noah Mendelsohn       (noah@athena.mit.edu)
/*	
/*	Thank you!
/*	
/*	This file is named: README
/*	
/************************************************************************/


/************************************************************************/
/*	
/*			Obtaining GDB
/*	
/************************************************************************/


GDB is now available to the MIT community by anonymous ftp 
from meathead.mit.edu.  There are currently two files:

	1) README    (this file)

	2) tar.file.Z  (compressed tar.file containing all of gdb)

To install gdb, make a directory on your own system.  It can
have any name, but we'll use gdb in this example:

	% mkdir gdb
	% cd gdb
	% ftp meathead.mit.edu
	===>login as anonymous and give your user i.d. as passwd
	ftp> cd gdb
	ftp> get README
	ftp> bin           	       <= make sure transfer of tar.file.Z
					  is done in binary mode, or the
					  uncompress step below may fail
	ftp> get tar.file.Z
	ftp> quit

	% uncompress tar.file.Z        <== this re-creates tar.file
					   If this step fails, you may have
					   forgotten to transfer the file
					   in binary mode (see above.)
	% tar xf tar.file              <== this extracts all the gdb
					   files from the tar file

/************************************************************************/
/*	
/*	Making the gdb libraries
/*	
/************************************************************************/

To build the GDB library:

	% make libgdb.a

/************************************************************************/
/*	
/*	Formatting documentation
/*	
/************************************************************************/

To format the gdb documents, you need scribe and access to a PostScript
printer.  To make the user guide:

	% make gdb_ugd.PS
	% rm gdb_ugd.PS
	% make gdb_ugd.PS

The reason you do it twice is that scribe requires two tries at a document 
in order to get the forward references to page numbers right.  The resulting
gdb_ugd.PS file may be sent to your PostScript printer:

	% lpr gdb_ugd.PS

To format the library reference manual:

	% make library.PS
	% rm library.PS
	% make library.PS

/************************************************************************/
/*	
/*			Writing and running programs
/*	
/************************************************************************/

The user guide tells you how to do this.  Note that gdb.h winds up in
the gdb directory (where the tar.file is) when you use these installation
instructions, and so does libgdb.a.  You will have to use the appropriate
Unix incantations, i.e. making links or telling cc and ld where to find 
things in order for your compilations and loads to work.  Make sure you
specify libgdb.a as one of the files to load along with your program.

/************************************************************************/
/*	
/*			Building the database server
/*	
/************************************************************************/

The database server program is named dbserv.  To build it:

	% make dbserv

This MUST be done on a machine where RTI Ingres is installed.  You may
have to edit the makefile if /rtingres is not the directory where Ingres
lives, and you may have to put /rtingres/bin in your path before doing the 
make.

/************************************************************************/
/*	
/*				Sample programs
/*	
/************************************************************************/

Various test programs are included in the tar.file.  These are not intended
primarily for users, they are used for my private testing, but a few of
them are well commented and many of them work.  The ones whose names begin
with the letter 't' are most likely to be useful.  Each of them can be
built with 'make'.

/************************************************************************/
/*	
/*				  Debugging
/*	
/************************************************************************/

Both the dbx and the Saber C debuggers have successfully executed many 
GDB applications.  I have found Saber to be particularly useful, and I
have included a .saberinit file which should serve as a starting point
for you.  (Warning:  .saberinit is supplied as a courtesy and I don't
guarantee to check it out with every re-release.  If you know enough
to use Saber, you can probably make any minor corrections which may
be needed without too much trouble.)  Note that both debuggers have trouble
on programs that fork.  See the gdb_debug routine and the GDB_NOFORK flag
for a useful trick to avoid forking when debugging.

/************************************************************************/
/*	
/*				Mailing lists
/*	
/************************************************************************/

gdb-users@athena.mit.edu	reaches all users of GDB bugs and fixes	
				are advertised here
gdb-news@athena.mit.edu		announcements of interest to a wider
				community of people who may not want to 
				know about every 2 line change to the system

noah@athena.mit.edu		the author