Installing DDD					-*- text -*-
**************

For compiling and installing DDD on a system, please follow these
instructions.


Build Requirements
==================

To build a complete DDD from sources, you need:

   * The GNU C++ compiler (2.7.2 or later), including a matching
     C++ I/O runtime library (libstdc++ or libg++).

     Some other C++ compilers have been reported to compile DDD as
     well.  Good results have been reported with Sun CC 4.0.  SGI CC
     and AIX xlC compile DDD, but introduce some subtle errors.
     Cfront 3.0 does not compile DDD.  In doubt, GCC is preferred.

   * A Motif Widget library, either LessTif (0.83 or later) or
     OSF/Motif (1.1 or later).  See the DDD WWW site and the
     `patches/' directory for useful LessTif patches.  The most recent
     LessTif release is available via `http://www.lesstif.org/'.

   * The X window library (Xlib) and X toolkit library (Xt), 
     X11 Release 4 or later.

   * A `make' program.  GNU make is recommended.


The following packages are recommended, but not required:

   * The XPM library (3.2 or later).  The XPM library brings support
     for multi-color icons and logos.  Without XPM, DDD will use
     monochrome icons.

   * The Athena Widget library (from X11R5 or later).  Having the
     Athena Widget library is convenient for supporting
     two-dimensional scrollbars.



Execution Requirements
======================

To run DDD, you need:

   * An inferior command-line debugger.  Best results are achieved
     with GDB, the GNU debugger.  (GDB 4.x is required; best results
     are achieved with GDB 4.13 or later.)  Using GDB, you can debug
     programs written in C, C++, GNU Java (`guavac'), GNU Ada
     (`gnat'), GNU Fortran (`g77') and GNU Modula-2.

     As an alternative to GDB, DDD also supports the DBX debugger as
     found on SUN, DEC, AIX, and IRIX systems.  Using DBX, you can
     debug programs written in C, C++, Pascal, Fortran, and Modula-2.
     DDD adapts automatically to a wide range of other DBX variants.

     As another alternative, DDD also supports the XDB debugger as
     found on HP-UX systems.  XDB usage has been tested for C programs
     only, but may work for other languages as well. (*)

     Finally, DDD also supports JDB, the Java Debugger, as of JDK 1.1
     and later.  Using JDB, you can find and fix bugs in Java
     programs.


     (*) XDB may no longer be supported in future DDD releases.
         You can use HP's Wildebeest (WDB) instead, a free GDB port to
         HP-UX (`http://www.hp.com/lang/tools/Debuggers/WDB/').
         Please let us know your experiences with DDD and WDB.


The following recommended helper applications should be in the user path:

   * An X terminal emulator program (`xterm' or likewise).  DDD needs
     this for running programs in the separate execution window.

   * The GNU `info' program as well as well as various info files.

     - `info -f gdb' should show the GDB Manual.  DDD uses this to
       display the GDB Reference.

     - `info -f libc' should show libc documentation.  DDD uses this
       give online help on the various signals.

   * The `xfontsel' font selection program.  With `xfontsel', you can
     select fonts interactively.


Basic Installation
==================

Basically, to build DDD from sources, you enter two commands:

	$ ./configure
	$ make

The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the DDD
package.  It also creates some `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a
file `config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

If you need to do unusual things to compile the DDD package, please
try to figure out how `configure' could check whether to do them, and
mail us diffs or instructions to so they can be considered for the next
release.  If at some point `config.cache' contains results you don't
want to keep, you may remove or edit it.

The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile DDD is:

  1. See the DDD WWW page, `http://www.cs.tu-bs.de/softech/ddd/',
     for recent release notes.

  2. See the file `PROBLEMS' for known problems during build and
     possible system-specific installation procedures.

  3. If you want to use DDD with LessTif, get a recent LessTif release
     from `http://www.lesstif.org' and see the `patches/' subdirectory
     for patches to be applied.

  4. `cd' to the directory containing the DDD package source code
     (that is, the directory named `ddd-<release>', *not* `ddd') and
     type `./configure' to configure DDD for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure -v' instead to prevent `csh' from trying to
     execute `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

     If `configure' reports an error or some bad result, check the
     files `config.log' and `ddd/config.log' for diagnostics.

  5. Check the `Makefile', `Ddd', and `config.h' files generated by
     `configure'.  Most settings should be guessed correctly by the
     `configure' program.  You may, however, wish to edit the
     settings, or re-run `configure' with special options.

     Frequently used `configure' options include `--program-prefix=x'
     to have DDD installed as `xddd' (to avoid confusion with existing
     `ddd' programs) or the `--with-motif...', `--with-athena...',
     `--with-x...'  options used to specify the locations of Motif and
     Athena widgets or the X libraries.  These and other `configure'
     options are decribed below.

     If you have multiple library versions installed (for instance,
     multiple X11 releases or releases from different sources), you
     may also have to supply their locations.  See `Optional
     features', below.

  6. Now type `make' to build DDD.  Most MAKE flavors should do,
     although GNU MAKE is preferred for incremental construction.
     Please report any bugs and problems to `ddd-bugs@ips.cs.tu-bs.de'.

  7. Building DDD takes awhile.  While DDD is being built, you may
     wish to read and/or print the documentation shipped with DDD.
     See the "Documentation" section, below.

  8. For a simple check, type `make check'.  This creates a sample
     program `cxxtest' and then runs DDD on it by invoking `./ddd
     cxxtest'.  Enjoy!

  9. If DDD crashes immediately after startup or after a few
     interactions, first check your configuration (the output of
     `./ddd --configuration') for version mismatches.

     Then, see the `PROBLEMS' and `BUGS' files for known problems.  If
     the problem is not listed, report it to the DDD maintainers
     <ddd-bugs@ips.cs.tu-bs.de>.  If you need help and assistance, see
     the DDD WWW page `http://www.cs.tu-bs.de/softech/ddd/' for
     patches, people, and pointers.

 10. Optionally, type `make strip' to reduce the size of the `ddd'
     executable by stripping the debugging information.

 11. Type `make install'.  This installs the DDD executable `ddd' in
     some public place (usually in `/usr/local/bin/') and the DDD
     manual page `ddd.1' (in `/usr/local/man/man1/').  See
     `Installation Names', below, on how to configure DDD to use other
     locations and names.

 12. Like every good X citizen, DDD comes with an application defaults
     file, named `ddd/Ddd'.  By default, this file is already compiled
     into DDD, so you need not install it.

     In fact, we **STRONGLY RECOMMEND** not to install it; there is a
     whole slew of version-skew problems associated with app-defaults
     files, which are best avoided by simply not using them.  See the
     comment at the beginning of `Ddd' for details.  If you absolutely
     want to install it, copy `Ddd' to a place where app-defaults
     files are commonly found.

 13. You can remove the program binaries, libraries and object files
     from the source directory by typing `make clean'.

     To also remove the Makefiles, the header files containing
     system-dependent definitions, and `config.status' (all the files
     that `configure' created), type `make distclean'.

     To also remove the system-independent derived files included in
     the DDD distribution for your convenience (such as LEX and YACC
     output), type `make realclean' instead.

     (There is also `make ultraclean' that removes *every* derived
     file; don't use it unless you know what you do.)

 14. Please consider sharing your DDD binary with other people lacking
     Motif or a C++ compiler.  As the DDD maintainers have access to a
     limited number of systems only, they cannot produce binaries for
     every single configuration.  For details, see
     `ftp://ftp.ips.cs.tu-bs.de/pub/local/softech/ddd/bin/'.

 15. You can remove DDD from your system by typing `make uninstall'.


Installation Details
====================

Compilers and Options
---------------------

Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.
Using a Bourne-compatible shell, you can do that on the command line
like this:

     CXX=/usr/egcs/bin/g++ CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:

     env CXXCPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Options set this way include:

`CC'
     The name of the C compiler

`CPPFLAGS'
     Preprocessing flags used by the C compiler

`CFLAGS'
     Compilation flags used by the C compiler

`CXX'
     The name of the C++ compiler

`CXXCPPFLAGS'
     Preprocessing flags used by the C++ compiler

`CXXFLAGS'
     Compilation flags used by the C++ compiler

`LDFLAGS'
     Linker flags used by both the C and C++ compiler


Using a Different Build Directory
---------------------------------

You can compile the DDD package in a different directory from the one
containing the source code.  Doing so allows you to compile it on more
than one kind of computer at the same time.  To do this, you must use
a version of `make' that supports the `VPATH' variable, such as GNU
`make'.  `cd' to the directory where you want the object files and
executables to go and run the `configure' script.  `configure'
automatically checks for the source code in the directory that
`configure' is in and in `..'.


Installation Names
------------------

By default, `make install' will install the DDD files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If
you give `configure' the option `--exec-prefix=PATH', the package will
use PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

You can cause DDD to be installed with an extra prefix or suffix on
its name by giving `configure' the option `--program-prefix=PREFIX' or
`--program-suffix=SUFFIX'.


External Packages
-----------------

By default, `configure' will configure DDD to use all supported
external packages available on your system.

`configure' can usually find the X include and library files
automatically, but if it doesn't, you can use the `configure' options
`--x-includes=DIR' and `--x-libraries=DIR' to specify their locations.

If `configure' doesn't find the Motif include and library files
automatically, you can use the `configure' options
`--with-motif-includes=DIR' and `--with-motif-libraries=DIR' to
specify their locations.

If `configure' doesn't find the Athena include and library files
automatically, you can use the `configure' options
`--with-athena-includes=DIR' and `--with-athena-libraries=DIR' to
specify their locations.

If `configure' doesn't find the Xpm include and library files
automatically, you can use the `configure' options
`--with-xpm-includes=DIR' and `--with-xpm-libraries=DIR' to specify
their locations.

If you wish to disable Athena widgets and rely on Motif widgets alone,
you can use the `configure' option `--without-athena'.  Likewise,
`--without-xpm' disables XPM support.  Don't use the `--without-motif'
option; DDD will not compile without Motif.


Optional Features
-----------------

By default, `configure' will configure DDD to use all supported
optional DDD features.

You can configure DDD such that the `Ddd' application defaults file
will not be compiled into the DDD executable.  This reduces the size
of the DDD executable by about 360k.  Note that this requires you to
install the application defaults file in a place where DDD will find
it; this also results in trouble if you want to maintain multiple DDD
versions.  To disable the builtin application defaults file, use the
`configure' option `--disable-builtin-app-defaults'.

You can configure DDD such that the DDD manual will not be compiled
into the DDD executable.  This reduces the size of the DDD executable
by about 60k.  `Help->DDD Reference' will then invoke `man ddd' to get
the DDD manual.  Note that this only works well if you use GNU `groff'
to format your manual pages.  To disable the builtin DDD manual, use
the `configure' option `--disable-builtin-manual'.



Specifying the System Type
--------------------------

There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host DDD will run
on.  Usually `configure' can figure that out, but if it prints a
message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:

     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.


Sharing Defaults
----------------

If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.


Operation Controls
------------------

`configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Save the results of the tests in FILE instead of `config.cache'.
     Set FILE to `/dev/null' to disable caching, for debugging
     `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.

`--srcdir=DIR'
     Look for the DDD source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.



Documentation
=============

The DDD Manual Page, contained in the file `ddd/ddd.man', is the
official DDD reference.  Note that DDD provides various on-line help
mechanisms.

Various formatted documents related to DDD are contained in the
`./doc' directory.  See the `./doc/README' file for details.


$Id: INSTALL,v 1.47 1998/06/18 14:45:23 zeller Exp $
