1
Building Python using Microsoft Visual C++
2
------------------------------------------
4
This directory is used to build CPython for Microsoft Windows NT version
5
5.1 or higher (Windows XP, Windows Server 2003, or later) on 32 and 64
6
bit platforms. Using this directory requires an installation of
7
Microsoft Visual C++ 2010 (MSVC 10.0) of any edition. The specific
8
requirements are as follows:
9
Visual C++ 2010 Express Edition
10
Required for building 32-bit Debug and Release configuration builds.
11
This edition does not support "solution folders", which pcbuild.sln
12
uses; this will not prevent building.
13
Visual Studio 2010 Standard Edition
14
Required for building 64-bit Debug and Release configuration builds
15
Visual Studio 2010 Professional Edition
16
Required for building Release configuration builds that make use of
17
Profile Guided Optimization (PGO), on either platform. The official
18
Python releases are built with Professional Edition using PGO.
20
All you need to do to build is open the solution "pcbuild.sln" in Visual
21
Studio, select the desired combination of configuration and platform,
22
then build with "Build Solution" or the F7 keyboard shortcut. You can
23
also build from the command line using the "build.bat" script in this
24
directory. The solution is configured to build the projects in the
27
The solution currently supports two platforms. The Win32 platform is
28
used to build standard x86-compatible 32-bit binaries, output into this
29
directory. The x64 platform is used for building 64-bit AMD64 (aka
30
x86_64 or EM64T) binaries, output into the amd64 sub-directory which
31
will be created if it doesn't already exist. The Itanium (IA-64)
32
platform is no longer supported. See the "Building for AMD64" section
33
below for more information about 64-bit builds.
35
Four configuration options are supported by the solution:
37
Used to build Python with extra debugging capabilities, equivalent
38
to using ./configure --with-pydebug on UNIX. All binaries built
39
using this configuration have "_d" added to their name:
40
python34_d.dll, python_d.exe, parser_d.pyd, and so on. Both the
41
build and rt (run test) batch files in this directory accept a -d
42
option for debug builds. If you are building Python to help with
43
development of CPython, you will most likely use this configuration.
44
PGInstrument, PGUpdate
45
Used to build Python in Release configuration using PGO, which
46
requires Professional Edition of Visual Studio. See the "Profile
47
Guided Optimization" section below for more information. Build
48
output from each of these configurations lands in its own
49
sub-directory of this directory. The official Python releases are
50
built using these configurations.
52
Used to build Python as it is meant to be used in production
53
settings, though without PGO.
59
You can find build directories for older versions of Visual Studio and
60
Visual C++ in the PC directory. The legacy build directories are no
61
longer actively maintained and may not work out of the box.
63
Currently, the only legacy build directory is PC\VS9.0, for Visual
70
Visual Studio 2010 uses version 10 of the C runtime (MSVCRT10). The
71
executables no longer use the "Side by Side" assemblies used in previous
72
versions of the compiler. This simplifies distribution of applications.
74
The run time libraries are available under the VC/Redist folder of your
75
Visual Studio distribution. For more info, see the Readme in the
82
The CPython project is split up into several smaller sub-projects which
83
are managed by the pcbuild.sln solution file. Each sub-project is
84
represented by a .vcxproj and a .vcxproj.filters file starting with the
85
name of the sub-project. These sub-projects fall into a few general
88
The following sub-projects represent the bare minimum required to build
89
a functioning CPython interpreter. If nothing else builds but these,
90
you'll have a very limited but usable python.exe:
96
kill_python.exe, a small program designed to kill any instances of
97
python(_d).exe that are running and live in the build output
98
directory; this is meant to avoid build issues due to locked files
99
make_buildinfo, make_versioninfo
100
helpers to provide necessary information to the build process
102
These sub-projects provide extra executables that are useful for running
103
CPython in different ways:
105
pythonw.exe, a variant of python.exe that doesn't open a Command
108
py.exe, the Python Launcher for Windows, see
109
http://docs.python.org/3/using/windows.html#launcher
111
pyw.exe, a variant of py.exe that doesn't open a Command Prompt
114
_testembed.exe, a small program that embeds Python for testing
115
purposes, used by test_capi.py
117
These are miscellaneous sub-projects that don't really fit the other
118
categories. By default, these projects do not build in Debug
121
_freeze_importlib.exe, used to regenerate Python\importlib.h after
122
changes have been made to Lib\importlib\_bootstrap.py
124
..\Lib\distutils\command\wininst-10.0[-amd64].exe, the base
125
executable used by the distutils bdist_wininst command
127
python3.dll, the PEP 384 Stable ABI dll
129
builds an example module that makes use of the PEP 384 Stable ABI,
130
see Modules\xxlimited.c
132
The following sub-projects are for individual modules of the standard
133
library which are implemented in C; each one builds a DLL (renamed to
134
.pyd) of the same name as the project:
153
The following Python-controlled sub-projects wrap external projects.
154
Note that these external libraries are not necessary for a working
155
interpreter, but they do implement several major features. See the
156
"Getting External Sources" section below for additional information
157
about getting the source for building these libraries. The sub-projects
160
Python wrapper for version 1.0.6 of the libbzip2 compression library
164
Python wrapper for the liblzma compression library, using pre-built
165
binaries of XZ Utils version 5.0.5
167
http://tukaani.org/xz/
169
Python wrapper for version 1.0.1e of the OpenSSL secure sockets
170
library, which is built by ssl.vcxproj
172
http://www.openssl.org/
174
Building OpenSSL requires nasm.exe (the Netwide Assembler), version
177
to be somewhere on your PATH. More recent versions of OpenSSL may
178
need a later version of NASM. If OpenSSL's self tests don't pass,
179
you should first try to update NASM and do a full rebuild of
182
If you like to use the official sources instead of the files from
183
python.org's subversion repository, Perl is required to build the
184
necessary makefiles and assembly files. ActivePerl is available
186
http://www.activestate.com/activeperl/
187
The svn.python.org version contains pre-built makefiles and assembly
190
The build process makes sure that no patented algorithms are
191
included. For now RC5, MDC2 and IDEA are excluded from the build.
192
You may have to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if
193
using official sources; the svn.python.org-hosted version is already
196
The ssl.vcxproj sub-project simply invokes PCbuild/build_ssl.py,
197
which locates and builds OpenSSL.
199
build_ssl.py attempts to catch the most common errors (such as not
200
being able to find OpenSSL sources, or not being able to find a Perl
201
that works with OpenSSL) and give a reasonable error message. If
202
you have a problem that doesn't seem to be handled correctly (e.g.,
203
you know you have ActivePerl but we can't find it), please take a
204
peek at build_ssl.py and suggest patches. Note that build_ssl.py
205
should be able to be run directly from the command-line.
207
The ssl sub-project does not have the ability to clean the OpenSSL
208
build; if you need to rebuild, you'll have to clean it by hand.
210
Wraps SQLite 3.8.1, which is itself built by sqlite3.vcxproj
212
http://www.sqlite.org/
214
Wraps version 8.6.1 of the Tk windowing system.
218
Unlike the other external libraries listed above, Tk must be built
219
separately before the _tkinter module can be built. This means that
220
a pre-built Tcl/Tk installation is expected in ..\..\tcltk (tcltk64
221
for 64-bit) relative to this directory. See "Getting External
222
Sources" below for the easiest method to ensure Tcl/Tk is built.
225
Getting External Sources
226
------------------------
228
The last category of sub-projects listed above wrap external projects
229
Python doesn't control, and as such a little more work is required in
230
order to download the relevant source files for each project before they
231
can be built. The buildbots must ensure that all libraries are present
232
before building, so the easiest approach is to run either external.bat
233
or external-amd64.bat (depending on platform) in the ..\Tools\buildbot
234
directory from ..\, i.e.:
236
C:\python\cpython\PCbuild>cd ..
237
C:\python\cpython>Tools\buildbot\external.bat
239
This extracts all the external sub-projects from
240
http://svn.python.org/projects/external
241
via Subversion (so you'll need an svn.exe on your PATH) and places them
242
in ..\.. (relative to this directory).
244
It is also possible to download sources from each project's homepage,
245
though you may have to change the names of some folders in order to make
246
things work. For instance, if you were to download a version 5.0.7 of
247
XZ Utils, you would need to extract the archive into ..\..\xz-5.0.5
248
anyway, since that is where the solution is set to look for xz. The
249
same is true for all other external projects.
251
The external(-amd64).bat scripts will also build a debug build of
252
Tcl/Tk, but there aren't any equivalent batch files for building release
253
versions of Tcl/Tk currently available. If you need to build a release
254
version of Tcl/Tk, just take a look at the relevant external(-amd64).bat
255
file and find the two nmake lines, then call each one without the
256
'DEBUG=1' parameter, i.e.:
258
The external-amd64.bat file contains this for tcl:
259
nmake -f makefile.vc DEBUG=1 MACHINE=AMD64 INSTALLDIR=..\..\tcltk64 clean all install
261
So for a release build, you'd call it as:
262
nmake -f makefile.vc MACHINE=AMD64 INSTALLDIR=..\..\tcltk64 clean all install
264
Note that the above command is called from within ..\..\tcl-8.6.1.0\win
265
(relative to this directory); don't forget to build Tk as well as Tcl!
267
This will be cleaned up in the future; http://bugs.python.org/issue15968
268
tracks adding a new tcltk.vcxproj file that will build Tcl/Tk and Tix
269
the same way the other external projects listed above are built.
275
The build process for AMD64 / x64 is very similar to standard builds,
276
you just have to set x64 as platform. In addition, the HOST_PYTHON
277
environment variable must point to a Python interpreter (at least 2.4),
278
to support cross-compilation from Win32. Note that Visual Studio
279
requires either Standard Edition or better, or Express Edition with the
280
Windows SDK 64-bit compilers to be available in order to build 64-bit
284
Profile Guided Optimization
285
---------------------------
287
The solution has two configurations for PGO. The PGInstrument
288
configuration must be built first. The PGInstrument binaries are linked
289
against a profiling library and contain extra debug information. The
290
PGUpdate configuration takes the profiling data and generates optimized
293
The build_pgo.bat script automates the creation of optimized binaries.
294
It creates the PGI files, runs the unit test suite or PyBench with the
295
PGI python, and finally creates the optimized files.
298
http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.100).aspx
299
for more on this topic.
305
The solution has no configuration for static libraries. However it is
306
easy to build a static library instead of a DLL. You simply have to set
307
the "Configuration Type" to "Static Library (.lib)" and alter the
308
preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may
309
also have to change the "Runtime Library" from "Multi-threaded DLL
310
(/MD)" to "Multi-threaded (/MT)".
313
Visual Studio properties
314
------------------------
316
The PCbuild solution makes heavy use of Visual Studio property files
317
(*.props). The properties can be viewed and altered in the Property
318
Manager (View -> Other Windows -> Property Manager).
320
The property files used are (+-- = "also imports"):
321
* debug (debug macro: _DEBUG)
325
* pyd (python extension, release build)
328
* pyd_d (python extension, debug build)
331
* pyproject (base settings for all projects, user macros like PyDllName)
332
* release (release macro: NDEBUG)
333
* sqlite3 (used only by sqlite3.vcxproj)
334
* x64 (AMD64 / x64 platform specific settings)
336
The pyproject property file defines _WIN32 and x64 defines _WIN64 and
337
_M_X64 although the macros are set by the compiler, too. The GUI doesn't
338
always know about the macros and confuse the user with false
342
Your Own Extension DLLs
343
-----------------------
345
If you want to create your own extension module DLL (.pyd), there's an
346
example with easy-to-follow instructions in ..\PC\example\; read the
347
file readme.txt there first.
added
removed
PCbuild/readme.txt
