Purpose of this document
------------------------
This document provides information on how to install python-aprmd5 on a target
system. If you are an end user, read the section titled "End user installation".
If you are a packager, skip the end user section and read on below.


End user installation
---------------------
1. Download the source tar ball from the python-aprmd5 website
2. Extract the tar ball contents

     tar xfvzo python-aprmd5-x.y.tar.gz

3. Perform a build

    cd python-aprmd5-x.y
    ./setup.py build

4. Install. If you have system administration rights, just do this: 

     ./setup.py install

   You might also consider installing to some prefix directory such as
   /usr/local. In this case the command would be

     ./setup.py install --prefix=/usr/local

   Finally, if you want to install python-aprmd5 into your home directory, e.g.
   because you are not the system administrator, the command looks like this

    ./setup.py install --home=~

5. Wherever you installed python-aprmd5, in order to use the module the folder
   that contains the "aprmd5" package must be in your PYTHONPATH.

   If you need to adjust PYTHONPATH, a good starting place might be your
   ~/.bashrc file (if you are using bash).


Packager information
--------------------
The tar ball that can be downloaded from the project website has been created
using the Distutils Python module. In the terminology of Distutils, the tar
ball is a so-called "source distribution" intended to be converted by a packager
into a so-called "built distribution" (e.g. an RPM or Debian package).

If you are a packager, the next two sections give you an overview of the source
distribution's directory structure and the content of each directory. Another
section provides details about the changes that are necessary to build
python-aprmd5 on different platforms with different versions of libaprutil. The
final section has information on how to run automated tests to check whether
the built extension works correctly.


Directory structure
-------------------
The directory structure inside the source distribution tar ball looks like
this:

root
+-- src
|   +-- packages
|   |   +-- tests
|   +-- extension
+-- doc


Content description
-------------------
src/extension
- contains the C sources from which the extension is built

src/packages/tests
- contains automated tests that can be run to check whether python-aprmd5
  behaves as it should on your system; for details read the section
  "How to test python-aprmd5" further down
- the test files are not intended to go into the built distribution, although
  you may certainly include them if you wish to do so

doc
- contains documentation files such as this INSTALL document
- some of these files should probably go into the built distribution (e.g.
  README, LICENSE), whereas others are of minor interest and can be omitted
  (e.g. Roadmap, TODO)


How to build the project
------------------------
Before attempting to build the project, the file setup.py must be edited and a
few things changed so that the build matches your system and uses the correct
version of libaprutil. Hopefully, in a future version of python-aprmd5 this
manual editing will be replaced by auto-detection of the build system type and
the version of libaprutil that is installed on the system.

For now, however, the following variable assignments in setup.py need to be
reviewed, and if necessary changed (or commented out) to make the build work:

  aprmd5_header_filename
  aprmd5_library_filename
  include_dirs
  library_dirs
  extra_compile_args
  extra_link_args

Once setup.py has been edited to your satisfaction, a standard build of
python-aprmd5, using the default Python interpreter, may be performed with the
following command:

  ./setup.py build_ext

The following is an example how to build the project using a non-default Python
interpreter:

  /Library/Frameworks/Python.framework/Versions/3.1/bin/python3.1 setup.py build_ext

If the build succeeds, you can find the built extension somewhere below the
folder "build", in a directory whose name depends on the target platform. For
instance when I build python-aprmd5 with Python 3.1 on my PPC Mac box, the
extension is built here:

  build/lib.macosx-10.3-fat-3.1/aprmd5.so

Finally, the following example illustrates how to use environment variables to
define additional include or library search paths for gcc, without having to
modify setup.py:

  CPATH=/sw/include LIBRARY_PATH=/sw/lib ./setup.py build_ext

  
How to test python-aprmd5
-------------------------
The "src/packages/tests" folder contains a number of unit tests that can be
automatically run like this:

  ./setup.py test

To run tests from only one module (test_md5_encode.py in this example):

  ./setup.py test --suite=tests.test_md5_encode

If python-aprmd5 hasn't been installed on a system, the examples above probably
won't work because Python does not know where to find the built extension. The
problem can be fixed, for instance, by building python-aprmd5 into a known
location - the current directory:

  ./setup.py build_ext --inplace
  ./setup.py test

Another solution is to set PYTHONPATH to make the location of the built
extension known to the Python interpreter. For instance, after I have built the
extension with Python 3.1 on my PPC Mac box, I can run the following:

  PYTHONPATH=build/lib.macosx-10.3-fat-3.1 ./setup.py test


build-and-test.sh
-----------------
build-and-test.sh is a helper script that, for every Python version specified,
automatically performs the following steps:

1. Build the extension (setup.py build_ext)
2. Run unit tests (setup.py test)
3. Perform a test installation (setup.py install)

I use the script before I make a release, to test whether python-aprmd5 builds,
runs and installs on Mac OS X and Debian Linux (the two system types available
to me). You may find the script useful, although there is no guarantee
whatsoever that it works on other configurations than my own two systems that
I use for development.
