PCbuild/readme.txt

   1 Building Python using VC++ 7.1
   2 -------------------------------------
   3 This directory is used to build Python for Win32 platforms, e.g. Windows
   4 95, 98 and NT.  It requires Microsoft Visual C++ 7.1
   5 (a.k.a. Visual Studio .NET 2003).
   6 (For other Windows platforms and compilers, see ../PC/readme.txt.)
   7
   8 All you need to do is open the workspace "pcbuild.sln" in MSVC++, select
   9 the Debug or Release setting (using "Solution Configuration" from
  10 the "Standard" toolbar"), and build the projects.
  11
  12 The proper order to build subprojects:
  13
  14 1) pythoncore (this builds the main Python DLL and library files,
  15                python25.{dll, lib} in Release mode)
  16               NOTE:  in previous releases, this subproject was
  17               named after the release number, e.g. python20.
  18
  19 2) python (this builds the main Python executable,
  20            python.exe in Release mode)
  21
  22 3) the other subprojects, as desired or needed (note:  you probably don't
  23    want to build most of the other subprojects, unless you're building an
  24    entire Python distribution from scratch, or specifically making changes
  25    to the subsystems they implement; see SUBPROJECTS below)
  26
  27 When using the Debug setting, the output files have a _d added to
  28 their name:  python25_d.dll, python_d.exe, parser_d.pyd, and so on.
  29
  30 SUBPROJECTS
  31 -----------
  32 These subprojects should build out of the box.  Subprojects other than the
  33 main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
  34 .pyd) from a specific module so that users don't have to load the code
  35 supporting that module unless they import the module.
  36
  37 pythoncore
  38     .dll and .lib
  39 python
  40     .exe
  41 pythonw
  42     pythonw.exe, a variant of python.exe that doesn't pop up a DOS box
  43 _socket
  44     socketmodule.c
  45 _testcapi
  46     tests of the Python C API, run via Lib/test/test_capi.py, and
  47     implemented by module Modules/_testcapimodule.c
  48 pyexpat
  49     Python wrapper for accelerated XML parsing, which incorporates stable
  50     code from the Expat project:  http://sourceforge.net/projects/expat/
  51 select
  52     selectmodule.c
  53 unicodedata
  54     large tables of Unicode data
  55 winsound
  56     play sounds (typically .wav files) under Windows
  57
  58 The following subprojects will generally NOT build out of the box.  They
  59 wrap code Python doesn't control, and you'll need to download the base
  60 packages first and unpack them into siblings of PCbuilds's parent
  61 directory; for example, if your PCbuild is  .......\dist\src\PCbuild\,
  62 unpack into new subdirectories of dist\.
  63
  64 _tkinter
  65     Python wrapper for the Tk windowing system.  Requires building
  66     Tcl/Tk first.  Following are instructions for Tcl/Tk 8.4.7; these
  67     should work for version 8.4.6 too, with suitable substitutions:
  68
  69     Get source
  70     ----------
  71     Go to
  72         http://prdownloads.sourceforge.net/tcl/
  73     and download
  74         tcl847-src.zip
  75         tk847-src.zip
  76     Unzip into
  77         dist\tcl8.4.7\
  78         dist\tk8.4.7\
  79     respectively.
  80
  81     Build Tcl first (done here w/ MSVC 7.1 on Windows XP)
  82     ---------------
  83     Use "Start -> All Programs -> Microsoft Visual Studio .NET 2003
  84          -> Visual Studio .NET Tools -> Visual Studio .NET 2003 Command Prompt"
  85     to get a shell window with the correct environment settings
  86     cd dist\tcl8.4.7\win
  87     nmake -f makefile.vc
  88     nmake -f makefile.vc INSTALLDIR=..\..\tcltk install
  89
  90     XXX Should we compile with OPTS=threads?
  91
  92     Optional:  run tests, via
  93         nmake -f makefile.vc test
  94
  95         On WinXP Pro, wholly up to date as of 30-Aug-2004:
  96         all.tcl:        Total   10678   Passed  9969    Skipped 709     Failed  0
  97         Sourced 129 Test Files.
  98
  99     Build Tk
 100     --------
 101     cd dist\tk8.4.7\win
 102     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.7
 103     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.7 INSTALLDIR=..\..\tcltk install
 104
 105     XXX Should we compile with OPTS=threads?
 106
 107     XXX Our installer copies a lot of stuff out of the Tcl/Tk install
 108     XXX directory.  Is all of that really needed for Python use of Tcl/Tk?
 109
 110     Optional:  run tests, via
 111         nmake -f makefile.vc TCLDIR=..\..\tcl8.4.7 test
 112
 113         On WinXP Pro, wholly up to date as of 30-Aug-2004:
 114         all.tcl:        Total   8420    Passed  6826    Skipped 1581    Failed  13
 115         Sourced 91 Test Files.
 116         Files with failing tests: canvImg.test scrollbar.test textWind.test winWm.test
 117
 118    Built Tix
 119    ---------
 120    Download from http://prdownloads.sourceforge.net/tix/tix-8.1.4.tar.gz
 121    cd dist\tix-8.1.4
 122    [cygwin]patch -p1 < ..\..\python\PC\tix.diff
 123    cd win
 124    nmake -f makefile.vc
 125    nmake -f makefile.vc install
 126
 127 bz2
 128     Python wrapper for the libbz2 compression library.  Homepage
 129         http://sources.redhat.com/bzip2/
 130     Download the source tarball, bzip2-1.0.2.tar.gz.
 131     Unpack into dist\bzip2-1.0.2.  WARNING:  If you're using WinZip, you
 132     must disable its "TAR file smart CR/LF conversion" feature (under
 133     Options -> Configuration -> Miscellaneous -> Other) for the duration.
 134
 135     A custom pre-link step in the bz2 project settings should manage to
 136     build bzip2-1.0.2\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
 137     linked in PCbuild\.
 138     However, the bz2 project is not smart enough to remove anything under
 139     bzip2-1.0.2\ when you do a clean, so if you want to rebuild bzip2.lib
 140     you need to clean up bzip2-1.0.2\ by hand.
 141
 142     The build step shouldn't yield any warnings or errors, and should end
 143     by displaying 6 blocks each terminated with
 144         FC: no differences encountered
 145     If FC finds differences, see the warning abou WinZip above (when I
 146     first tried it, sample3.ref failed due to CRLF conversion).
 147
 148     All of this managed to build bzip2-1.0.2\libbz2.lib, which the Python
 149     project links in.
 150
 151
 152 _bsddb
 153     Go to Sleepycat's download page:
 154         http://www.sleepycat.com/download/
 155
 156     and download version 4.2.52.
 157
 158     With or without strong cryptography? You can choose either with or
 159     without strong cryptography, as per the instructions below.  By
 160     default, Python is built and distributed WITHOUT strong crypto.
 161
 162     Unpack into the dist\. directory, ensuring you expand with folder names.
 163
 164     If you downloaded with strong crypto, this will create a dist\db-4.2.52
 165     directory, and is ready to use.
 166
 167     If you downloaded WITHOUT strong crypto, this will create a
 168     dist\db-4.2.52.NC directory - this directory should be renamed to
 169     dist\db-4.2.52 before use.
 170
 171     As of 11-Apr-2004, you also need to download and manually apply two
 172     patches before proceeding (and the sleepycat download page tells you
 173     about this).  Cygwin patch worked for me.  cd to dist\db-4.2.52 and
 174     use "patch -p0 < patchfile" once for each downloaded patchfile.
 175
 176     Open
 177         dist\db-4.2.52\docs\index.html
 178
 179     and follow the "Windows->Building Berkeley DB with Visual C++ .NET"
 180     instructions for building the Sleepycat
 181     software.  Note that Berkeley_DB.dsw is in the build_win32 subdirectory.
 182     Build the "Release Static" version.
 183
 184     XXX We're linking against Release_static\libdb42s.lib.
 185     XXX This yields the following warnings:
 186 """
 187 Compiling...
 188 _bsddb.c
 189 Linking...
 190    Creating library ./_bsddb.lib and object ./_bsddb.exp
 191 _bsddb.obj : warning LNK4217: locally defined symbol _malloc imported in function __db_associateCallback
 192 _bsddb.obj : warning LNK4217: locally defined symbol _free imported in function __DB_consume
 193 _bsddb.obj : warning LNK4217: locally defined symbol _fclose imported in function _DB_verify
 194 _bsddb.obj : warning LNK4217: locally defined symbol _fopen imported in function _DB_verify
 195 _bsddb.obj : warning LNK4217: locally defined symbol _strncpy imported in function _init_pybsddb
 196 __bsddb - 0 error(s), 5 warning(s)
 197 """
 198     XXX This isn't encouraging, but I don't know what to do about it.
 199
 200     To run extensive tests, pass "-u bsddb" to regrtest.py.  test_bsddb3.py
 201     is then enabled.  Running in verbose mode may be helpful.
 202
 203     XXX The test_bsddb3 tests don't always pass, on Windows (according to
 204     XXX me) or on Linux (according to Barry).  (I had much better luck
 205     XXX on Win2K than on Win98SE.)  The common failure mode across platforms
 206     XXX is
 207     XXX     DBAgainError: (11, 'Resource temporarily unavailable -- unable
 208     XXX                         to join the environment')
 209     XXX
 210     XXX and it appears timing-dependent.  On Win2K I also saw this once:
 211     XXX
 212     XXX test02_SimpleLocks (bsddb.test.test_thread.HashSimpleThreaded) ...
 213     XXX Exception in thread reader 1:
 214     XXX Traceback (most recent call last):
 215     XXX File "C:\Code\python\lib\threading.py", line 411, in __bootstrap
 216     XXX    self.run()
 217     XXX File "C:\Code\python\lib\threading.py", line 399, in run
 218     XXX    apply(self.__target, self.__args, self.__kwargs)
 219     XXX File "C:\Code\python\lib\bsddb\test\test_thread.py", line 268, in
 220     XXX                  readerThread
 221     XXX    rec = c.next()
 222     XXX DBLockDeadlockError: (-30996, 'DB_LOCK_DEADLOCK: Locker killed
 223     XXX                                to resolve a deadlock')
 224     XXX
 225     XXX I'm told that DBLockDeadlockError is expected at times.  It
 226     XXX doesn't cause a test to fail when it happens (exceptions in
 227     XXX threads are invisible to unittest).
 228
 229 _ssl
 230     Python wrapper for the secure sockets library.
 231
 232     Get the latest source code for OpenSSL from
 233         http://www.openssl.org
 234
 235     You (probably) don't want the "engine" code.  For example, get
 236         openssl-0.9.7d.tar.gz
 237     not
 238         openssl-engine-0.9.7d.tar.gz
 239
 240     (see #1233049 for using 0.9.8).
 241     Unpack into the "dist" directory, retaining the folder name from
 242     the archive - for example, the latest stable OpenSSL will install as
 243         dist/openssl-0.9.7d
 244
 245     You can (theoretically) use any version of OpenSSL you like - the
 246     build process will automatically select the latest version.
 247
 248     You must also install ActivePerl from
 249         http://www.activestate.com/Products/ActivePerl/
 250     as this is used by the OpenSSL build process.  Complain to them <wink>.
 251
 252     The MSVC project simply invokes PCBuild/build_ssl.py to perform
 253     the build.  This Python script locates and builds your OpenSSL
 254     installation, then invokes a simple makefile to build the final .pyd.
 255
 256     build_ssl.py attempts to catch the most common errors (such as not
 257     being able to find OpenSSL sources, or not being able to find a Perl
 258     that works with OpenSSL) and give a reasonable error message.
 259     If you have a problem that doesn't seem to be handled correctly
 260     (eg, you know you have ActivePerl but we can't find it), please take
 261     a peek at build_ssl.py and suggest patches.  Note that build_ssl.py
 262     should be able to be run directly from the command-line.
 263
 264     build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
 265     this by hand.
 266
 267 Building for Itanium
 268 --------------------
 269
 270 The project files support a ReleaseItanium configuration which creates
 271 Win64/Itanium binaries. For this to work, you need to install the Platform
 272 SDK, in particular the 64-bit support. This includes an Itanium compiler
 273 (future releases of the SDK likely include an AMD64 compiler as well).
 274 In addition, you need the Visual Studio plugin for external C compilers,
 275 from http://sf.net/projects/vsextcomp. The plugin will wrap cl.exe, to
 276 locate the proper target compiler, and convert compiler options
 277 accordingly.
 278
 279 The Itanium build has seen little testing. The SDK compiler reports a lot
 280 of warnings about conversion from size_t to int, which will be fixed in
 281 future Python releases.
 282
 283 YOUR OWN EXTENSION DLLs
 284 -----------------------
 285 If you want to create your own extension module DLL, there's an example
 286 with easy-to-follow instructions in ../PC/example/; read the file
 287 readme.txt there first.