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

How to Install 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://dmalloc.com/'.

  2. You probably will want to edit the settings in `settings.dist' to
     tune specific features of the library.  The `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.  You may want to use the `--disable-cxx' option if you
     do not want the Makefile to build the C++ version of dmalloc.  You
     may want to use the `--enable-threads' option to build the
     threaded version of dmalloc.  You may want to use the
     `--enable-shlib' option to build the shared versions of the
     dmalloc libraries.  Configure should generate the `Makefile' and
     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.
     *Note Using With Threads::.  The `configure' script created this
     file from the `settings.dist' file.  Any permanent changes to these
     settings should made to the `settings.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_RETURN_MACROS' variable in the
     `settings.h' file.

     _NOTE_: The code is dependent on an 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.

  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. If you have a C++ compiler installed, the library should have
     automatically built `libdmallocxx.a' which is the C++ version of
     the library.  If it was not done automatically, you can build it by
     typing `make cxx'.  You should link this library into your C++
     programs instead of `libdmalloc.a'.  See the `dmallocc.cc' C++
     file which contains basic code to overload the `new', `new[]',
     `delete', and `delete[]' C++ operators.  My apologies on the
     minimal C++ support.  I am still living in a mostly C world.  Any
     help improving this interface without sacrificing portability
     would be appreciated.

 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 library into place and/or
     `make installcc' to install the C++ library 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::.


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

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://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 if supported.
     Bash, ksh, and zsh users should add the following to their
     `.bashrc', `.profile', 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::.  It should be inserted at the _bottom_ of
     your include files as to not conflict with other includes.  You
     may want to ifdef it as well and compile with `cc -DDMALLOC ...':

          /* other includes above ^^^ */
          
          #ifdef DMALLOC
          #include "dmalloc.h"
          #endif

  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. You may also want to enable the `log-unknown' token (`dmalloc -p
     log-unknown') which will log non-freed information about "unknown"
     memory to the log file.  Unknown means memory that does not have
     associated file and line information.  This is necessary if you
     are _not_ including `dmalloc.h' in your C files or if you want to
     track possible memory leaks in system functions.

  9. Run your program, examine the logfile that should have been
     created by dmalloc_shutdown, and use its information to help debug
     your program.  See the next section for help with this.  *Note
     Troubleshooting::.



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

Some Solutions to Common Problems
=================================

   This section provides some answers to some common problems and
questions.  Please feel free to send me mail with any additions to this
list - either problems you are still having or tips that you would like
to pass on.

`Why does my program run so slow?'
     This library has never been (and maybe never will be) optimized for
     space nor speed.  Some of its features make it unable to use some
     of the organizational methods of other more efficient heap
     libraries.  If you have the `check-heap' token enabled, see the
     `-i' option to the dmalloc utility.  *Note Dmalloc Program::.

`Why was a log-file not produced after I ran my program?'
     This could be caused by a number of different problems.

       1. Are you sure you followed all of the items in the "Getting
          Started" section?  Please review them if there is any doubt.
          *Note Getting Started::.

       2. Use the `env' or `printenv' commands to make sure that the
          `DMALLOC_OPTIONS' variable is set in your exported
          environment.  *Note Environment Variable::.

       3. Make sure that your program has been compiled correctly with
          the dmalloc library.  The `ident' program should show chunk.c
          and other dmalloc files compiled into your program.  You can
          also do `strings -a your-program | grep chunk.c' and look for
          something like `$Id: chunk.c,v 1.152 1999/08/25 12:37:01 gray
          Exp $' with different versions and date information.  If this
          doesn't show up then chances are dmalloc was not linked into
          your program.

       4. If your program changes its working directory, it may write
          the dmalloc log-file somewhere else in the filesystem.  You
          will need to check both where the program was started and to
          where it might change directory.


`I don't see any information about my non-freed (leaked) memory?'
     The library will not (by default) report on "unknown" non-freed
     memory.  Unknown means memory that does not have associated file
     and line information.  To log information about unknown pointers
     you should enable the `log-unknown' token (`dmalloc -p
     log-unknown').  This will be necessary if you are _not_ including
     `dmalloc.h' in all of your C files or if you are interested in
     tracking leaks in system functions.


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