docs/build/build-pyOpenSSL.rst

   1 Building pyOpenSSL on Windows
   2 =============================
   3
   4 This document details the steps to build an pyOpenSSL egg with embedded
   5 OpenSSL library, for use by Tahoe-LAFS on Windows.
   6
   7 The instructions were tried on Windows 7 64-bit and Windows XP 32-bit.
   8 They should work on other versions of Windows, maybe with minor variations.
   9
  10
  11 Download and install Microsoft Visual C++ compiler for Python 2.7
  12 -----------------------------------------------------------------
  13
  14 For reasons detailed in `the Python documentation`_, Python extension modules
  15 need to be built using a compiler compatible with the same version of Visual C++
  16 that was used to build Python itself. Until recently, this meant downloading
  17 Microsoft Visual Studio 2008 Express Edition and Windows SDK 3.5. The recent
  18 release of the Microsoft Visual C++ compiler for Python 2.7 made things a lot
  19 simpler.
  20
  21 So, the first step is to download and install the C++ compiler from Microsoft
  22 from `this link`_.
  23
  24 Find the location where it installed the ``vcvarsall.bat`` file; depending on
  25 the version of Windows it could be either
  26 ``"%USERPROFILE%\AppData\Local\Programs\Common\Microsoft\Visual C++ for Python\9.0"``
  27 or ``"%CommonProgramFiles%\Microsoft\Visual C++ for Python\9.0"``, for example.
  28 We'll call this ``%VCDIR%`` below.
  29
  30 .. _the Python documentation: https://docs.python.org/2/extending/windows.html
  31 .. _this link: https://www.microsoft.com/en-us/download/details.aspx?id=44266
  32
  33
  34 Download and install Perl
  35 -------------------------
  36
  37 Download and install ActiveState Perl:
  38
  39 * go to `the ActiveState Perl download page`_.
  40 * identify the correct link and manually change it from http to https.
  41
  42 .. _the ActiveState Perl download page: https://www.activestate.com/activeperl/downloads
  43
  44
  45 Download and install the latest OpenSSL version
  46 -----------------------------------------------
  47
  48 * Download the latest OpenSSL from `the OpenSSL source download page`_ and untar it.
  49   At the time of writing, the latest version was OpenSSL 1.0.1m.
  50
  51 * Set up the build environment. For 64-bit Windows::
  52
  53     "%VCDIR%\vcvarsall.bat" amd64
  54
  55   or for 32-bit Windows::
  56
  57     "%VCDIR%\vcvarsall.bat" x86
  58
  59 * Go to the untar'ed OpenSSL source base directory. For 64-bit Windows, run::
  60
  61     mkdir c:\dist
  62     perl Configure VC-WIN64A --prefix=c:\dist\openssl no-asm enable-tlsext
  63     ms\do_win64a.bat
  64     nmake -f ms\ntdll.mak
  65     nmake -f ms\ntdll.mak install
  66
  67   or for 32-bit Windows, run::
  68
  69     mkdir c:\dist
  70     perl Configure VC-WIN32 --prefix=c:\dist\openssl no-asm enable-tlsext
  71     ms\do_ms.bat
  72     nmake -f ms\ntdll.mak
  73     nmake -f ms\ntdll.mak install
  74
  75
  76 To check that it is working, run ``c:\dist\openssl\bin\openssl version``.
  77
  78 .. _the OpenSSL source download page: https://www.openssl.org/source/
  79
  80
  81 Building PyOpenSSL
  82 ------------------
  83
  84 * Download and untar pyOpenSSL 0.13.1 (see `ticket #2221`_ for why we
  85   currently use this version). The MD5 hash of pyOpenSSL-0.13.1.tar.gz is
  86   e27a3b76734c39ea03952ca94cc56715.
  87
  88 * Set up the build environment by running ``vcvarsall.bat`` as for building
  89   OpenSSL above.
  90
  91 * Set OpenSSL ``LIB``, ``INCLUDE`` and ``PATH``::
  92
  93     set LIB=c:\dist\openssl\lib;%LIB%
  94     set INCLUDE=c:\dist\openssl\include;%INCLUDE%
  95     set PATH=c:\dist\openssl\bin;%PATH%
  96
  97 * A workaround is needed to ensure that the setuptools ``bdist_egg`` command
  98   is available. Edit pyOpenSSL's ``setup.py`` around line 13 as follows::
  99
 100     < from distutils.core import Extension, setup
 101     ---
 102     > from setuptools import setup
 103     > from distutils.core import Extension
 104
 105 * Run ``python setup.py bdist_egg``
 106
 107 The generated egg will be in the ``dist`` directory. It is a good idea
 108 to check that Tahoe-LAFS is able to use it before uploading the egg to
 109 tahoe-lafs.org. This can be done by putting it in the ``tahoe-deps`` directory
 110 of a Tahoe-LAFS checkout or release, then running ``python setup.py test``.
 111
 112 .. _ticket #2221: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2221