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

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

Requirements
============

    To build a complete DDD from sources, you need:

       * The GNU C++ compiler (GCC/G++), preferably version 2.7.2 or
	 later, and a matching C++ I/O 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.

       * The X window library (Xlib) and X toolkit library (Xt), X11R4
         or later.

       * A Motif Widget library, version 1.1 or later.  Best results
         are achieved using OSF/Motif 2.0 or later.

         DDD also compiles and runs with LessTif, a free Motif clone,
         release 0.82 or later, without loss of functionality.  Be
         sure to check the DDD WWW site and the `patches/' directory
         for patches required to make DDD run.  LessTif is available
         via `http://www.lesstif.org/'.

       * Optionally, in addition to the Motif widget library, the
         Athena Widget library (release 5 or later).  Having the
         Athena Widget library is convenient for supporting
         two-dimensional scrollbars and the `editres' protocol.

       * Optionally, the XPM library (release 3.2 or later).  The XPM
         library brings support for multi-color icons and logos.

       * Lots of virtual memory.

    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 and C++; GNU Ada
    (`gnat'), GNU Fortran (`g77') and GNU Modula-2 have been reported
    to work as well.

    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.


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

    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.

      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.  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, see the `PROBLEMS' and `BUGS' files.  If the
         problem is not listed, report it to the DDD maintainers
         <ddd-bugs@ips.cs.tu-bs.de>.  If you need help, 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.

     12. Like every good X citizen, DDD comes with an application
         defaults file, named `ddd/Ddd'.  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 Makefile(s), 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.  Your
         support is thus very appreciated.  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'.


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

    The DDD Manual Page, contained in the file `ddd/ddd.man', contains
    a short reference.  Note that DDD provides an on-line help system.

    Various formatted documents related to DDD are contained in the
    `./doc' directory.  See the `./doc/README' file for 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=g++-2.8.0 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'.


Optional Features
=================

    By default, `configure' will configure DDD to use all supported
    features 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.


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.



$Id: INSTALL,v 1.34 1998/01/27 16:41:24 zeller Exp $
