1Building Python using VC++ 7.1
2-------------------------------------
3This directory is used to build Python for Win32 platforms, e.g. Windows
495, 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
8All you need to do is open the workspace "pcbuild.sln" in MSVC++, select
9the Debug or Release setting (using "Solution Configuration" from
10the "Standard" toolbar"), and build the projects.
11
12The proper order to build subprojects:
13
141) pythoncore (this builds the main Python DLL and library files,
15 python27.{dll, lib} in Release mode)
16 NOTE: in previous releases, this subproject was
17 named after the release number, e.g. python20.
18
192) python (this builds the main Python executable,
20 python.exe in Release mode)
21
223) 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, or are running a Python core buildbot
26 test slave; see SUBPROJECTS below)
27
28When using the Debug setting, the output files have a _d added to
29their name: python27_d.dll, python_d.exe, parser_d.pyd, and so on.
30
31SUBPROJECTS
32-----------
33These subprojects should build out of the box. Subprojects other than the
34main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
35.pyd) from a specific module so that users don't have to load the code
36supporting that module unless they import the module.
37
38pythoncore
39 .dll and .lib
40python
41 .exe
42pythonw
43 pythonw.exe, a variant of python.exe that doesn't pop up a DOS box
44_socket
45 socketmodule.c
46_testcapi
47 tests of the Python C API, run via Lib/test/test_capi.py, and
48 implemented by module Modules/_testcapimodule.c
49pyexpat
50 Python wrapper for accelerated XML parsing, which incorporates stable
51 code from the Expat project: http://sourceforge.net/projects/expat/
52select
53 selectmodule.c
54unicodedata
55 large tables of Unicode data
56winsound
57 play sounds (typically .wav files) under Windows
58
59The following subprojects will generally NOT build out of the box. They
60wrap code Python doesn't control, and you'll need to download the base
61packages first and unpack them into siblings of PC's parent
62directory; for example, if this directory is ....\dist\trunk\PC\VS7.1,
63unpack into new subdirectories of dist\.
64
65_tkinter
66 Python wrapper for the Tk windowing system. Requires building
67 Tcl/Tk first. Following are instructions for Tcl/Tk 8.4.12.
68
69 Get source
70 ----------
71 In the dist directory, run
72 svn export http://svn.python.org/projects/external/tcl8.4.12
73 svn export http://svn.python.org/projects/external/tk8.4.12
74 svn export http://svn.python.org/projects/external/tix-8.4.0
75
76 Build Tcl first (done here w/ MSVC 7.1 on Windows XP)
77 ---------------
78 Use "Start -> All Programs -> Microsoft Visual Studio .NET 2003
79 -> Visual Studio .NET Tools -> Visual Studio .NET 2003 Command Prompt"
80 to get a shell window with the correct environment settings
81 cd dist\tcl8.4.12\win
82 nmake -f makefile.vc
83 nmake -f makefile.vc INSTALLDIR=..\..\tcltk install
84
85 XXX Should we compile with OPTS=threads?
86
87 Optional: run tests, via
88 nmake -f makefile.vc test
89
90 On WinXP Pro, wholly up to date as of 30-Aug-2004:
91 all.tcl: Total 10678 Passed 9969 Skipped 709 Failed 0
92 Sourced 129 Test Files.
93
94 Build Tk
95 --------
96 cd dist\tk8.4.12\win
97 nmake -f makefile.vc TCLDIR=..\..\tcl8.4.12
98 nmake -f makefile.vc TCLDIR=..\..\tcl8.4.12 INSTALLDIR=..\..\tcltk install
99
100 XXX Should we compile with OPTS=threads?
101
102 XXX Our installer copies a lot of stuff out of the Tcl/Tk install
103 XXX directory. Is all of that really needed for Python use of Tcl/Tk?
104
105 Optional: run tests, via
106 nmake -f makefile.vc TCLDIR=..\..\tcl8.4.12 test
107
108 On WinXP Pro, wholly up to date as of 30-Aug-2004:
109 all.tcl: Total 8420 Passed 6826 Skipped 1581 Failed 13
110 Sourced 91 Test Files.
111 Files with failing tests: canvImg.test scrollbar.test textWind.test winWm.test
112
113 Built Tix
114 ---------
115 cd dist\tix-8.4.0\win
116 nmake -f python.mak
117 nmake -f python.mak install
118
119bz2
120 Python wrapper for the libbz2 compression library. Homepage
121 http://sources.redhat.com/bzip2/
122 Download the source from the python.org copy into the dist
123 directory:
124
125 svn export http://svn.python.org/projects/external/bzip2-1.0.3
126
127 A custom pre-link step in the bz2 project settings should manage to
128 build bzip2-1.0.3\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
129 linked in VS7.1\.
130 However, the bz2 project is not smart enough to remove anything under
131 bzip2-1.0.3\ when you do a clean, so if you want to rebuild bzip2.lib
132 you need to clean up bzip2-1.0.3\ by hand.
133
134 The build step shouldn't yield any warnings or errors, and should end
135 by displaying 6 blocks each terminated with
136 FC: no differences encountered
137
138 All of this managed to build bzip2-1.0.3\libbz2.lib, which the Python
139 project links in.
140
141
142_bsddb
143 To use the version of bsddb that Python is built with by default, invoke
144 (in the dist directory)
145
146 svn export http://svn.python.org/projects/external/db-4.4.20
147
148
149 Then open a VS.NET 2003 shell, and invoke:
150
151 devenv db-4.4.20\build_win32\Berkeley_DB.sln /build Release /project db_static
152
153 and do that a second time for a Debug build too:
154
155 devenv db-4.4.20\build_win32\Berkeley_DB.sln /build Debug /project db_static
156
157 Alternatively, if you want to start with the original sources,
158 go to Sleepycat's download page:
159 http://www.sleepycat.com/downloads/releasehistorybdb.html
160
161 and download version 4.4.20.
162
163 With or without strong cryptography? You can choose either with or
164 without strong cryptography, as per the instructions below. By
165 default, Python is built and distributed WITHOUT strong crypto.
166
167 Unpack the sources; if you downloaded the non-crypto version, rename
168 the directory from db-4.4.20.NC to db-4.4.20.
169
170 Now apply any patches that apply to your version.
171
172 Open
173 dist\db-4.4.20\docs\index.html
174
175 and follow the "Windows->Building Berkeley DB with Visual C++ .NET"
176 instructions for building the Sleepycat
177 software. Note that Berkeley_DB.dsw is in the build_win32 subdirectory.
178 Build the "db_static" project, for "Release" mode.
179
180 To run extensive tests, pass "-u bsddb" to regrtest.py. test_bsddb3.py
181 is then enabled. Running in verbose mode may be helpful.
182
183 XXX The test_bsddb3 tests don't always pass, on Windows (according to
184 XXX me) or on Linux (according to Barry). (I had much better luck
185 XXX on Win2K than on Win98SE.) The common failure mode across platforms
186 XXX is
187 XXX DBAgainError: (11, 'Resource temporarily unavailable -- unable
188 XXX to join the environment')
189 XXX
190 XXX and it appears timing-dependent. On Win2K I also saw this once:
191 XXX
192 XXX test02_SimpleLocks (bsddb.test.test_thread.HashSimpleThreaded) ...
193 XXX Exception in thread reader 1:
194 XXX Traceback (most recent call last):
195 XXX File "C:\Code\python\lib\threading.py", line 411, in __bootstrap
196 XXX self.run()
197 XXX File "C:\Code\python\lib\threading.py", line 399, in run
198 XXX apply(self.__target, self.__args, self.__kwargs)
199 XXX File "C:\Code\python\lib\bsddb\test\test_thread.py", line 268, in
200 XXX readerThread
201 XXX rec = c.next()
202 XXX DBLockDeadlockError: (-30996, 'DB_LOCK_DEADLOCK: Locker killed
203 XXX to resolve a deadlock')
204 XXX
205 XXX I'm told that DBLockDeadlockError is expected at times. It
206 XXX doesn't cause a test to fail when it happens (exceptions in
207 XXX threads are invisible to unittest).
208
209 Building for Win64:
210 - open a VS.NET 2003 command prompt
211 - run the SDK setenv.cmd script, passing /RETAIL and the target
212 architecture (/SRV64 for Itanium, /X64 for AMD64)
213 - build BerkeleyDB with the solution configuration matching the
214 target ("Release IA64" for Itanium, "Release AMD64" for AMD64), e.g.
215 devenv db-4.4.20\build_win32\Berkeley_DB.sln /build "Release AMD64" /project db_static /useenv
216
217_sqlite3
218 Python wrapper for SQLite library.
219
220 Get the source code through
221
222 svn export http://svn.python.org/projects/external/sqlite-source-3.3.4
223
224 To use the extension module in a Python build tree, copy sqlite3.dll into
225 the VS7.1 folder.
226
227_ssl
228 Python wrapper for the secure sockets library.
229
230 Get the source code through
231
232 svn export http://svn.python.org/projects/external/openssl-0.9.8a
233
234 Alternatively, get the latest version from http://www.openssl.org.
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 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 build_ssl.py attempts to catch the most common errors (such as not
247 being able to find OpenSSL sources, or not being able to find a Perl
248 that works with OpenSSL) and give a reasonable error message.
249 If you have a problem that doesn't seem to be handled correctly
250 (eg, you know you have ActivePerl but we can't find it), please take
251 a peek at build_ssl.py and suggest patches. Note that build_ssl.py
252 should be able to be run directly from the command-line.
253
254 build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
255 this by hand.
256
257Building for Itanium
258--------------------
259
260The project files support a ReleaseItanium configuration which creates
261Win64/Itanium binaries. For this to work, you need to install the Platform
262SDK, in particular the 64-bit support. This includes an Itanium compiler
263(future releases of the SDK likely include an AMD64 compiler as well).
264In addition, you need the Visual Studio plugin for external C compilers,
265from http://sf.net/projects/vsextcomp. The plugin will wrap cl.exe, to
266locate the proper target compiler, and convert compiler options
267accordingly. The project files require atleast version 0.9.
268
269Building for AMD64
270------------------
271
272The build process for the ReleaseAMD64 configuration is very similar
273to the Itanium configuration; make sure you use the latest version of
274vsextcomp.
275
276Building Python Using the free MS Toolkit Compiler
277--------------------------------------------------
278
279The build process for Visual C++ can be used almost unchanged with the free MS
280Toolkit Compiler. This provides a way of building Python using freely
281available software.
282
283Note that Microsoft have withdrawn the free MS Toolkit Compiler, so this can
284no longer be considered a supported option. The instructions are still
285correct, but you need to already have a copy of the compiler in order to use
286them. Microsoft now supply Visual C++ 2008 Express Edition for free, but this
287is NOT compatible with Visual C++ 7.1 (it uses a different C runtime), and so
288cannot be used to build a version of Python compatible with the standard
289python.org build. If you are interested in using Visual C++ 2008 Express
290Edition, however, you should look at the PCBuild directory.
291
292Requirements
293
294 To build Python, the following tools are required:
295
296 * The Visual C++ Toolkit Compiler
297 no longer available for download - see above
298 * A recent Platform SDK
299 from http://www.microsoft.com/downloads/details.aspx?FamilyID=484269e2-3b89-47e3-8eb7-1f2be6d7123a
300 * The .NET 1.1 SDK
301 from http://www.microsoft.com/downloads/details.aspx?FamilyID=9b3a2ca6-3647-4070-9f41-a333c6b9181d
302
303 [Does anyone have better URLs for the last 2 of these?]
304
305 The toolkit compiler is needed as it is an optimising compiler (the
306 compiler supplied with the .NET SDK is a non-optimising version). The
307 platform SDK is needed to provide the Windows header files and libraries
308 (the Windows 2003 Server SP1 edition, typical install, is known to work -
309 other configurations or versions are probably fine as well). The .NET 1.1
310 SDK is needed because it contains a version of msvcrt.dll which links to
311 the msvcr71.dll CRT. Note that the .NET 2.0 SDK is NOT acceptable, as it
312 references msvcr80.dll.
313
314 All of the above items should be installed as normal.
315
316 If you intend to build the openssl (needed for the _ssl extension) you
317 will need the C runtime sources installed as part of the platform SDK.
318
319 In addition, you will need Nant, available from
320 http://nant.sourceforge.net. The 0.85 release candidate 3 version is known
321 to work. This is the latest released version at the time of writing. Later
322 "nightly build" versions are known NOT to work - it is not clear at
323 present whether future released versions will work.
324
325Setting up the environment
326
327 Start a platform SDK "build environment window" from the start menu. The
328 "Windows XP 32-bit retail" version is known to work.
329
330 Add the following directories to your PATH:
331 * The toolkit compiler directory
332 * The SDK "Win64" binaries directory
333 * The Nant directory
334 Add to your INCLUDE environment variable:
335 * The toolkit compiler INCLUDE directory
336 Add to your LIB environment variable:
337 * The toolkit compiler LIB directory
338 * The .NET SDK Visual Studio 2003 VC7\lib directory
339
340 The following commands should set things up as you need them:
341
342 rem Set these values according to where you installed the software
343 set TOOLKIT=C:\Program Files\Microsoft Visual C++ Toolkit 2003
344 set SDK=C:\Program Files\Microsoft Platform SDK
345 set NET=C:\Program Files\Microsoft Visual Studio .NET 2003
346 set NANT=C:\Utils\Nant
347
348 set PATH=%TOOLKIT%\bin;%PATH%;%SDK%\Bin\win64;%NANT%\bin
349 set INCLUDE=%TOOLKIT%\include;%INCLUDE%
350 set LIB=%TOOLKIT%\lib;%NET%\VC7\lib;%LIB%
351
352 The "win64" directory from the SDK is added to supply executables such as
353 "cvtres" and "lib", which are not available elsewhere. The versions in the
354 "win64" directory are 32-bit programs, so they are fine to use here.
355
356 That's it. To build Python (the core only, no binary extensions which
357 depend on external libraries) you just need to issue the command
358
359 nant -buildfile:python.build all
360
361 from within the VS7.1 directory.
362
363Extension modules
364
365 To build those extension modules which require external libraries
366 (_tkinter, bz2, _bsddb, _sqlite3, _ssl) you can follow the instructions
367 for the Visual Studio build above, with a few minor modifications. These
368 instructions have only been tested using the sources in the Python
369 subversion repository - building from original sources should work, but
370 has not been tested.
371
372 For each extension module you wish to build, you should remove the
373 associated include line from the excludeprojects section of pc.build.
374
375 The changes required are:
376
377 _tkinter
378 The tix makefile (tix-8.4.0\win\makefile.vc) must be modified to
379 remove references to TOOLS32. The relevant lines should be changed to
380 read:
381 cc32 = cl.exe
382 link32 = link.exe
383 include32 =
384 The remainder of the build instructions will work as given.
385
386 bz2
387 No changes are needed
388
389 _bsddb
390 The file db.build should be copied from the Python PCBuild directory
391 to the directory db-4.4.20\build_win32.
392
393 The file db_static.vcproj in db-4.4.20\build_win32 should be edited to
394 remove the string "$(SolutionDir)" - this occurs in 2 places, only
395 relevant for 64-bit builds. (The edit is required as otherwise, nant
396 wants to read the solution file, which is not in a suitable form).
397
398 The bsddb library can then be build with the command
399 nant -buildfile:db.build all
400 run from the db-4.4.20\build_win32 directory.
401
402 _sqlite3
403 No changes are needed. However, in order for the tests to succeed, a
404 copy of sqlite3.dll must be downloaded, and placed alongside
405 python.exe.
406
407 _ssl
408 The documented build process works as written. However, it needs a
409 copy of the file setargv.obj, which is not supplied in the platform
410 SDK. However, the sources are available (in the crt source code). To
411 build setargv.obj, proceed as follows:
412
413 Copy setargv.c, cruntime.h and internal.h from %SDK%\src\crt to a
414 temporary directory.
415 Compile using "cl /c /I. /MD /D_CRTBLD setargv.c"
416 Copy the resulting setargv.obj to somewhere on your LIB environment
417 (%SDK%\lib is a reasonable place).
418
419 With setargv.obj in place, the standard build process should work
420 fine.
421
422YOUR OWN EXTENSION DLLs
423-----------------------
424If you want to create your own extension module DLL, there's an example
425with easy-to-follow instructions in ../PC/example/; read the file
426readme.txt there first.
427
