blob: dbe031f4749ce2e6e81908ba4a97920a2767b27b [file] [log] [blame]
Christian Heimes5b5e81c2007-12-31 16:14:33 +00001Building Python using VC++ 9.0
2------------------------------
Christian Heimes57dddfb2008-01-02 18:30:52 +00003
Trent Nelson52037272008-04-02 15:06:49 +00004This directory is used to build Python for Win32 and x64 platforms, e.g.
5Windows 2000, XP, Vista and Windows Server 2008. In order to build 32-bit
6debug and release executables, Microsoft Visual C++ 2008 Express Edition is
7required at the very least. In order to build 64-bit debug and release
8executables, Visual Studio 2008 Standard Edition is required at the very
9least. In order to build all of the above, as well as generate release builds
10that make use of Profile Guided Optimisation (PG0), Visual Studio 2008
11Professional Edition is required at the very least. The official Python
12releases are built with this version of Visual Studio.
13
14For other Windows platforms and compilers, see ../PC/readme.txt.
Guido van Rossum15b239f1998-05-26 14:16:23 +000015
Christian Heimes5b5e81c2007-12-31 16:14:33 +000016All you need to do is open the workspace "pcbuild.sln" in Visual Studio,
17select the desired combination of configuration and platform and eventually
18build the solution. Unless you are going to debug a problem in the core or
19you are going to create an optimized build you want to select "Release" as
20configuration.
Guido van Rossum15b239f1998-05-26 14:16:23 +000021
Christian Heimes5b5e81c2007-12-31 16:14:33 +000022The PCbuild directory is compatible with all versions of Visual Studio from
23VS C++ Express Edition over the standard edition up to the professional
Benjamin Peterson9bc93512008-09-22 22:10:59 +000024edition. However the express edition does not support features like solution
Christian Heimes5b5e81c2007-12-31 16:14:33 +000025folders or profile guided optimization (PGO). The missing bits and pieces
26won't stop you from building Python.
Guido van Rossum15b239f1998-05-26 14:16:23 +000027
Christian Heimes5b5e81c2007-12-31 16:14:33 +000028The solution is configured to build the projects in the correct order. "Build
Christian Heimesa8223142008-02-09 20:58:00 +000029Solution" or F7 takes care of dependencies except for x64 builds. To make
Christian Heimes5b5e81c2007-12-31 16:14:33 +000030cross compiling x64 builds on a 32bit OS possible the x64 builds require a
3132bit version of Python.
Guido van Rossum15b239f1998-05-26 14:16:23 +000032
Christian Heimes5b5e81c2007-12-31 16:14:33 +000033NOTE:
34 You probably don't want to build most of the other subprojects, unless
35 you're building an entire Python distribution from scratch, or
36 specifically making changes to the subsystems they implement, or are
37 running a Python core buildbot test slave; see SUBPROJECTS below)
Guido van Rossum15b239f1998-05-26 14:16:23 +000038
39When using the Debug setting, the output files have a _d added to
Martin v. Löwisf7a6b502009-06-27 23:00:59 +000040their name: python32_d.dll, python_d.exe, parser_d.pyd, and so on. Both
Christian Heimesa8223142008-02-09 20:58:00 +000041the build and rt batch files accept a -d option for debug builds.
Guido van Rossume79cf321998-07-07 22:35:03 +000042
Christian Heimes5b5e81c2007-12-31 16:14:33 +000043The 32bit builds end up in the solution folder PCbuild while the x64 builds
44land in the amd64 subfolder. The PGI and PGO builds for profile guided
45optimization end up in their own folders, too.
46
Christian Heimes57dddfb2008-01-02 18:30:52 +000047Legacy support
48--------------
49
50You can find build directories for older versions of Visual Studio and
51Visual C++ in the PC directory. The legacy build directories are no longer
52actively maintained and may not work out of the box.
53
54PC/VC6/
55 Visual C++ 6.0
56PC/VS7.1/
57 Visual Studio 2003 (7.1)
Hirokazu Yamamoto0b0ebb42010-10-01 10:40:49 +000058PC/VS8.0/
Christian Heimes57dddfb2008-01-02 18:30:52 +000059 Visual Studio 2005 (8.0)
60
61
62C RUNTIME
63---------
64
65Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9). The executables
66are linked to a CRT "side by side" assembly which must be present on the target
67machine. This is avalible under the VC/Redist folder of your visual studio
68distribution. On XP and later operating systems that support
Trent Nelson52037272008-04-02 15:06:49 +000069side-by-side assemblies it is not enough to have the msvcrt90.dll present,
Christian Heimes57dddfb2008-01-02 18:30:52 +000070it has to be there as a whole assembly, that is, a folder with the .dll
71and a .manifest. Also, a check is made for the correct version.
72Therefore, one should distribute this assembly with the dlls, and keep
73it in the same directory. For compatibility with older systems, one should
74also set the PATH to this directory so that the dll can be found.
75For more info, see the Readme in the VC/Redist folder.
76
Tim Peters4b5fb072000-07-01 00:03:43 +000077SUBPROJECTS
78-----------
Tim Peters610a8272000-07-01 02:51:23 +000079These subprojects should build out of the box. Subprojects other than the
Tim Petersbefc97c2001-01-18 19:01:39 +000080main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
Tim Peters610a8272000-07-01 02:51:23 +000081.pyd) from a specific module so that users don't have to load the code
Tim Peters4b5fb072000-07-01 00:03:43 +000082supporting that module unless they import the module.
Guido van Rossume79cf321998-07-07 22:35:03 +000083
Tim Peters97c96402001-01-17 23:23:13 +000084pythoncore
Tim Peters4b5fb072000-07-01 00:03:43 +000085 .dll and .lib
86python
87 .exe
88pythonw
89 pythonw.exe, a variant of python.exe that doesn't pop up a DOS box
90_socket
91 socketmodule.c
Tim Petersd66595f2001-02-04 03:09:53 +000092_testcapi
Tim Petersb16c56f2001-02-02 21:24:51 +000093 tests of the Python C API, run via Lib/test/test_capi.py, and
Tim Petersd66595f2001-02-04 03:09:53 +000094 implemented by module Modules/_testcapimodule.c
Tim Petersb012a152002-02-13 23:56:46 +000095pyexpat
96 Python wrapper for accelerated XML parsing, which incorporates stable
97 code from the Expat project: http://sourceforge.net/projects/expat/
Tim Peters4b5fb072000-07-01 00:03:43 +000098select
99 selectmodule.c
Tim Peters19f52c22001-01-24 10:07:22 +0000100unicodedata
Tim Peters4b5fb072000-07-01 00:03:43 +0000101 large tables of Unicode data
Tim Peters4b5fb072000-07-01 00:03:43 +0000102winsound
103 play sounds (typically .wav files) under Windows
104
Trent Nelson52037272008-04-02 15:06:49 +0000105Python-controlled subprojects that wrap external projects:
Trent Nelson52037272008-04-02 15:06:49 +0000106_sqlite3
Martin v. Löwis0e74cac2010-12-17 21:04:09 +0000107 Wraps SQLite 3.7.4, which is currently built by sqlite3.vcproj (see below).
Tim Peters4b5fb072000-07-01 00:03:43 +0000108_tkinter
Georg Brandl1158a332009-06-04 09:30:30 +0000109 Wraps the Tk windowing system. Unlike _sqlite3, there's no
Trent Nelson52037272008-04-02 15:06:49 +0000110 corresponding tcltk.vcproj-type project that builds Tcl/Tk from vcproj's
111 within our pcbuild.sln, which means this module expects to find a
112 pre-built Tcl/Tk in either ..\..\tcltk for 32-bit or ..\..\tcltk64 for
113 64-bit (relative to this directory). See below for instructions to build
114 Tcl/Tk.
Tim Petersb0ead4e2002-11-09 04:48:58 +0000115bz2
116 Python wrapper for the libbz2 compression library. Homepage
117 http://sources.redhat.com/bzip2/
Martin v. Löwisf6f79252006-03-13 13:48:05 +0000118 Download the source from the python.org copy into the dist
119 directory:
120
Martin v. Löwis70ce8aa2008-06-13 17:28:35 +0000121 svn export http://svn.python.org/projects/external/bzip2-1.0.5
Tim Peters077736b2002-11-14 23:24:40 +0000122
Trent Nelson52037272008-04-02 15:06:49 +0000123 ** NOTE: if you use the Tools\buildbot\external(-amd64).bat approach for
124 obtaining external sources then you don't need to manually get the source
125 above via subversion. **
126
Thomas Heller46a007e2003-08-20 18:27:36 +0000127 A custom pre-link step in the bz2 project settings should manage to
Martin v. Löwis70ce8aa2008-06-13 17:28:35 +0000128 build bzip2-1.0.5\libbz2.lib by magic before bz2.pyd (or bz2_d.pyd) is
Thomas Heller46a007e2003-08-20 18:27:36 +0000129 linked in PCbuild\.
130 However, the bz2 project is not smart enough to remove anything under
Martin v. Löwis70ce8aa2008-06-13 17:28:35 +0000131 bzip2-1.0.5\ when you do a clean, so if you want to rebuild bzip2.lib
132 you need to clean up bzip2-1.0.5\ by hand.
Tim Peters077736b2002-11-14 23:24:40 +0000133
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000134 All of this managed to build libbz2.lib in
Martin v. Löwis70ce8aa2008-06-13 17:28:35 +0000135 bzip2-1.0.5\$platform-$configuration\, which the Python project links in.
Tim Petersb0ead4e2002-11-09 04:48:58 +0000136
Mark Hammondf229f9f2002-12-03 05:47:26 +0000137_ssl
Tim Peterse8bcb252002-12-04 02:39:52 +0000138 Python wrapper for the secure sockets library.
Tim Peters4b5fb072000-07-01 00:03:43 +0000139
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000140 Get the source code through
Mark Hammondf229f9f2002-12-03 05:47:26 +0000141
Martin v. Löwise38de852010-07-30 17:30:51 +0000142 svn export http://svn.python.org/projects/external/openssl-1.0.0a
Tim Peterse8bcb252002-12-04 02:39:52 +0000143
Trent Nelson52037272008-04-02 15:06:49 +0000144 ** NOTE: if you use the Tools\buildbot\external(-amd64).bat approach for
145 obtaining external sources then you don't need to manually get the source
146 above via subversion. **
147
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000148 Alternatively, get the latest version from http://www.openssl.org.
Mark Hammondf229f9f2002-12-03 05:47:26 +0000149 You can (theoretically) use any version of OpenSSL you like - the
150 build process will automatically select the latest version.
151
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000152 You must install the NASM assembler from
Benjamin Petersone5384b02008-10-04 22:00:42 +0000153 http://nasm.sf.net
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000154 for x86 builds. Put nasmw.exe anywhere in your PATH.
Georg Brandl0abcbd72010-08-02 19:43:05 +0000155 Note: recent releases of nasm only have nasm.exe. Just rename it to
156 nasmw.exe.
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000157
158 You can also install ActivePerl from
Hirokazu Yamamoto7c3d7092010-10-28 17:57:25 +0000159 http://www.activestate.com/activeperl/
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000160 if you like to use the official sources instead of the files from
161 python's subversion repository. The svn version contains pre-build
162 makefiles and assembly files.
163
164 The build process makes sure that no patented algorithms are included.
165 For now RC5, MDC2 and IDEA are excluded from the build. You may have
166 to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if the build process
167 complains about missing files or forbidden IDEA. Again the files provided
168 in the subversion repository are already fixed.
Mark Hammondf229f9f2002-12-03 05:47:26 +0000169
170 The MSVC project simply invokes PCBuild/build_ssl.py to perform
Tim Peterse8bcb252002-12-04 02:39:52 +0000171 the build. This Python script locates and builds your OpenSSL
Mark Hammondf229f9f2002-12-03 05:47:26 +0000172 installation, then invokes a simple makefile to build the final .pyd.
173
174 build_ssl.py attempts to catch the most common errors (such as not
175 being able to find OpenSSL sources, or not being able to find a Perl
176 that works with OpenSSL) and give a reasonable error message.
177 If you have a problem that doesn't seem to be handled correctly
178 (eg, you know you have ActivePerl but we can't find it), please take
179 a peek at build_ssl.py and suggest patches. Note that build_ssl.py
180 should be able to be run directly from the command-line.
181
Tim Peterse8bcb252002-12-04 02:39:52 +0000182 build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
183 this by hand.
Tim Peters4b5fb072000-07-01 00:03:43 +0000184
Trent Nelson52037272008-04-02 15:06:49 +0000185The subprojects above wrap external projects Python doesn't control, and as
186such, a little more work is required in order to download the relevant source
187files for each project before they can be built. The buildbots do this each
188time they're built, so the easiest approach is to run either external.bat or
189external-amd64.bat in the ..\Tools\buildbot directory from ..\, i.e.:
190
191 C:\..\svn.python.org\projects\python\trunk\PCbuild>cd ..
192 C:\..\svn.python.org\projects\python\trunk>Tools\buildbot\external.bat
193
194This extracts all the external subprojects from http://svn.python.org/external
195via Subversion (so you'll need an svn.exe on your PATH) and places them in
196..\.. (relative to this directory). The external(-amd64).bat scripts will
197also build a debug build of Tcl/Tk; there aren't any equivalent batch files
198for building release versions of Tcl/Tk lying around in the Tools\buildbot
199directory. If you need to build a release version of Tcl/Tk it isn't hard
200though, take a look at the relevant external(-amd64).bat file and find the
201two nmake lines, then call each one without the 'DEBUG=1' parameter, i.e.:
202
203The external-amd64.bat file contains this for tcl:
204 nmake -f makefile.vc COMPILERFLAGS=-DWINVER=0x0500 DEBUG=1 MACHINE=AMD64 INSTALLDIR=..\..\tcltk64 clean all install
205
206So for a release build, you'd call it as:
207 nmake -f makefile.vc COMPILERFLAGS=-DWINVER=0x0500 MACHINE=AMD64 INSTALLDIR=..\..\tcltk64 clean all install
208
209 XXX Should we compile with OPTS=threads?
210 XXX Our installer copies a lot of stuff out of the Tcl/Tk install
211 XXX directory. Is all of that really needed for Python use of Tcl/Tk?
212
213This will be cleaned up in the future; ideally Tcl/Tk will be brought into our
214pcbuild.sln as custom .vcproj files, just as we've recently done with the
Georg Brandl1158a332009-06-04 09:30:30 +0000215sqlite3.vcproj file, which will remove the need for Tcl/Tk to be built
216separately via a batch file.
Trent Nelson52037272008-04-02 15:06:49 +0000217
218XXX trent.nelson 02-Apr-08:
219 Having the external subprojects in ..\.. relative to this directory is a
220 bit of a nuisance when you're working on py3k and trunk in parallel and
221 your directory layout mimics that of Python's subversion layout, e.g.:
222
223 C:\..\svn.python.org\projects\python\trunk
224 C:\..\svn.python.org\projects\python\branches\py3k
225 C:\..\svn.python.org\projects\python\branches\release25-maint
226
227 I'd like to change things so that external subprojects are fetched from
228 ..\external instead of ..\.., then provide some helper scripts or batch
229 files that would set up a new ..\external directory with svn checkouts of
230 the relevant branches in http://svn.python.org/projects/external/, or
231 alternatively, use junctions to link ..\external with a pre-existing
232 externals directory being used by another branch. i.e. if I'm usually
233 working on trunk (and have previously created trunk\external via the
234 provided batch file), and want to do some work on py3k, I'd set up a
235 junction as follows (using the directory structure above as an example):
236
237 C:\..\python\trunk\external <- already exists and has built versions
238 of the external subprojects
239
240 C:\..\python\branches\py3k>linkd.exe external ..\..\trunk\external
241 Link created at: external
242
243 Only a slight tweak would be needed to the buildbots such that bots
244 building trunk and py3k could make use of the same facility. (2.5.x
245 builds need to be kept separate as they're using Visual Studio 7.1.)
246/XXX trent.nelson 02-Apr-08
247
Martin v. Löwis13e50fe2004-07-20 14:37:48 +0000248Building for Itanium
249--------------------
250
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000251NOTE:
252Official support for Itanium builds have been dropped from the build. Please
Christian Heimesa8223142008-02-09 20:58:00 +0000253contact us and provide patches if you are interested in Itanium builds.
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000254
Tim Peterse82b00f2004-08-30 21:14:51 +0000255The project files support a ReleaseItanium configuration which creates
Martin v. Löwis13e50fe2004-07-20 14:37:48 +0000256Win64/Itanium binaries. For this to work, you need to install the Platform
257SDK, in particular the 64-bit support. This includes an Itanium compiler
258(future releases of the SDK likely include an AMD64 compiler as well).
259In addition, you need the Visual Studio plugin for external C compilers,
260from http://sf.net/projects/vsextcomp. The plugin will wrap cl.exe, to
Tim Peterse82b00f2004-08-30 21:14:51 +0000261locate the proper target compiler, and convert compiler options
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000262accordingly. The project files require atleast version 0.9.
Martin v. Löwis13e50fe2004-07-20 14:37:48 +0000263
Martin v. Löwis856bf9a2006-02-14 20:42:55 +0000264Building for AMD64
265------------------
266
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000267The build process for AMD64 / x64 is very similar to standard builds. You just
Martin v. Löwis1561bab2008-02-29 19:39:25 +0000268have to set x64 as platform. In addition, the HOST_PYTHON environment variable
269must point to a Python interpreter (at least 2.4), to support cross-compilation.
Martin v. Löwis856bf9a2006-02-14 20:42:55 +0000270
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000271Building Python Using the free MS Toolkit Compiler
272--------------------------------------------------
273
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000274Microsoft has withdrawn the free MS Toolkit Compiler, so this can no longer
275be considered a supported option. Instead you can use the free VS C++ Express
276Edition.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000277
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000278Profile Guided Optimization
279---------------------------
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000280
Christian Heimes25bb7832008-01-11 16:17:00 +0000281The solution has two configurations for PGO. The PGInstrument
282configuration must be build first. The PGInstrument binaries are
283lniked against a profiling library and contain extra debug
284information. The PGUpdate configuration takes the profiling data and
285generates optimized binaries.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000286
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000287The build_pgo.bat script automates the creation of optimized binaries. It
288creates the PGI files, runs the unit test suite or PyBench with the PGI
289python and finally creates the optimized files.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000290
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000291http://msdn2.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000292
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000293Static library
294--------------
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000295
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000296The solution has no configuration for static libraries. However it is easy
297it build a static library instead of a DLL. You simply have to set the
298"Configuration Type" to "Static Library (.lib)" and alter the preprocessor
299macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may also have to
300change the "Runtime Library" from "Multi-threaded DLL (/MD)" to
301"Multi-threaded (/MT)".
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000302
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000303Visual Studio properties
304------------------------
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000305
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000306The PCbuild solution makes heavy use of Visual Studio property files
307(*.vsprops). The properties can be viewed and altered in the Property
308Manager (View -> Other Windows -> Property Manager).
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000309
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000310 * debug (debug macro: _DEBUG)
311 * pginstrument (PGO)
312 * pgupdate (PGO)
313 +-- pginstrument
314 * pyd (python extension, release build)
315 +-- release
316 +-- pyproject
317 * pyd_d (python extension, debug build)
318 +-- debug
319 +-- pyproject
320 * pyproject (base settings for all projects, user macros like PyDllName)
321 * release (release macro: NDEBUG)
322 * x64 (AMD64 / x64 platform specific settings)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000323
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000324The pyproject propertyfile defines _WIN32 and x64 defines _WIN64 and _M_X64
325although the macros are set by the compiler, too. The GUI doesn't always know
326about the macros and confuse the user with false information.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000327
Tim Petersf9a4a6e2000-07-01 20:38:27 +0000328YOUR OWN EXTENSION DLLs
Tim Peters4b5fb072000-07-01 00:03:43 +0000329-----------------------
Christian Heimes5b5e81c2007-12-31 16:14:33 +0000330
Tim Peters4b5fb072000-07-01 00:03:43 +0000331If you want to create your own extension module DLL, there's an example
332with easy-to-follow instructions in ../PC/example/; read the file
333readme.txt there first.