home *** CD-ROM | disk | FTP | other *** search
- 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.
-
- * A Motif Widget library. Either
-
- - LessTif, 0.87 or later, or
- - OSF/Motif (1.2 or later).
-
- Best results are obtained with OSF/Motif 2.0 and later. We
- recommend to use OSF/Motif or the most recent LessTif release,
- available from `http://www.lesstif.org/'.
-
- LessTif should be used in (default) Motif 1.2 compatibility mode.
- The Motif 2.0 compatibility mode of LessTif is still incomplete.
-
- * 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 support is no longer maintained in this DDD
- release. 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. Please report any bugs and problems to
- the DDD maintainers <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.
-
- Please check the `make' output for compiler warnings. Normally,
- DDD should build without any warnings. If you encounter
- warnings, these may indicate actual problems in DDD code.
-
- 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 a warning can be avoided by changing DDD code, send a
- bug report to the DDD maintainers <ddd-bugs@ips.cs.tu-bs.de>,
- including a context diff (`diff -c5') between the original and
- the changed file.
-
- 8. 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!
-
- 9. 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.
-
- 10. Optionally, type
-
- $ make strip
-
- to reduce the size of the `ddd' executable by stripping the
- debugging information.
-
- 11. 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/'.
-
- 12. 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.
-
- 13. 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.
-
- 14. 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 step
- 13, above, and the comment at the beginning of `Ddd' for details.
-
- 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.
-
- 15. 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.)
-
- 16. 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.
-
-
-
- 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 1998/12/01 11:07:33 zeller Exp $
-