INSTALLATION INSTRUCTIONS FOR pyOpenSSL
------------------------------------------------------------------------------

I have tested this on Debian Linux systems (woody and sid), Solaris 2.6 and
2.7. Others have successfully compiled it on Windows and NT.


-- Building the Module on a Unix System --

pyOpenSSL uses distutils, so there really shouldn't be any problems. To build
the library:

  $ python setup.py build

If your OpenSSL header files aren't in /usr/include, you may need to supply
the -I flag to let the setup script know where to look. The same goes for the
libraries of course, use the -L flag. Note that build won't accept these
flags, so you have to run first build_ext and then build! Example:

  $ python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib
  $ python setup.py build

Now you should have a directory called OpenSSL that contains e.g. SSL.so and
__init__.py somewhere in the build dicrectory, so just:

  $ python setup.py install

If you, for some arcane reason, don't want the module to appear in the
site-packages directory, use the --prefix option.

You can, of course, do

  $ python setup.py --help

to find out more about how to use the script.


-- Building the Module on a Windows System --

First you should get OpenSSL linked with the same runtime library that Python
uses.  If you are using Python 2.6 you can use the installer at:

  http://www.slproweb.com/products/Win32OpenSSL.html

The binaries in the installer are built with Visual Studio 2008 at the
time of this writing, which is the same compiler used for building the
official Python 2.6 installers.

If you want to build pyOpenSSL for an older Python version, it is preferred
to build OpenSSL yourself, either with the Visual Studio 2003 compiler or
with the MinGW compiler.  This way you avoid all potential incompatibilities
between different versions of runtime library (msvcrt.dll).  To build
OpenSSL follow the instructions in its source distribution and make sure
that you build a shared library, not a static one.  pyOpenSSL fails some of
its tests when linked with the static OpenSSL libraries.  Use the same
compiler for OpenSSL that you will use for pyOpenSSL later.  Make sure that
OpenSSL is properly installed before continuing.  To install OpenSSL when
building with MinGW, use the folowing script:

set OPENSSL_INSTALL_DIR=%1
mkdir %OPENSSL_INSTALL_DIR%
mkdir %OPENSSL_INSTALL_DIR%\bin
mkdir %OPENSSL_INSTALL_DIR%\include
mkdir %OPENSSL_INSTALL_DIR%\include\openssl
mkdir %OPENSSL_INSTALL_DIR%\lib
copy /b .\*.dll            %OPENSSL_INSTALL_DIR%\bin
copy /b .\out\openssl.exe  %OPENSSL_INSTALL_DIR%\bin
copy /b .\outinc\openssl\* %OPENSSL_INSTALL_DIR%\include\openssl
copy /b .\out\*.a          %OPENSSL_INSTALL_DIR%\lib

Ensure that OpenSSL's openssl.exe executable can be found on PATH before
running pyOpenSSL's setup script.  The setup script finds OpenSSL's include
dir and lib dir based on the location of openssl.exe, and the test suite
requires openssl.exe for output comparison.  Alternatively, you can specify
the --with-openssl option to setup.py's build_ext command with the path to
the OpenSSL installation dir:

  > python setup.py build_ext --with-openssl=C:\path\to\openssl build

pyOpenSSL is known to build with mingw32 for Python 2.3 through Python 2.5.
Before using the mingw32 compiler for Python 2.3, you will have to create
a Python library that MinGW understands. Find and download the pexports
program, put it and MinGW's bin directory on path, then run from Python's
install dir:

> pexports python23.dll > libs\python23.def
> dlltool --dllname python23.dll --def libs\python23.def \
          --output-lib libs\libpython23.a

For Python 2.4 and 2.5, no special preparation is needed, just make sure that
MinGW's gcc is on PATH.  You can specify that mingw32 be used by passing
the --compiler argument to build_ext:

  C:\pyOpenSSL-X.Y> setup.py build_ext -c mingw32 bdist_msi

The bdist_msi command will build an MSI installer.  It can be substituted
with another bdist command if another kind of installer is desired or with
the install command if you want to install directly.

For Python 2.4 and 2.5 you can use Visual Studio 2003 in addition to MinGW.
For Python 2.6, the official Windows installer of which is built with
Microsoft Visual Studio 2008 (version 9.0), Microsoft Visual Studio 2008
(version 9.0) is required.

To build with MSVC, just omit the compiler specific option:

  C:\pyOpenSSL-X.Y> setup.py bdist_msi

The resulting binary distribution will be placed in the dist directory. To
install it, depending on what kind of distribution you create, run it,
unzip it, or copy it to Python installation's site-packages.

And similarily, you can do

    setup.py --help

to get more information.

Big thanks to Itamar Shtull-Trauring, Oleg Orlov, Zooko O'Whielacronx, Chris
Galvan, Žiga Seilnacht, and #python and #distutils on FreeNode for their
help with Windows build instructions and to Michael Schneider for providing
Windows build hosts.

-- Documentation --

The documentation is written in LaTeX, using the standard Python templates,
and tools to compile it into a number of forms are included.  You need to
supply things like dvips, latex2html yourself of course!

To build the text, html, postscript or dvi forms of the documentation, this is
what you do:

    cd doc
    # To make the text-only documentation:
    make text
    # To make the dvi form:
    make dvi

It's as simple as that.  Note that since Python's mkhowto script is used, if
you do first ``make dvi'' and then ``make ps'', the dvi file will disappear.
I included a special build target ``make all'' that will build all the
documentation in an order that won't let anything disappear.


@(#) $Id: INSTALL,v 1.7 2002/06/14 12:14:19 martin Exp $