-------------------------------------------------------------------------------
$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 - for instance handling
     local thread library features.  The `configure' script created this
     file from the `settings.dist' 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.  In general 64 bit systems usually have lots of
     warnings about int to pointer promotion.

     *NOTE*: The code is pretty dependent on a good ANSI-C compiler like
     gcc.  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 can `/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. 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 \!*`'

     zsh users should add the following to their `.zshrc' file (notice
     the -b option for bourne shell output):

          dmalloc() { eval `command dmalloc -b $*` }

  4. 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::.

  5. Link the dmalloc library into your program.

  6. 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::.

  7. Run your program, examine the logfile, and voila!



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