1Quick Start Guide
2-----------------
3
41. Install Microsoft Visual Studio 2015, any edition.
52. Install Subversion, and make sure 'svn.exe' is on your PATH.
63. Run "build.bat -e" to build Python in 32-bit Release configuration.
74. (Optional, but recommended) Run the test suite with "rt.bat -q".
8
9
10Building Python using Microsoft Visual C++
11------------------------------------------
12
13This directory is used to build CPython for Microsoft Windows NT version
146.0 or higher (Windows Vista, Windows Server 2008, or later) on 32 and 64
15bit platforms. Using this directory requires an installation of
16Microsoft Visual C++ 2015 (MSVC 14.0) of any edition. The specific
17requirements are as follows:
18
19Visual Studio Express 2015 for Desktop
20Visual Studio Professional 2015
21 Either edition is sufficient for building all configurations except
22 for Profile Guided Optimization.
23 The Python build solution pcbuild.sln makes use of Solution Folders,
24 which this edition does not support. Any time pcbuild.sln is opened
25 or reloaded by Visual Studio, a warning about Solution Folders will
26 be displayed, which can be safely dismissed with no impact on your
27 ability to build Python.
28 Required for building 64-bit Debug and Release configuration builds
29Visual Studio Premium 2015
30 Required for building Release configuration builds that make use of
31 Profile Guided Optimization (PGO), on either platform.
32
33All you need to do to build is open the solution "pcbuild.sln" in Visual
34Studio, select the desired combination of configuration and platform,
35then build with "Build Solution". You can also build from the command
36line using the "build.bat" script in this directory; see below for
37details. The solution is configured to build the projects in the correct
38order.
39
40The solution currently supports two platforms. The Win32 platform is
41used to build standard x86-compatible 32-bit binaries, output into the
42win32 sub-directory. The x64 platform is used for building 64-bit AMD64
43(aka x86_64 or EM64T) binaries, output into the amd64 sub-directory.
44The Itanium (IA-64) platform is no longer supported.
45
46Four configuration options are supported by the solution:
47Debug
48 Used to build Python with extra debugging capabilities, equivalent
49 to using ./configure --with-pydebug on UNIX. All binaries built
50 using this configuration have "_d" added to their name:
51 python36_d.dll, python_d.exe, parser_d.pyd, and so on. Both the
52 build and rt (run test) batch files in this directory accept a -d
53 option for debug builds. If you are building Python to help with
54 development of CPython, you will most likely use this configuration.
55PGInstrument, PGUpdate
56 Used to build Python in Release configuration using PGO, which
57 requires Premium Edition of Visual Studio. See the "Profile
58 Guided Optimization" section below for more information. Build
59 output from each of these configurations lands in its own
60 sub-directory of this directory. The official Python releases may
61 be built using these configurations.
62Release
63 Used to build Python as it is meant to be used in production
64 settings, though without PGO.
65
66
67Building Python using the build.bat script
68----------------------------------------------
69
70In this directory you can find build.bat, a script designed to make
71building Python on Windows simpler. This script will use the env.bat
72script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of
73which may be used to build Python, though only Visual Studio 2015 is
74officially supported.
75
76By default, build.bat will build Python in Release configuration for
77the 32-bit Win32 platform. It accepts several arguments to change
78this behavior, try `build.bat -h` to learn more.
79
80
81C Runtime
82---------
83
84Visual Studio 2015 uses version 14 of the C runtime (MSVCRT14). The
85executables no longer use the "Side by Side" assemblies used in previous
86versions of the compiler. This simplifies distribution of applications.
87
88The run time libraries are available under the VC/Redist folder of your
89Visual Studio distribution. For more info, see the Readme in the
90VC/Redist folder.
91
92
93Sub-Projects
94------------
95
96The CPython project is split up into several smaller sub-projects which
97are managed by the pcbuild.sln solution file. Each sub-project is
98represented by a .vcxproj and a .vcxproj.filters file starting with the
99name of the sub-project. These sub-projects fall into a few general
100categories:
101
102The following sub-projects represent the bare minimum required to build
103a functioning CPython interpreter. If nothing else builds but these,
104you'll have a very limited but usable python.exe:
105pythoncore
106 .dll and .lib
107python
108 .exe
109
110These sub-projects provide extra executables that are useful for running
111CPython in different ways:
112pythonw
113 pythonw.exe, a variant of python.exe that doesn't open a Command
114 Prompt window
115pylauncher
116 py.exe, the Python Launcher for Windows, see
117 http://docs.python.org/3/using/windows.html#launcher
118pywlauncher
119 pyw.exe, a variant of py.exe that doesn't open a Command Prompt
120 window
121_testembed
122 _testembed.exe, a small program that embeds Python for testing
123 purposes, used by test_capi.py
124
125These are miscellaneous sub-projects that don't really fit the other
126categories:
127_freeze_importlib
128 _freeze_importlib.exe, used to regenerate Python\importlib.h after
129 changes have been made to Lib\importlib\_bootstrap.py
130python3dll
131 python3.dll, the PEP 384 Stable ABI dll
132xxlimited
133 builds an example module that makes use of the PEP 384 Stable ABI,
134 see Modules\xxlimited.c
135
136The following sub-projects are for individual modules of the standard
137library which are implemented in C; each one builds a DLL (renamed to
138.pyd) of the same name as the project:
139_ctypes
140_ctypes_test
141_decimal
142_elementtree
143_hashlib
144_msi
145_multiprocessing
146_overlapped
147_socket
148_testcapi
149_testbuffer
150_testimportmultiple
151pyexpat
152select
153unicodedata
154winsound
155
156The following Python-controlled sub-projects wrap external projects.
157Note that these external libraries are not necessary for a working
158interpreter, but they do implement several major features. See the
159"Getting External Sources" section below for additional information
160about getting the source for building these libraries. The sub-projects
161are:
162_bz2
163 Python wrapper for version 1.0.6 of the libbzip2 compression library
164 Homepage:
165 http://www.bzip.org/
166_lzma
167 Python wrapper for the liblzma compression library, using pre-built
168 binaries of XZ Utils version 5.0.5
169 Homepage:
170 http://tukaani.org/xz/
171_ssl
172 Python wrapper for version 1.0.2k of the OpenSSL secure sockets
173 library, which is built by ssl.vcxproj
174 Homepage:
175 http://www.openssl.org/
176
177 Building OpenSSL requires nasm.exe (the Netwide Assembler), version
178 2.10 or newer from
179 http://www.nasm.us/
180 to be somewhere on your PATH. More recent versions of OpenSSL may
181 need a later version of NASM. If OpenSSL's self tests don't pass,
182 you should first try to update NASM and do a full rebuild of
183 OpenSSL. If you use the PCbuild\get_externals.bat method
184 for getting sources, it also downloads a version of NASM which the
185 libeay/ssleay sub-projects use.
186
187 The libeay/ssleay sub-projects expect your OpenSSL sources to have
188 already been configured and be ready to build. If you get your sources
189 from svn.python.org as suggested in the "Getting External Sources"
190 section below, the OpenSSL source will already be ready to go. If
191 you want to build a different version, you will need to run
192
193 PCbuild\prepare_ssl.py path\to\openssl-source-dir
194
195 That script will prepare your OpenSSL sources in the same way that
196 those available on svn.python.org have been prepared. Note that
197 Perl must be installed and available on your PATH to configure
198 OpenSSL. ActivePerl is recommended and is available from
199 http://www.activestate.com/activeperl/
200
201 The libeay and ssleay sub-projects will build the modules of OpenSSL
202 required by _ssl and _hashlib and may need to be manually updated when
203 upgrading to a newer version of OpenSSL or when adding new
204 functionality to _ssl or _hashlib. They will not clean up their output
205 with the normal Clean target; CleanAll should be used instead.
206_sqlite3
207 Wraps SQLite 3.14.2.0, which is itself built by sqlite3.vcxproj
208 Homepage:
209 http://www.sqlite.org/
210_tkinter
211 Wraps version 8.6.6 of the Tk windowing system.
212 Homepage:
213 http://www.tcl.tk/
214
215 Tkinter's dependencies are built by the tcl.vcxproj and tk.vcxproj
216 projects. The tix.vcxproj project also builds the Tix extended
217 widget set for use with Tkinter.
218
219 Those three projects install their respective components in a
220 directory alongside the source directories called "tcltk" on
221 Win32 and "tcltk64" on x64. They also copy the Tcl and Tk DLLs
222 into the current output directory, which should ensure that Tkinter
223 is able to load Tcl/Tk without having to change your PATH.
224
225 The tcl, tk, and tix sub-projects do not clean their builds with
226 the normal Clean target; if you need to rebuild, you should use the
227 CleanAll target or manually delete their builds.
228
229
230Getting External Sources
231------------------------
232
233The last category of sub-projects listed above wrap external projects
234Python doesn't control, and as such a little more work is required in
235order to download the relevant source files for each project before they
236can be built. However, a simple script is provided to make this as
237painless as possible, called "get_externals.bat" and located in this
238directory. This script extracts all the external sub-projects from
239 http://svn.python.org/projects/external
240via Subversion (so you'll need svn.exe on your PATH) and places them
241in ..\externals (relative to this directory).
242
243It is also possible to download sources from each project's homepage,
244though you may have to change folder names or pass the names to MSBuild
245as the values of certain properties in order for the build solution to
246find them. This is an advanced topic and not necessarily fully
247supported.
248
249The get_externals.bat script is called automatically by build.bat when
250you pass the '-e' option to it.
251
252
253Profile Guided Optimization
254---------------------------
255
256The solution has two configurations for PGO. The PGInstrument
257configuration must be built first. The PGInstrument binaries are linked
258against a profiling library and contain extra debug information. The
259PGUpdate configuration takes the profiling data and generates optimized
260binaries.
261
262The build_pgo.bat script automates the creation of optimized binaries.
263It creates the PGI files, runs the unit test suite or PyBench with the
264PGI python, and finally creates the optimized files.
265
266See
267 http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.140).aspx
268for more on this topic.
269
270
271Static library
272--------------
273
274The solution has no configuration for static libraries. However it is
275easy to build a static library instead of a DLL. You simply have to set
276the "Configuration Type" to "Static Library (.lib)" and alter the
277preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may
278also have to change the "Runtime Library" from "Multi-threaded DLL
279(/MD)" to "Multi-threaded (/MT)".
280
281
282Visual Studio properties
283------------------------
284
285The PCbuild solution makes use of Visual Studio property files (*.props)
286to simplify each project. The properties can be viewed in the Property
287Manager (View -> Other Windows -> Property Manager) but should be
288carefully modified by hand.
289
290The property files used are:
291 * python (versions, directories and build names)
292 * pyproject (base settings for all projects)
293 * openssl (used by libeay and ssleay projects)
294 * tcltk (used by _tkinter, tcl, tk and tix projects)
295
296The pyproject property file defines all of the build settings for each
297project, with some projects overriding certain specific values. The GUI
298doesn't always reflect the correct settings and may confuse the user
299with false information, especially for settings that automatically adapt
300for diffirent configurations.
301