-------------------------------------------------------------------------------
$Id: INSTALL.1,v 1.13 1994/11/08 23:54:39 gray Exp $
-------------------------------------------------------------------------------

NOTE:

The library has gone through 2 name changes since its inception.

In version 3.0.0, the malloc files were renamed to libdmalloc.a and
dmalloc.h.  The old libmalloc_dbg.a and malloc_dbg.h files will have
to be removed if you've installed them.

Before version 1.2.0, the malloc files were named libmalloc.a and
malloc.h.  These files will also have to be removed if you've
installed them.

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

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

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

  1. First, please examine the `PERMISSIONS' file.  If you are using
     the library in a commercial setting, please consider paying for a
     licensed copy of the software.

  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 - especially 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*: 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. Typing `make tests' should build the `dmalloc_t' test program.

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

 10. Typing `make install' should install the `libdmalloc.a' and
     `libdmalloc_lp.a' library files in `/usr/local/lib', the `dmalloc'
     utility in `/usr/local/bin', and the `dmalloc.info' documentation
     file in `/usr/local/info'.

     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. First, please examine the `PERMISSIONS' file.  If you are using
     the library in a commercial setting, please consider paying for a
     licensed copy of the software.

  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. csh/tcsh users
     should add the following to their `.cshrc' file (notice the -C
     option for c-shell output):

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

     bash

     Bash and Zsh users should add the following to their `.bashrc' or
     `.zshrc' respectively file (notice the -b option for bourne shell
     output):

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

  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 ta-dah!



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