====================
 Installing M2Crypto
====================

:Maintainer: Heikki Toivonen
:Web-Site: http://wiki.osafoundation.org/bin/view/Projects/MeTooCrypto

.. contents::


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

The following software packages are pre-requisites:

- **Python 2.3 or newer**
- **OpenSSL 0.9.7 or newer**
- **SWIG 1.3.24 or newer**


Installing on Unix-like systems, including Cygwin
-------------------------------------------------

::

    $ tar zxf m2crypto-0.17.tar.gz
    $ cd m2crypto-0.17
    $ python setup.py build
    $ python setup.py install

If you have installed setuptools you can also optionally run tests like this:

    $ python setup.py test

This assumes OpenSSL is installed in /usr. You can provide an alternate
OpenSSL prefix location with --openssl option to build command. Other
commands accept standard options if you need them.


Differences when installing on Windows
--------------------------------------

Before building from source, you need to install OpenSSL's include files,
import libraries and DLLs. By default setup.py assumes that OpenSSL include
files are in ``c:\pkg\openssl\include``, and the import libraries 
in ``c:\pkg\openssl\lib``. As with other platforms, you can specify a different
OpenSSL location with --openssl option.

Using OpenSSL 0.9.8 on Windows requires Python be built with applink.c 
(add an include statement in python.c).  This is not a requirement for 
Linux or MacOSX.  (applink.c is provided by OpenSSL.)


MSVC++
~~~~~~~~

setup.py is already configured to work with MSVC++ by default.

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

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


MINGW
~~~~~~~

.. NOTE:: 
   The following instructions for building M2Crypto with MINGW are from 
   M2Crypto 0.12. These instructions should continue to work for this release,
   although I have not tested them.

Read Sebastien Sauvage's webpage:

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

For mingw32, the OpenSSL import libraries are named ``libeay32.a`` and
``libssl32.a``. You may need to edit setup.py file for these.

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

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

Build M2Crypto:

    python setup.py build -cmingw32
    python setup.py install


BC++
~~~~~~

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

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 will need to edit setup.py file 
for these.

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


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


MacOSX
------

Follow the standard instructions to build and install M2Crypto.  
However, should you encounter difficulties, you may want to consider 
the following possibilities.

  - Distutils for Python 2.5 now provides support for universal 
    builds (ppc and i386) and Distutils requires a recent version 
    of Xcode.  See http://developer.apple.com/tools/download/

  - OpenSSL 0.9.7l gets installed in /usr with Apple's Security 
    Update 2006-007.  If you need features in OpenSSL 0.9.8, you 
    should consider installing 0.9.8 in /usr/local.  The commands 
    are:
    
      OpenSSL:
        ./config shared --prefix=/usr/local
        make
        make test
        sudo make install     [or... install_sw]
        
      M2Crypto:
        python setup.py build --openssl=/usr/local
        sudo python setup.py install --openssl=/usr/local