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

:Maintainer: Heikki Toivonen
:Web-Site: http://chandlerproject.org/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.28 or newer**

Note about OpenSSL versions early in the 0.9.7 series
-----------------------------------------------------

Early OpenSSL 0.9.7 versions require the __i386__ symbol to be defined.
Uncomment this line in setup.py:

  #'-D__i386__', # Uncomment for early OpenSSL 0.9.7 versions

if you get this compile-time error:
  
  This openssl-devel package does not work your architecture?

Note about Fedora Core -based Distributions
-----------------------------------------------------

Fedora Core (and RedHat, CentOS etc.) have made changes to OpenSSL
configuration compared to many other Linux distributions. If you can not
build M2Crypto normally, try the fedora_setup.sh script included with
M2Crypto sources.

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

::

    $ tar zxf m2crypto-<version>.tar.gz
    $ cd m2crypto-<version>
    $ 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_ext command. Other
commands accept standard options if you need them.

Some distributions, like Fedora Core, package OpenSSL headers in a different
location from OpenSSL itself. In that case you need to tell build_ext the
additional include location with -I option.

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 to build_ext command.

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 build_ext --openssl=/usr/local
        sudo python setup.py install build_ext --openssl=/usr/local

To make Universal builds, you will need to uncomment a line in setup.py:

  extra_link_args = ['-Wl,-search_paths_first'],
  
If that does not work, here is what Marc Hedlund was able to get working:

  First, download OpenSSL 0.9.8d and unpack it.  Edit the OpenSSL Makefiles 
  per PROBLEMS.  Then:

    ./config no-shared no-asm --prefix=/usr/local
    make
    make test
    sudo make install
    make clean
    ./Configure no-shared no-asm --prefix=/usr/local darwin-ppc-cc
    make build_libs "CC=cc -arch ppc"
    lipo -info lib*
    mkdir -p build/ppc
    mv lib* build/ppc
    make clean
    ./Configure no-shared no-asm --prefix=/usr/local darwin-i386-cc
    make build_libs "CC=cc -arch i386"
    lipo -info lib*
    mkdir -p build/i386
    mv lib* build/i386/
    /bin/ls -1 build/i386/ > libnames.tmp
    mkdir universal

  Create a script in the OpenSSL directory called 'make_universal', with these
  contents:

    #!/bin/sh
    for lib in `cat libnames.tmp`; do
     lipo -create build/*/$lib -output universal/$lib
    done
    exit 0

  Then:

    sh make_universal
    lipo -info universal/lib*
    sudo cp universal/lib* /usr/local/lib
    lipo -info /usr/local/lib/lib{crypto,ssl}*
    cd ../m2crypto-0.17

  Then edit the m2crypto setup.py and uncomment the extra_link_args line at 
  the end.

    python setup.py build build_ext --openssl=/usr/local
    sudo python setup.py install build_ext --openssl=/usr/local