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 (3.1 or later), including a matching
     C++ I/O runtime library (libstdc++ or libg++).

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

   * The Motif Widget library (2.3.4 or later)  
     - motif

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

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

   * Curses terminal manipulation library
     -   ncurses

   * X Athena Widgets (recommended)
     - libXaw

Be sure to install the headers for these libraries, usually in a 
a package named <pkg>-devel or similar.

If (and only if) you make changes to the DDD sources, or if you build
DDD from the repository, you may also need:

   * `automake' (after changes to Makefile templates)
   * `autoconf' (after changes to configuration files)
   * `libtool' (to recreate Makefiles)
   * `bison' and `flex' (after changes to parser and scanner files)
   * `texinfo' (after changes to documentation)
   * `netpbm' packages (after changes to icons)
   * `fig2dev' and ImageMagick `convert' (after changes to screenshots)
   * `texi2dvi' and LaTeX (for recreating the PostScript manual)
   * `epstopdf' and PDFLaTeX (for recreating the PDF manual)

For Ubuntu and Fedora distributions, you can check if the packages
required to build a DDD tarball are installed by running ./etc/install-prereq.
If you specify the '-maint' command line option, this will additionally 
check for the prerequisites for building from the source repository.

The DDD source package contains several pre-built files, such that you
should not need any of these programs.  (If your `make' program
invokes any of the programs above on an unchanged source package, this
is a potential bug.  Find out what's going on and let us know; use GNU
make as a workaround.)


Configure DDD from tarball
==========================

Download a tarball located at http://ftp.gnu.org/gnu/ddd/.

  $ tar xfz ddd-<version>.tar.gz
  $ mkdir build
  $ cd build

Configure DDD:

  $ ../ddd-<version>/configure

This will configure DDD to install in /usr/local.  If you want to
install in a different directory, for example, under your home
directory, specify --prefix:

  $ ../ddd-<version>/configure --prefix=$HOME

This may issue warnings about missing libraries or support programs.
Install these and re-run configure until it issues the following:

  configuration is done.  Type `make' to make DDD.

To build DDD, continue with the section titled "Make DDD" below.


Configuring DDD from the repository
===================================

If you have downloaded a tarball of DDD sources, skip this section.

To download DDD sources from the Savannah repository, you will
need to install the Subversion source management system if it is 
not already installed on your system.

DDD sources can be obtained from the FSF GNU Savannah website:
https://savannah.gnu.org/svn/?group=ddd.
We recommend that you do not download the entire DDD repository.  
It is more than 1.1Gb, including all branches and tags.

You may download a specific release of DDD or the top of the 
development tree.  To download a release, including latest updates,
use "branches/<release>" for <module> in the following commands.  If 
you want to download the top of the development tree, use "trunk"
for <module> in the following commands.  

The latest release of DDD is "DDD_3_4".  Note that the top of the
development tree may contain changes which have not been completely
tested. 

Download the latest sources:
  $ svn co svn://svn.savannah.gnu.org/ddd/<module> ddd
Configure for building DDD:
  $ cd ddd
  $ autoreconf -ifv
  $ cd ..
  $ mkdir build
  $ cd build

Configure DDD:

  $ ../ddd/configure 

Make DDD and Install
====================

Build DDD:

  $ make

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

If you receive errors that say "Warning: Cannot convert string"
when you run 'make check', please read the accompanying FONTS file.

Install DDD:

  $ make install

If you do not have write access to the installation directory 
(common if using the default /usr/local target) you will need
to run the last step as root:

  $ sudo make install


Cleanup
=======

 You can remove the program binaries, libraries and object files
from the source directory by typing
     
  $ make clean

(There is also `make mostlyclean', which removes all object files, 
but keeps the executables.)

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

(There is also `make maintainer-clean', which removes *each*
derived file included in the DDD distribution - such as LEX and
YACC output.  Do not use this unless you know what you're doing.)

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

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


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

To run DDD, you need:

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

     If you are running a UNIX-like system, you certainly have X.  

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

     - To debug binary executables, best results are achieved with
       GDB, the GNU debugger.  Using GDB, you can debug programs written 
       in C, C++, GNU Java (`guavac'), GNU Ada (`gnat'), GNU Fortran (`g77'),
       GNU Chill and GNU Modula-2.

       GDB also supports WDB, a GDB variant found on HP-UX systems.

     - As an alternative to GDB, DDD also supports the DBX debugger as
       found on SUN, Compaq, DEC, AIX, and IRIX systems.  DDD adapts
       automatically to a wide range of DBX variants.

       Note: In DDD, GDB support is better than DBX support.  Try GDB first.

     - As an alternative to GDB, DDD also supports the `ladebug'
       debugger as found on some Compaq and DEC systems.  This is useful
       if you use a compiler that is better supported by `ladebug' than
       by GDB.

       Note: In DDD, GDB support is better than `ladebug' support.
       Try GDB first.

     - To debug Bash programs, you will need a version of Bash that
       has the debugger extensions compiled in and the bash debugger,
       bashdb. Get bashdb from
       http://bashdb.sourceforge.net/download.html

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

       Please note: JDB is more a `proof of concept' than a real
       debugger.  DDD does its best to overcome JDB's limitations, but
       if you have an alternative to DDD/JDB, try it first.

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

     - To debug GNU Make Makefiles, you will need a version of GNU
       Make has the debugging extensions compiled. For now, the
       installed "make" is called usually called "remake". Get
       the GNU Make + debugger from 
       http://bashdb.sourceforge.net/remake/

     - To debug Python programs, DDD supports an extended version 
       of the stock Python debugger called PYDB. Get pydb from 
       the download link at http://bashdb.sourceforge.net/pydb/

     **** PLEASE NOTE:
     Other than GDB, no testing of the other debug engines has been 
     done in many years.  How well DDD works with them, or if it works
     at all, is uncertain.

   * Fonts

     DDD uses the Liberation Open Source fonts by default.  These are
     available on many systems.  If you experience problems installing
     or using these fonts, or wish to use other fonts, please read the 
     FONTS file.


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, version 4.0 or later,
     as well as various info files.

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

     - `info -f ddd' should show the DDD Manual (after installation).
       DDD uses this to display the DDD Manual.

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


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 CPPFLAGS=-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 and C++ compilers

`CFLAGS'
     Compilation flags used by the C compiler

`CXX'
     The name of 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 `..'.


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.  See also `Locating Libraries', below.
   
   * If `configure' doesn't find the M*tif include and library files
     automatically, you can use the `configure' options
     `--with-motif-includes=DIR' and `--with-motif-libraries=DIR' to
     specify their locations.  See also `Locating Libraries', below.
   
   * 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.  See also `Locating Libraries', below.
   
   * 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.  See also `Locating Libraries', below.
   
   * If `configure' doesn't find the Readline include and library files
     automatically, you can use the `configure' options
     `--with-readline-includes=DIR' and `--with-readline-libraries=DIR'
     to specify their locations.  See also `Locating Libraries', below.
   
   * If `configure' doesn't find a termcap compatible library files
     automatically, you can use the `configure' options
     `--with-termlib=LIB' and `--with-termlib-libraries=DIR'
     to specify their locations. See also `Locating Libraries', below.


You can also configure DDD to _ignore_ some external packages:

   * If you wish to disable Athena widgets and rely on M*tif 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 M*tif.
   
   * If you wish to disable command-line editing on standard input,
     use `--without-readline'.



Locating Libraries
------------------

If one of the libraries to be used with DDD is a dynamic library and
installed in a non-standard place (that is, in a place where the
run-time linker cannot find it), you can specify its location
explicitly.

The option `--enable-rpath=PATH' sets the path of directories to be
searched for dynamic libraries to PATH (a colon-separated list of
directories).

For instance, if you have a Motif library `libXm.so' installed in
`/you/cannot/find/me/' and a Readline library `libreadline.so'
installed in `/nobody/knows/i/am/here/', you can specify

    --enable-rpath=/you/cannot/find/me/:/nobody/knows/i/am/here/

to make sure these places are searched for libraries.

Note: `--enable-rpath' must be specified separately from
`--with-PACKAGE-libraries' and likewise because these are different
concepts:

   * `--with-PACKAGE-libraries' specifies the place to be searched at
     _link_ time;
   
   * `--enable-rpath' specifies the place to be searched at
     _execution_ time.



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

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

   * You can configure DDD such that the `Ddd' application defaults file
     will be compiled into the DDD executable.
   
     To enable the builtin application defaults file, use the `configure'
     option `--enable-builtin-app-defaults'.
   
   
   * You can configure DDD such that the DDD manual will be compiled into
     the DDD executable.
   
     To enable the builtin DDD manual, use the `configure' option
     `--enable-builtin-manual'.
   
   
   * You can configure DDD such that the DDD News will be compiled into
     the DDD executable.
   
     To enable the builtin DDD news, use the `configure' option
     `--enable-builtin-news'.
   
   
   * You can configure DDD such that the DDD License will be compiled into
     the DDD executable.
   
     To enable the builtin DDD news, use the `configure' option
     `--enable-builtin-license'.
   
   
   * You can configure DDD such that the DDD VSL library `ddd.vsl' will
     be compiled into the DDD executable.
   
     To enable the builtin VSL library, use the `configure' option
     `--enable-builtin-vsllib'.

See also `External Packages', above, to disable external packages such
as the Readline library used for command-line editing on standard input.


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.


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 at `http://savannah.gnu.org/bugs/?group=ddd'.  Be sure to
include a context diff (`diff -c2') between the original and the
changed file(s).


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

The DDD Manual, contained in the file `ddd/ddd.texi', is the official
DDD reference.  

Preformatted versions of the DDD Manual (in info, PostScript, and PDF
formats) can be found in the `doc/' subdirectory.  A HTML version
comes in a separate package.  Note that DDD also has various on-line
facilities.
