mpatrol.texi

debug source code under unix platform.

The library and tools can be built using the GNU autoconf, automake and libtool
utilities.  Build scripts are also supplied to build both installation packages
and binary distributions.  A Linux Software Map file is also provided.

@cindex test suite
@item
A small test suite is provided in order to test basic features.

@item
User documentation is currently available in @TeX{}info format as well as UNIX
manual pages and a quick reference card.  The source code for the library and
tools can also be formatted for a printed manual.
@end itemize

@node Installation, Integration, Features, Top
@chapter Installation
@cindex installation
@cindex building the library
@cindex library, building

@cindex Amiga 4000/040
@cindex Dell Inspiron 7500
The mpatrol library was initially developed on an Amiga 4000/040 running AmigaOS
3.1.  I then installed Red Hat Linux 5.1 on my Amiga and added support for
Linux/m68k.  I've now just recently purchased a Dell Inspiron 7500 Notebook PC
and put my Amiga in retirement, so development will now continue on Red Hat
Linux 6.2 and above on the Intel platform.  I've tried my best to make it as
easy as possible to build and install mpatrol on any system, but it isn't
likely to run smoothly for everybody.  However, there shouldn't be any major
problems if you perform the following steps.

@cindex CHECKSUMS
@cindex md5sum
Note that if you want to check the integrity of the files that came with the
mpatrol distribution you can use the @file{CHECKSUMS} file in the @file{mpatrol}
base directory.  You must have the @command{md5sum} command installed on your
system in order to make use of this file.

@cindex autoconf
@cindex automake
@cindex libtool
@cindex configure
@cindex setup
@cindex cleanup
@cindex distclean (make target)
If you wish to use GNU autoconf, automake and libtool to build and install
mpatrol you may do so by entering the @file{pkg/auto} directory and typing
@samp{./setup}.  This will construct the directory structure that is required
by these tools and will also create a @file{configure} script.  Please see the
@file{INSTALL} file in that directory for information on how to proceed.  Note
that you can clean up the @file{pkg/auto} directory by typing @samp{make
distclean} (if the @file{configure} script has already been run) followed by
@samp{./cleanup}.

For a manual installation, perform the following steps.

@enumerate 1
@item
Go into the @file{build} directory and then into the appropriate subdirectory
for your system.

@cindex Makefile
@cindex CC
@cindex AR
@cindex LD
@cindex CFLAGS
@cindex OFLAGS
@cindex SFLAGS
@cindex TFLAGS
@cindex GUISUP
@cindex compiling
@cindex compiler
@cindex linking
@cindex linker
@cindex optimisation
@item
Edit the @file{Makefile} in that directory and check that it is using the
appropriate compiler and build tools.  The @code{CC} macro specifies the
compiler@footnote{On many systems this actually a C++ compiler by default, and
should be a C++ compiler if you wish to use the C++ operators.}, the @code{AR}
macro specifies the tool used to build the archive library and the @code{LD}
macro specifies the tool to build the shared library.  The @code{CFLAGS} macro
specifies compiler options that are always to be used, the @code{OFLAGS} macro
specifies optimisation options for the compiler, the @code{SFLAGS} macro
specifies options to be passed to the compiler when building a shared library
and the @code{TFLAGS} macro specifies options to be passed to the compiler when
building a thread-safe library.  You may also need to change the library names
and library build commands on different systems.

Note that the generic UNIX @file{Makefile} contains a macro called @code{GUISUP}
which is set to @code{false} by default.  If it is set to @code{true} then the
@command{mptrace} command will be built with GUI support enabled.  However,
your system must contain the correct header files and libraries in order to
support this.

@cindex make
@cindex all (make target)
@cindex lint (make target)
@cindex clean (make target)
@cindex clobber (make target)
@cindex lint
@item
Use the @command{make} command (or equivalent) to build the mpatrol library in
archive form.  The @samp{all} target builds all possible combinations of the
mpatrol library for your system.  The @samp{clean} target removes all relevant
object files from the current directory, while the @samp{clobber} target also
removes all libraries that have been built from the current directory.  On some
UNIX platforms, the @samp{lint} target will build a @command{lint} library for
the mpatrol library.

@cindex Inuse
@item
If the mpatrol library is to be built with support for Parasoft Inuse then the
@code{MP_INUSE_SUPPORT} preprocessor macro must be defined in the
@code{CFLAGS} portion of the @file{Makefile} before building.  This will ensure
that Inuse will be notified of every memory allocation, reallocation and
deallocation, but the Insure++ runtime library will also have to be linked in
with any program that uses mpatrol.

@cindex symbolic links
@cindex links, symbolic
@cindex ldconfig
@item
Copy all of the libraries that have been built into your local library
directory.  If there were symbolic links created in the @file{build} directory
then these should be recreated in the local library directory rather than simply
copying them.  You may need to run a command such as @command{ldconfig} in order
for the system to recognise the newly-installed libraries, and you may also need
to add the filename of the directory containing the newly-installed libraries to
an environment variable such as @env{LD_LIBRARY_PATH} if you installed the
libraries in a non-standard location.

@item
Copy the @command{mpatrol}, @command{mprof}, @command{mptrace} and
@command{mleak} programs that have been built into your local bin directory.
You may also wish to copy the @command{mpsym}, @command{mpedit} and
@command{hexwords} commands to your local bin directory as well if your system
supports Bourne shell scripts.

@item
Go up two directory levels into the @file{src} directory and copy the
@file{mpatrol.h}, @file{mpalloc.h} and @file{mpdebug.h} header files into your
local include directory.

@item
Go up one directory level into the @file{tools} directory and copy all of the
header files into the @file{mpatrol} subdirectory (which you'll need to create)
in your local include directory.

@cindex manual pages
@item
On UNIX platforms, go up one directory level into the @file{man} directory and
copy the @file{man1} and @file{man3} subdirectories to your local man directory.
Unfortunately, the location for manual pages varies from system to system so you
may or may not also be able to copy the @file{cat1} and @file{cat3}
subdirectories as well.  The @file{man*} subdirectories contain the unformatted
manual pages while the @file{cat*} subdirectories contain the formatted manual
pages.

@cindex @TeX{}info
@cindex La@TeX{}
@cindex documentation
@cindex reference card
@cindex quick reference card
@cindex printing
@item
Go up one directory level into the @file{doc} directory and examine the files
located there.  The @file{mpatrol.texi} file contains the @TeX{}info source for
this manual and can be translated into a wide variety of documentation formats.
The @file{refcard.tex} file contains the La@TeX{} source for the quick reference
card and can be translated into formats suitable for printing onto a few pages.
There should already be translated files in the @file{doc} directory, but if not
you will have to generate them yourself using the @file{Makefile} provided.  You
can then install or print these documents.

@cindex source code documentation
The mpatrol library source code can also be formatted for a printed manual for
later perusal.  The @samp{source} target in the @file{Makefile} within the
@file{doc} directory can be used to build the source code documentation in DVI,
postscript and PDF formats, but be prepared for a large number of pages!

If you are not installing on a system that supports UNIX manual pages then you
should also check in the @file{man} directory to ensure that there are
alternative formats for the mpatrol manual pages that you can install.  If not,
you will have to generate them yourself using the @file{Makefile} provided.
@end enumerate

@cindex PKG package
@cindex SD/UX package
@cindex RPM package
@cindex Debian package
@cindex TAR archive
@cindex LhA archive
@cindex ZIP archive
Alternatively, the @file{pkg} directory contains files that can be used to
automatically generate a @emph{package} in a specific format suitable for
installation on a system.  Four package formats (PKG, SD/UX, RPM and Debian) and
three archive formats are currently supported (generic tape archive, LhA and
ZIP).

The first package format is generally used on UNIX SVR4 systems, while the
second is used on HP/UX systems.  The RPM and Debian package formats were
introduced by Red Hat and Debian respectively for use in their Linux
distributions.

@cindex Aminet
@cindex WinSite
The generic tape archive can be used as a distribution for UNIX systems where no
package format is supported, but it does not contain information on how to
install the files on the system once they have been extracted from the
distribution.  The LhA and ZIP formats are also roughly the same, but the LhA
format is intended for Amiga systems and is used for Aminet distributions, while
the ZIP format is intended for Windows systems and is used for WinSite
distributions.

You should really know what you are doing before you attempt to build a package,
and you should also be aware that some of the package files may need to be
modified before you begin.

@cindex Linux Software Map
@cindex LSM
In addition, a Linux Software Map index file exists in the @file{pkg/lsm}
directory.

@cindex extra
Note that the @file{extra} directory that comes with the mpatrol distribution
contains several prototype configuration files for certain third-party programs.
These files should be examined so that you can decide whether to integrate their
contents into your existing configuration files.  The purpose of each file is
described in the relevant sections of this manual.

@node Integration, Memory allocations, Installation, Top
@chapter Integration
@cindex integration

This section describes how to go about adding or removing the mpatrol library
from your code.  There are several levels for each category so it is worth
reading about each before proceeding.

@menu
* Adding mpatrol::              Adding mpatrol to your program.
* Removing mpatrol::            Removing mpatrol from your program.
@end menu

@node Adding mpatrol, Removing mpatrol, , Integration
@section Adding mpatrol
@cindex adding mpatrol

@cindex recompilation
The following steps should allow you to easily integrate the mpatrol library
into an existing application, although some of them may not be available to do
on many platforms.  They are listed in the order of number of changes required
to modify existing code --- the last step will require a complete recompilation
of all your code.

@enumerate 1
@item
This step is currently only available on DYNIX/ptx, FreeBSD, IRIX, Linux,
NetBSD, OpenBSD, Solaris and Tru64 platforms and on DG/UX 4.20MU07@footnote{Also
available on DG/UX 4.20MU05 with patch dgux_R4.20MU05.p59 and DG/UX 4.20MU06
with patch dgux_R4.20MU06.p08.} or later platforms with the @env{LD_PRELOAD}
feature.

If your program or application has been dynamically linked with the system C
library (@file{libc.so}) or an alternative malloc shared library then you can
use the @option{--dynamic} option to the @file{mpatrol} command to override the
default definitions of @code{malloc()}, etc.@: at run-time without having to
relink your program.  If your program is multithreaded then you must also add
the @option{--threads} option to pick up the multithreaded shared libraries
instead.

For example, if your program's executable file is called @file{testprog} and it
accepts an option specifying an input file, you can force the system's dynamic
linker to use mpatrol's versions of @code{malloc()}, etc.@: instead of the
default versions by typing:

@smallexample
mpatrol --dynamic ./testprog -i file
@end smallexample

The resulting log file should be called @file{mpatrol.<procid>.log} by default
(where @var{procid} is the current process id), but if no such file exists after
running the @file{mpatrol} command then it will not be possible to force the
run-time linking of mpatrol functions to your program and you will have to
proceed to the next step.  Note that the @command{mpatrol} command overrides
any previous setting of the @env{MPATROL_OPTIONS} environment variable.

@item
This step is currently only available on UNIX and Windows platforms (and AmigaOS
when using @command{gcc}).