/************************************************************************/
/*	
/*			Instructions for Installing GDB
/*	
/*			    Noah Mendelsohn
/*			    August 24, 1987
/*	
/*	Copyright (C) 1987 Massachusetts Institute of Technology
/*	
/*	    For more information on copying and distribtion, see 
/*	    the file named mit-copyright.h in the directory named
/*	    include.
/*	
/*	
/*	$Source: /afs/dev.mit.edu/source/repository/athena/lib/gdb/README,v $
/*	$Author: probe $
/*	$Header: /afs/dev.mit.edu/source/repository/athena/lib/gdb/README,v 1.1 1993-10-12 03:25:36 probe Exp $
/*	
/*			=========================
/*	
/*	This file contains information of interest to two separate
/*	groups of readers:
/*	
/*	1) Those around the MIT community who are obtaining private
/*	   copies of GDB.
/*	
/*	2) The Project Athena release engineering staff, who build
/*	   GDB for inclusion with the Athena system releases.
/*	
/*			=========================
/*	
/*	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 and associated programs:

	% make all

There is also support for:

	% make clean		<= clean up the directories
	% make depend		<= rebuild the dependency information
				   in the make files
	% make lint		<= run lint on all the GDB programs 
				   (except the samples)
	% make install		<= normally used only by the Athena
			     	   staff.  installs GDB in its usual
				   place(s) at Athena

If you are not at Project Athena, or for some other reason wish to compile
GDB without Hesiod support (or dependencies), see the section later in
this README file on Building and Using GDB Without Hesiod.

/************************************************************************/
/*	
/*	Installing the GDB libraries 
/*	
/************************************************************************/

The Makefiles provided with GDB are designed for installations to be
done by the release engineering staff at Project Athena.  In
particular, a:

	% make DESTDIR=/ABC install

will create the following files:

	/ABC/usr/lib/libgdb.a
	/ABC/usr/lib/libgdb_p.a

	/ABC/usr/man/man1/dbserv.1
	/ABC/usr/man/man3/gdb.3

	/ABC/usr/doc/gdb/gdb_ugd.mss
	/ABC/usr/doc/gdb/gdb_library.mss

	/ABC/usr/unsupported/dbserv	<== this file not created unless Ingres
				    	    is installed at this site
	/ABC/usr/include/gdb.h


where the /ABC is the directory specified as DESTDIR on the make command.
To change the directories in which the files are placed, you must edit the 
Makefiles.  The Makefiles presume that all required directories have been
created before the make install is run.

If you are making GDB for private use, do a:

	% make all

instead of a make install.  The GDB libraries will be in the lib subdirectory,
.h in include, and so on.  

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

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

	% cd doc
	% make gdb_ugd.PS gdb_library.PS

Scribe will report a few errors after the first pass about symbol
references being wrong, suggesting a re-run.  The makefile does
the re-run automatically.


To print the manuals:

	% lpr gdb_ugd.PS
	% lpr gdb_library.PS

You must be using a postscript printer.


There are a few man pages supplied with GDB too.  These are installed
automatically on a make install.  To just format them:

	% cd doc          	   <= Assuming you were in the gdb directory
	% make gdb.man dbserv.man  <= runs the man pages through nroff

You can 'more' the resulting .man files.

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

The user guide tells you how to do this.  Note that gdb.h winds up in
the gdb/include directory when you use these installation
instructions, and libgdb.a winds up in gdb/lib.  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.  It is built automatically
along with a make all or you can do the following:

	% cd db			<= from the gdb directory
	% make dbserv

This MUST be done on a machine where RTI Ingres is installed.  You may
have to edit the makefile if /usr/rtingres is not the directory where Ingres
lives.  In anycase, the dbserv program winds up in the db subdirectory.

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

Various test programs are included in samps directory.  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.  All of them can be
built by:

	% cd samps
	% make all

They are NOT normally built when the rest of GDB is made.

/************************************************************************/
/*	
/*				  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 (in the samps directory) 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
nany 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.

/************************************************************************/
/*	
/*	   Building and Using GDB Without Hesiod Support
/*	
/************************************************************************/

The Makefiles supplied with this distribution cause GDB to be built with
Hesiod support for resolving database names.  Hesiod support may be disabled
by removing the "-DHESIOD" from the definition of CFLAGS and LINTFLAGS
in the main Makefile. Also, if the sample programs are to be compiled, then
the Makefile in the samps subdirectory should be edited to remove the 
-lhesiod specification.

If GDB is built with Hesiod support, then applications using libgdb.a 
should be linked with the -lhesiod flag.  If not, then the flag may be
omitted.

/************************************************************************/
/*	
/*				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