-------------------------------------------------------------------------------

Installation of the Library
===========================

   To configure, compile, and install the library, follow these steps
carefully.

  1. Make sure you have the latest version of the library available
     from the home page `http://www.dmalloc.com/'.

  2. You probably will want to edit the settings in `settings.dist' to
     tune specific features of the library.  The below `configure'
     script will copy this file to `settings.h' which is where you
     should be adding per-architecture settings.

  3. Type `sh ./configure' to configure the library.  You may want to
     first examine the `config.help' file for some information about
     configure.  Configure should generate the `Makefile' and some
     configuration files automatically.

     *NOTE*: It seems that some versions of tr (especially from HP-UX)
     don't understand `tr '[a-z]' '[A-Z]''.  Since configure uses tr
     often, you may need to either get GNU's tr (in their textutils
     package) or generate the `Makefile' and `conf.h' files by hand.

  4. You may want to examine the `Makefile' and `conf.h' files created
     by configure to make sure it did its job correctly.

  5. You might want to tune the settings in `settings.h' file to tune
     the library to the local architecture.  This file contains relevant
     settings if you are using pthreads or another thread library.  The
     `configure' script created this file from the `settings.dist'
     file.  Any permanent changes to these settings should made to the
     dist file.  You then can run `config.status' to re-create the
     `settings.h' file.

  6. The `DMALLOC_SIZE' variable gets auto-configured in `dmalloc.h.2'
     but it may not generate correct settings for all systems.  You may
     have to alter the definitions in this file to get things to stop
     complaining when you go to compile about the size arguments to
     malloc routines.  Comments on this please.

  7. Typing `make' should be enough to build `libdmalloc.a',
     `libdmalloclp.a', and `dmalloc' program.  If it does not work,
     please see if there are any notes in the contrib directory about
     your system-type.  If not and you figure your problem out, please
     send me some notes so future users can profit from your
     experiences.

     *NOTE*: You may experience some errors compiling some of the
     return.h assembly macros which attempt to determine the callers
     address for logging purposes.  You may want to first try disabling
     any compiler optimization flags.  If this doesn't work then you
     may need to disable the `USE_RET_ADDRESS' variable in the
     `settings.h' file.

     *NOTE*: The code is pretty dependent on a good ANSI-C compiler.  If
     the configure script gives the `WARNING' that you do not have an
     ANSI-C compiler, you may still be able to add some sort of option
     to your compiler to make it ANSI.  If there such is an option,
     please send it to the author so it can be added to the configure
     script.  Otherwise, you will have to try `make noansi'.  This will
     run the `Deansify.pl' perl script on the code which:

        * *WARNING*: modifies the source code in place

        * changes `stdarg.h' and `...' to `varargs.h' and `va_alist'

        * changes all `void *' references to `char *'.

        * fixes all functions to remove `foo(char * var)' declarations.

     If it doesn't work you may have to do Deansify.pl's job by hand.

  8. If you use threads, typing `make threads' should be enough to
     build `libdmallocth.a' which is the threaded version of the
     library.  This may or may not work depending on the configuration
     scripts ability to detect your local thread functionality.  Feel
     free to send me mail with improvements.

     See the "Using With Threads" section for more information about the
     operation of the library with your threaded program.  *Note Using
     With Threads::.

  9. See the `dmalloc.cc' C++ file which contains basic code to
     overload the `new', `new[]', and `delete' C++ operators.  You may
     want to compile and include this object file in the dmalloc
     libraries.  My apologies on the minimal C++ support.  I am still
     living in a mostly C world.

 10. Typing `make tests' should build the `dmalloc_t' test program.

 11. Typing `make light' should run the `dmalloc_t' test program
     through a set of light trials.  By default this will execute
     `dmalloc_t' 5 times - each time will execute 10,000 malloc
     operations in a very random manner.  Anal folks can type `make
     heavy' to up the ante.  Use `dmalloc_t --usage' for the list of all
     `dmalloc_t' options.

 12. Typing `make install' should install the `libdmalloc.a' and
     `libdmalloc_lp.a' library files in `/usr/local/lib', the
     `dmalloc.h' include file in `/usr/local/include', and the
     `dmalloc' utility in `/usr/local/bin'.  You may also want to type
     `make installth' to install the thread libraries into place.

     You may have specified a `--prefix=PATH' option to configure in
     which case `/usr/local' will have been replaced with `PATH'.


   See the "Getting Started" section to get up and running with the
library.  *Note Getting Started::.

   *NOTE*: This library has never been (and maybe never will be)
optimized for space nor speed.  in fact, some of its features make it
unable to use some of the organizational methods of other more efficient
heap libraries.


-------------------------------------------------------------------------------

Getting Started with the Library
================================

   This section should give you a quick idea on how to get going.
Basically, you need to do the following things to make use of the
library:

  1. Make sure you have the latest version of the library available
     from the home page `http://www.dmalloc.com/'.

  2. Follow the installation instructions on how to configure and make
     and install the library (i.e. type: `make install').  *Note
     Installation::.

  3. You need to make sure that the dmalloc building process above was
     able to locate one of the the `on_exit' or `atexit' functions.  If
     so, then the dmalloc library should be able to automatically call
     `dmalloc_shutdown' when `exit' is called.  This causes the memory
     statistics and unfreed information to be dumped to the log file.
     However, if your system has neither, you will need to call
     `dmalloc_shutdown' yourself before your program exits.

  4. Add an alias for dmalloc to your shell's rc file.  Bourne, bash,
     ksh, and zsh users should add the following to their `.bashrc' or
     `.zshrc' file respectively (notice the -b option for bourne shell
     output):

          function dmalloc { eval `command dmalloc -b $*` }

     By the way, if you are looking for a shell, I heartily recommend
     trying out zsh.  It is a bourne shell written from scratch with
     much the same features as tcsh without the csh crap.  If you are
     *still* using csh or tcsh, you should add the following to your
     `.cshrc' file (notice the -C option for c-shell output):

          alias dmalloc 'eval `\dmalloc -C \!*`'

  5. Although not necessary, you may want to include `dmalloc.h' in
     your C files and recompile.  This will allow the library to report
     the file/line numbers of calls that generate problems.  *Note
     Allocation Macros::.

  6. Link the dmalloc library into your program.

  7. Enable the debugging features by typing `dmalloc -l logfile -i 100
     low' (for example).  This will:

        * set the malloc log path to `logfile' (`-l logfile')

        * have the library check itself every 100 iterations (`-i 100')

        * enable a number of debug features (`low').  You can also try
          `runtime' for minimal checking or `medium' or `high' for more
          extensive heap verification.  `all' is also provided but
          generates a multitude of log messages without many more tests.

     `dmalloc --usage' will provide verbose usage info for the dmalloc
     program.  *Note Dmalloc Program::.

     You may also want to install the `dmallocrc' file in your home
     directory as `.dmallocrc'.  This allows you to add your own
     combination of debug tokens.  *Note RC File::.

  8. Run your program, examine the logfile that should have been
     created by dmalloc_shutdown, and use its information to help debug
     your program.

     *NOTE*: If a log file has not been created then go back and repeat
     these items carefully.  You may want to use `ident' or `strings'
     on your program and `grep' for `chunk.c,v' to make sure that the
     library is actually getting linked into your program.



-------------------------------------------------------------------------------
$Id: INSTALL.1,v 1.15 1999/03/09 05:00:39 gray Exp $
-------------------------------------------------------------------------------
