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