PC/VC6/readme.txt

   1 Building Python using VC++ 6.0 or 5.0
   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++ 6.x or 5.x.
   5 (For other Windows platforms and compilers, see ../readme.txt.)
   6
   7 All you need to do is open the workspace "pcbuild.dsw" in MSVC++, select
   8 the Debug or Release setting (using Build -> Set Active Configuration...),
   9 and build the projects.
  10
  11 The proper order to build subprojects:
  12
  13 1) pythoncore (this builds the main Python DLL and library files,
  14                python21.{dll, lib} in Release mode)
  15               NOTE:  in previous releases, this subproject was
  16               named after the release number, e.g. python20.
  17
  18 2) python (this builds the main Python executable,
  19            python.exe in Release mode)
  20
  21 3) the other subprojects, as desired or needed (note:  you probably don't
  22    want to build most of the other subprojects, unless you're building an
  23    entire Python distribution from scratch, or specifically making changes
  24    to the subsystems they implement; see SUBPROJECTS below)
  25
  26 When using the Debug setting, the output files have a _d added to
  27 their name:  python21_d.dll, python_d.exe, parser_d.pyd, and so on.
  28
  29 SUBPROJECTS
  30 -----------
  31 These subprojects should build out of the box.  Subprojects other than the
  32 main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
  33 .pyd) from a specific module so that users don't have to load the code
  34 supporting that module unless they import the module.
  35
  36 pythoncore
  37     .dll and .lib
  38 python
  39     .exe
  40 pythonw
  41     pythonw.exe, a variant of python.exe that doesn't pop up a DOS box
  42 _socket
  43     socketmodule.c
  44 _testcapi
  45     tests of the Python C API, run via Lib/test/test_capi.py, and
  46     implemented by module Modules/_testcapimodule.c
  47 pyexpat
  48     Python wrapper for accelerated XML parsing, which incorporates stable
  49     code from the Expat project:  http://sourceforge.net/projects/expat/
  50 select
  51     selectmodule.c
  52 unicodedata
  53     large tables of Unicode data
  54 winsound
  55     play sounds (typically .wav files) under Windows
  56
  57 The following subprojects will generally NOT build out of the box.  They
  58 wrap code Python doesn't control, and you'll need to download the base
  59 packages first and unpack them into siblings of PCbuilds's parent
  60 directory; for example, if your PCbuild is  .......\dist\src\PCbuild\,
  61 unpack into new subdirectories of dist\.
  62
  63 _tkinter
  64     Python wrapper for the Tk windowing system.  Requires building
  65     Tcl/Tk first.  Following are instructions for Tcl/Tk 8.4.3:
  66
  67     Get source
  68     ----------
  69     Go to
  70         http://prdownloads.sourceforge.net/tcl/
  71     and download
  72         tcl843-src.zip
  73         tk843-src.zip
  74     Unzip into
  75         dist\tcl8.4.3\
  76         dist\tk8.4.3\
  77     respectively.
  78
  79     Build Tcl first (done here w/ MSVC 6 on Win98SE)
  80     ---------------
  81     cd dist\tcl8.4.3\win
  82     run vcvars32.bat [necessary even on Win2K]
  83     nmake -f makefile.vc
  84     nmake -f makefile.vc INSTALLDIR=..\..\tcl84 install
  85
  86     XXX Should we compile with OPTS=threads?
  87
  88     XXX Some tests failed in "nmake -f makefile.vc test".
  89     XXX all.tcl:  Total 10480   Passed 9743    Skipped 719     Failed 18
  90     XXX
  91     XXX That was on Win98SE.  On Win2K:
  92     XXX all.tcl   Total 10480   Passed 9781    Skipped 698     Failed  1
  93
  94     Build Tk
  95     --------
  96     cd dist\tk8.4.3\win
  97     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.3
  98     nmake -f makefile.vc TCLDIR=..\..\tcl8.4.3 INSTALLDIR=..\..\tcl84 install
  99
 100     XXX Should we compile with OPTS=threads?
 101
 102     XXX I have no idea whether "nmake -f makefile.vc test" passed or
 103     XXX failed.  It popped up tons of little windows, and did lots of
 104     XXX stuff, and nothing blew up.
 105
 106     XXX Our installer copies a lot of stuff out of the Tcl/Tk install
 107     XXX directory.  Is all of that really needed for Python use of Tcl/Tk?
 108
 109     Make sure the installer matches
 110     -------------------------------
 111     Ensure that the Wise compiler vrbl _TCLDIR_ is set to the name of
 112     the common Tcl/Tk installation directory (tcl84 for the instructions
 113     above).  This is needed so the installer can copy various Tcl/Tk
 114     files into the Python distribution.
 115
 116
 117 zlib
 118     Python wrapper for the zlib compression library.  Get the source code
 119     for version 1.1.4 from a convenient mirror at:
 120         http://www.gzip.org/zlib/
 121     Unpack into dist\zlib-1.1.4.
 122     A custom pre-link step in the zlib project settings should manage to
 123     build zlib-1.1.4\zlib.lib by magic before zlib.pyd (or zlib_d.pyd) is
 124     linked in PCbuild\.
 125     However, the zlib project is not smart enough to remove anything under
 126     zlib-1.1.4\ when you do a clean, so if you want to rebuild zlib.lib
 127     you need to clean up zlib-1.1.4\ by hand.
 128
 129 bz2
 130     Python wrapper for the libbz2 compression library.  Homepage
 131         http://sources.redhat.com/bzip2/
 132     Download the source tarball, bzip2-1.0.2.tar.gz.
 133     Unpack into dist\bzip2-1.0.2.  WARNING:  If you're using WinZip, you
 134     must disable its "TAR file smart CR/LF conversion" feature (under
 135     Options -> Configuration -> Miscellaneous -> Other) for the duration.
 136
 137     A custom pre-link step in the bz2 project settings should manage to
 138     build bzip2-1.0.2\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
 139     linked in PCbuild\.
 140     However, the bz2 project is not smart enough to remove anything under
 141     bzip2-1.0.2\ when you do a clean, so if you want to rebuild bzip2.lib
 142     you need to clean up bzip2-1.0.2\ by hand.
 143
 144     The build step shouldn't yield any warnings or errors, and should end
 145     by displaying 6 blocks each terminated with
 146         FC: no differences encountered
 147     If FC finds differences, see the warning abou WinZip above (when I
 148     first tried it, sample3.ref failed due to CRLF conversion).
 149
 150     All of this managed to build bzip2-1.0.2\libbz2.lib, which the Python
 151     project links in.
 152
 153
 154 _bsddb
 155     Go to Sleepycat's download page:
 156         http://www.sleepycat.com/download/
 157
 158     and download version 4.1.25.  The file name is db-4.1.25.NC.zip.
 159     XXX with or without strong cryptography?  I picked "without".
 160
 161     Unpack into
 162         dist\db-4.1.25
 163
 164     [If using WinZip to unpack the db-4.1.25.NC distro, that requires
 165      renaming the directory (to remove ".NC") after unpacking.
 166     ]
 167
 168     Open
 169         dist\db-4.1.25\docs\index.html
 170
 171     and follow the Windows instructions for building the Sleepycat
 172     software.  Note that Berkeley_DB.dsw is in the build_win32 subdirectory.
 173     Build the Release version ("build_all -- Win32 Release").
 174
 175     XXX We're actually linking against Release_static\libdb41s.lib.
 176     XXX This yields the following warnings:
 177 """
 178 Compiling...
 179 _bsddb.c
 180 Linking...
 181    Creating library ./_bsddb.lib and object ./_bsddb.exp
 182 LINK : warning LNK4049: locally defined symbol "_malloc" imported
 183 LINK : warning LNK4049: locally defined symbol "_free" imported
 184 LINK : warning LNK4049: locally defined symbol "_fclose" imported
 185 LINK : warning LNK4049: locally defined symbol "_fopen" imported
 186 _bsddb.pyd - 0 error(s), 4 warning(s)
 187 """
 188     XXX This isn't encouraging, but I don't know what to do about it.
 189
 190     To run extensive tests, pass "-u bsddb" to regrtest.py.  test_bsddb3.py
 191     is then enabled.  Running in verbose mode may be helpful.
 192
 193     XXX The test_bsddb3 tests don't always pass, on Windows (according to
 194     XXX me) or on Linux (according to Barry).  I had much better luck
 195     XXX on Win2K than on Win98SE.  The common failure mode across platforms
 196     XXX is
 197     XXX     DBAgainError: (11, 'Resource temporarily unavailable -- unable
 198     XXX                         to join the environment')
 199     XXX
 200     XXX and it appears timing-dependent.  On Win2K I also saw this once:
 201     XXX
 202     XXX test02_SimpleLocks (bsddb.test.test_thread.HashSimpleThreaded) ...
 203     XXX Exception in thread reader 1:
 204     XXX Traceback (most recent call last):
 205     XXX File "C:\Code\python\lib\threading.py", line 411, in __bootstrap
 206     XXX    self.run()
 207     XXX File "C:\Code\python\lib\threading.py", line 399, in run
 208     XXX    apply(self.__target, self.__args, self.__kwargs)
 209     XXX File "C:\Code\python\lib\bsddb\test\test_thread.py", line 268, in
 210     XXX                  readerThread
 211     XXX    rec = c.next()
 212     XXX DBLockDeadlockError: (-30996, 'DB_LOCK_DEADLOCK: Locker killed
 213     XXX                                to resolve a deadlock')
 214     XXX
 215     XXX I'm told that DBLockDeadlockError is expected at times.  It
 216     XXX doesn't cause a test to fail when it happens (exceptions in
 217     XXX threads are invisible to unittest).
 218
 219
 220 _ssl
 221     Python wrapper for the secure sockets library.
 222
 223     Get the latest source code for OpenSSL from
 224         http://www.openssl.org
 225
 226     You (probably) don't want the "engine" code.  For example, get
 227         openssl-0.9.6g.tar.gz
 228     not
 229         openssl-engine-0.9.6g.tar.gz
 230
 231     Unpack into the "dist" directory, retaining the folder name from
 232     the archive - for example, the latest stable OpenSSL will install as
 233         dist/openssl-0.9.6g
 234
 235     You can (theoretically) use any version of OpenSSL you like - the
 236     build process will automatically select the latest version.
 237
 238     You must also install ActivePerl from
 239         http://www.activestate.com/Products/ActivePerl/
 240     as this is used by the OpenSSL build process.  Complain to them <wink>.
 241
 242     The MSVC project simply invokes PCBuild/build_ssl.py to perform
 243     the build.  This Python script locates and builds your OpenSSL
 244     installation, then invokes a simple makefile to build the final .pyd.
 245
 246     Win9x users:  see "Win9x note" below.
 247
 248     build_ssl.py attempts to catch the most common errors (such as not
 249     being able to find OpenSSL sources, or not being able to find a Perl
 250     that works with OpenSSL) and give a reasonable error message.
 251     If you have a problem that doesn't seem to be handled correctly
 252     (eg, you know you have ActivePerl but we can't find it), please take
 253     a peek at build_ssl.py and suggest patches.  Note that build_ssl.py
 254     should be able to be run directly from the command-line.
 255
 256     build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
 257     this by hand.
 258
 259     Win9x note:  If, near the start of the build process, you see
 260     something like
 261
 262         C:\Code\openssl-0.9.6g>set OPTS=no-asm
 263         Out of environment space
 264
 265     then you're in trouble, and will probably also see these errors near
 266     the end of the process:
 267
 268         NMAKE : fatal error U1073: don't know how to make
 269             'crypto\md5\asm\m5_win32.asm'
 270         Stop.
 271         NMAKE : fatal error U1073: don't know how to make
 272             'C:\Code\openssl-0.9.6g/out32/libeay32.lib'
 273         Stop.
 274
 275     You need more environment space.  Win9x only has room for 256 bytes
 276     by default, and especially after installing ActivePerl (which fiddles
 277     the PATH envar), you're likely to run out.  KB Q230205
 278
 279         http://support.microsoft.com/default.aspx?scid=KB;en-us;q230205
 280
 281     explains how to edit CONFIG.SYS to cure this.
 282
 283
 284 YOUR OWN EXTENSION DLLs
 285 -----------------------
 286 If you want to create your own extension module DLL, there's an example
 287 with easy-to-follow instructions in ../PC/example/; read the file
 288 readme.txt there first.