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:

     - Sun CC:  safe.
     - SGI CC:  safe if full ISO C++ is supported (including `bool').
                Earlier versions are unsafe: DDD may compile, but
                crashes after a few interactions.
     - DEC CXX: safe if full ISO C++ is supported (including `bool').
     - AIX xlC: safe if full ISO C++ is supported (including `bool').
                Earlier versions are unsafe: they introduce some minor errors.
     - Cfront 3.0: does not compile DDD.

     To avoid any risks, we strongly recommend to use the GNU C++
     compiler, such as GCC 2.95 or later.

   * A Motif Widget library.  Either

     - LessTif, 0.88 or later, or
     - OSF/Motif (1.2 or later).

     We recommend to use LessTif 0.88.9 or later, available from
     `http://www.lesstif.org/'.  Use LessTif in (default) Motif 1.2
     compatibility mode.

   * The X window library (Xlib) and X toolkit library (Xt), X11R4 or
     later.  Best results are obtained with X11R6.3 and later.

   * A `make' program.  We recommend GNU make.


We also recommend the following (optional) packages:

   * 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 panners - a
     kind of two-dimensional scrollbar.



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

To run DDD, you need:

   * An X server.  Without X, DDD does not run.

     If you are running a UNIX system, you certainly have X.  For
     Windows systems, free X servers are available.  See the DDD FAQ
     under `http://www.cs.tu-bs.de/softech/ddd/' for useful links.

   * A command-line debugger (the so-called `inferior' debugger).

     - To debug binary executables, best results are achieved with
       GDB, the GNU debugger.  (GDB 4.x is required; we recommend GDB
       4.17 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.  This is useful if
       you use a compiler that is better supported by DBX than by GDB.
       DDD adapts automatically to a wide range of DBX variants.

     - As another alternative, DDD may also support 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.

       Note that XDB will no longer be maintained 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/').

     - To debug Java bytecode programs, DDD supports JDB, the Java
       Debugger, as of JDK 1.1 and later.

     - To debug Python programs, DDD supports PYDB, a PDB extension.
       PYDB is included in the DDD distribution.

     - To debug Perl programs, DDD supports the Perl debugger as of
       Perl 5.003 and later.


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

   * The `gnuplot' program, version 3.5 or later.  DDD uses `gnuplot'
     to plot array and history data.


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 local `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
	
     instead to prevent `csh' from trying to execute `configure' itself.
     If you're building DDD on Windows using CYGWIN, type
     
	$ bash ./configure

     instead.

     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.  Any modern MAKE flavors should do, but for
     incremental reconstruction, GNU MAKE is required on most
     systems.

  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. Check the `make' output for compiler errors and warnings.

     If you see any compiler errors or warnings, please see the
     sections `Warnings during build' and `Errors during build', below.

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

 10. If DDD crashes immediately after startup or after a few
     interactions, first check your configuration (the output of
     `./ddd --configuration') for version mismatches.  Also check
     whether libraries and include files have matching versions.

     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.

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

 12. Please consider sharing your DDD binary with other people lacking
     Motif or a sane build environment.  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/'.

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

 14. If you have a `Ddd' app-defaults file installed from a previous
     DDD version, this file will *override* the built-in DDD settings
     and cause major problems.  Remove it.

 15. 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.  For
     details, see step 13, above, and the comment at the `Ddd' top.

     If you absolutely want to install it (or if you configured DDD
     such that `Ddd' is not compiled into DDD), copy `Ddd' to a place
     where app-defaults files are commonly found.

 16. 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.)

 17. You can remove DDD from your system by typing
 
	$ make uninstall

     This undoes all effects of a previous `make install'.


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.

In some cases, `configure' may require additional information about
these packages:

* `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.


You can also configure DDD to *ignore* some external packages:

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

* There is also a `--without-motif' option.  Don't use it; DDD will
  not compile without Motif.


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

By default, `configure' will configure DDD to use all supported
optional DDD features.  There are two optional 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 330 kBytes.  

  Note that this option requires you to install the application
  defaults file in a place where DDD will find it.  This option will
  also cause trouble if
  - you want to maintain multiple DDD versions or 
  - you upgrade to a new DDD version without removing or changing the
    application defaults file.

  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 80 kBytes.

  `Help->DDD Reference' will then invoke `man ddd' to get the DDD
  manual.  Note that this option only works well if man uses GNU
  `groff' to format manual pages (such as `man' on Linux).  Be sure to
  remove or update the manual page when upgrading to a new DDD version.

  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.



Warnings during build
---------------------

Normally, DDD should build without any warnings.  If you encounter
warnings, these may indicate actual problems in DDD code, showing up
in your particular configuration.

Warnings that can be ignored safely include warnings about code
not being reached and warnings about unused, uninitialized, or
shadowed variables.

However, GCC warnings that *must never be ignored* include:

- `implicit declaration of function F'
- `cannot pass objects of type T through `...''

If you encounter such a warning, GCC will generate unusable code.
Abort compilation and fix the problem.

If you find the warning can be avoided by changing some code or by
changing the DDD build process, please send a bug report to the DDD
maintainers <ddd-bugs@ips.cs.tu-bs.de>.  Be sure to include a context
diff (`diff -c5') between the original and the changed file(s).



Errors during build
-------------------

Normally, DDD should build without any errors.  If you encounter
errors, these indicate serious problems in either DDD code or your
particular configuration.

The `PROBLEMS' file contains a number of common problems encountered
during build, as well as fixes and workarounds.  If the problem is not
listed there, please ask a local expert for help.

If you find the error can be avoided by changing some DDD code or by
changing the DDD build process, please send a bug report to the DDD
maintainers <ddd-bugs@ips.cs.tu-bs.de>.  Be sure to include a context
diff (`diff -c5') between the original and the changed file(s).




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

The DDD Manual, contained in the file `ddd/ddd.man', is the official
DDD reference.  Note that DDD also has various on-line facilities.

A DDD manual in PostScript format (including several screen shots), as
well as other documents related to DDD are contained in the `./doc'
directory.  See the `./doc/README' file for details.


$Id: INSTALL,v 1.63.4.4 1999/08/10 15:11:56 andreas Exp $
