3. Installation

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.

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

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

For a manual installation, perform the following steps.

1. Go into the `build' directory and then into the appropriate subdirectory for your system.

2. Edit the `Makefile' in that directory and check that it is using the appropriate compiler and build tools. The CC macro specifies the compiler(1), the AR macro specifies the tool used to build the archive library and the LD macro specifies the tool to build the shared library. The CFLAGS macro specifies compiler options that are always to be used, the OFLAGS macro specifies optimisation options for the compiler, the SFLAGS macro specifies options to be passed to the compiler when building a shared library and the 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 `Makefile' contains a macro called GUISUP which is set to false by default. If it is set to true then the 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.

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

4. If the mpatrol library is to be built with support for Parasoft Inuse then the MP_INUSE_SUPPORT preprocessor macro must be defined in the CFLAGS portion of the `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.

5. Copy all of the libraries that have been built into your local library directory. If there were symbolic links created in the `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 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 LD_LIBRARY_PATH if you installed the libraries in a non-standard location.

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

7. Go up two directory levels into the `src' directory and copy the `mpatrol.h', `mpalloc.h' and `mpdebug.h' header files into your local include directory.

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

9. On UNIX platforms, go up one directory level into the `man' directory and copy the `man1' and `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 `cat1' and `cat3' subdirectories as well. The `man*' subdirectories contain the unformatted manual pages while the `cat*' subdirectories contain the formatted manual pages.

10. Go up one directory level into the `doc' directory and examine the files located there. The `mpatrol.texi' file contains the TeXinfo source for this manual and can be translated into a wide variety of documentation formats. The `refcard.tex' file contains the LaTeX 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 `doc' directory, but if not you will have to generate them yourself using the `Makefile' provided. You can then install or print these documents.

    The mpatrol library source code can also be formatted for a printed manual for later perusal. The `source' target in the `Makefile' within the `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 `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 `Makefile' provided.

Alternatively, the `pkg' directory contains files that can be used to automatically generate a 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.

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.

In addition, a Linux Software Map index file exists in the `pkg/lsm' directory.

Note that the `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.