==========================
 Installing M2Crypto 0.13
==========================

:Author: Ng Pheng Siong
:Id: $Id: INSTALL,v 1.12 2004/03/25 08:48:40 ngps Exp $
:Date: $Date: 2004/03/25 08:48:40 $
:Web-Site: http://sandbox.rulemaker.net/ngps/m2

.. contents::


Pre-requisites
----------------

The following software packages are pre-requisites:

- **Python 2.1, 2.2 or 2.3**
- **OpenSSL 0.9.7 or later**
- **SWIG 1.3.21 or later**

.. NOTE:: 
   - Earlier versions of Python may or may not work. 
   - This release is incompatible with OpenSSL versions prior to 0.9.7. 
   - Earlier versions of SWIG may not work with new-style Python classes.

This distribution is tested with OpenSSL 0.9.7d.


Installing on Un\*x
--------------------

::

    $ unzip m2crypto-0.13.zip
    $ cd m2crypto-0.13
    $ python setup.py build
    # python setup.py install
    $ cd tests
    $ python alltests.py
    
Also see the examples in ``m2crypto-0.13/demo``.


Installing on Windows 
-----------------------

.. NOTE:: 
   As of M2Crypto 0.13, I am making Windows installers available for a
   small fee. These installers bundle assembler-powered OpenSSL DLLs which
   are smaller and faster than the DLLs generated by Mingw. Please support
   M2Crypto development by purchasing the installers. Thank you.

   The rest of this section has been left as is from M2Crypto 0.12's
   version of this file.


Before building from source, you need to install OpenSSL's include files,
import libraries and DLLs.

Here is the relevant section from setup.py::

    if os.name == 'nt':
        openssl_dir = 'c:\\pkg\\openssl'
        include_dirs = [my_inc, openssl_dir + '/include']
        library_dirs = [openssl_dir + '\\lib']
        libraries = ['ssl32', 'eay32']
        extra_compile_args = [ "-DTHREADING" ]
    
By convention, I place OpenSSL include files in ``c:\pkg\openssl\include``, 
and the import libraries in ``c:\pkg\openssl\lib``.


Preparation
~~~~~~~~~~~~~

Read Sebastien Sauvage's webpage:

     http://sebsauvage.net/python/mingw.html


Import Libraries
~~~~~~~~~~~~~~~~~~

For mingw32, the OpenSSL import libraries are named ``libeay32.a`` and
``libssl32.a``. 

You'll also need to create ``libpython2[123].a``, depending on your version
of Python.


OpenSSL DLLs
~~~~~~~~~~~~~~

OpenSSL DLLs for mingw32 are named ``libeay32.dll`` and ``libssl32.dll``.
Install these somewhere on your PATH; by convention, I place them in
``c:\bin``, together with ``openssl.exe``.


Installing
~~~~~~~~~~~~

Build M2Crypto:

    python setup.py build -cmingw32

Then,

::

    python setup.py install
    cd tests
    python alltests.py


.. NOTE:: 
   The following instructions for building M2Crypto with MSVC++ 6.0 and
   BC++ 5.5 free compiler suite are from M2Crypto 0.10. These instructions
   should continue to work for this release, although I have not tested
   them.


OpenSSL DLLs
~~~~~~~~~~~~~~

With MSVC++, the OpenSSL DLLs, as built, are named ``libeay32.dll``
and ``ssleay32.dll``. Install these somewhere on your PATH; by convention, 
I place them in ``c:\bin``, together with ``openssl.exe``. 


MSVC++
~~~~~~~~

For MSVC++, the import libraries, as built by OpenSSL, are named
``libeay32.lib`` and ``ssleay32.lib``.


BC++
~~~~~~

For BC++ these files are created from the MSVC++-built ones using the
tool ``coff2omf.exe``. I call them ``libeay32_bc.lib`` and
``ssleay32_bc.lib``, respectively.

You'll also need Python's import library, e.g., ``python22.lib``, to
be the BC++-compatible version; i.e., create ``python22_bc.lib`` from
``python22.lib``, save a copy of ``python22.lib`` (as ``python22_vc.lib``,
say), then rename ``python22_bc.lib`` to ``python22.lib``.


Installing
~~~~~~~~~~~~

Now you are ready to build M2Crypto. Do one of the following::

    python setup.py build
    python setup.py build -cbcpp

Then,

::

    python setup.py install
    cd tests
    python alltests.py


Building on Mac OS X
----------------------

Larry Bugbee has kindly updated the instructions for Mac OS X 10.2:

0. MacOSX 10.2 comes with OpenSSL 0.9.6x and installing a current version
can lead to incompatabilities between Apache and other apps depending
on 0.9.6.  I am not ready for the hassle to rebuild Apache and all the
other dependencies, so I built OpenSSL 0.9.7c in /usr/local with::

    ./config --prefix=/usr/local --openssldir=/usr/local/openssl
    make
    ...etc.

1. ``cd swig``

2. Check the path to the version of OpenSSL you want for M2Crypto. If
you decided to install a newer OpenSSL in /usr/local and not use
Apple's pre-installed version, the path in 'Makefile.osx' is ready to go.

3. make -f Makefile.osx

4. ``cd ..``

5. Move the directory ``M2Crypto`` into Python's ``site-packages`` directory.

6. If you have PyUnit installed::

     cd tests, python alltests.py

7. ``cd ..``

8. ``cd demo``

9. Try out the various test programs.

