blob: 00b50be0175565903e7d881aa9d2ee379d00c461 [file] [log] [blame]
Zachary Ware50ebf032015-04-13 12:30:53 -05001Quick 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
Zachary Ware30cc6fa2015-04-13 12:28:11 -050010Building Python using Microsoft Visual C++
11------------------------------------------
12
13This directory is used to build CPython for Microsoft Windows NT version
Zachary Ware50ebf032015-04-13 12:30:53 -0500146.0 or higher (Windows Vista, Windows Server 2008, or later) on 32 and 64
Zachary Ware30cc6fa2015-04-13 12:28:11 -050015bit platforms. Using this directory requires an installation of
Zachary Ware50ebf032015-04-13 12:30:53 -050016Microsoft Visual C++ 2015 (MSVC 14.0) of any edition. The specific
Zachary Ware30cc6fa2015-04-13 12:28:11 -050017requirements are as follows:
18
Zachary Ware50ebf032015-04-13 12:30:53 -050019Visual Studio Express 2015 for Desktop
20Visual Studio Professional 2015
21 Either edition is sufficient for building all configurations except
22 for Profile Guided Optimization.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050023 The Python build solution pcbuild.sln makes use of Solution Folders,
24 which this edition does not support. Any time pcbuild.sln is opened
Zachary Ware50ebf032015-04-13 12:30:53 -050025 or reloaded by Visual Studio, a warning about Solution Folders will
26 be displayed, which can be safely dismissed with no impact on your
Zachary Ware30cc6fa2015-04-13 12:28:11 -050027 ability to build Python.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050028 Required for building 64-bit Debug and Release configuration builds
Zachary Ware50ebf032015-04-13 12:30:53 -050029Visual Studio Premium 2015
Zachary Ware30cc6fa2015-04-13 12:28:11 -050030 Required for building Release configuration builds that make use of
31 Profile Guided Optimization (PGO), on either platform.
32
Zachary Ware30cc6fa2015-04-13 12:28:11 -050033All you need to do to build is open the solution "pcbuild.sln" in Visual
34Studio, select the desired combination of configuration and platform,
Zachary Ware50ebf032015-04-13 12:30:53 -050035then 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050039
40The solution currently supports two platforms. The Win32 platform is
Zachary Ware50ebf032015-04-13 12:30:53 -050041used 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.
Zachary Ware875ef4c2015-09-08 01:12:00 -050044The Itanium (IA-64) platform is no longer supported.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050045
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:
Ned Deily4829bc62016-09-12 17:29:04 -040051 python37_d.dll, python_d.exe, parser_d.pyd, and so on. Both the
Zachary Ware30cc6fa2015-04-13 12:28:11 -050052 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
Zachary Ware50ebf032015-04-13 12:30:53 -050060 sub-directory of this directory. The official Python releases may
61 be built using these configurations.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050062Release
63 Used to build Python as it is meant to be used in production
64 settings, though without PGO.
65
66
Zachary Ware50ebf032015-04-13 12:30:53 -050067Building Python using the build.bat script
68----------------------------------------------
Zachary Ware30cc6fa2015-04-13 12:28:11 -050069
Zachary Ware50ebf032015-04-13 12:30:53 -050070In 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050075
Zachary Ware50ebf032015-04-13 12:30:53 -050076By default, build.bat will build Python in Release configuration for
77the 32-bit Win32 platform. It accepts several arguments to change
Zachary Ware875ef4c2015-09-08 01:12:00 -050078this behavior, try `build.bat -h` to learn more.
Zachary Ware30cc6fa2015-04-13 12:28:11 -050079
80
81C Runtime
82---------
83
Zachary Ware50ebf032015-04-13 12:30:53 -050084Visual Studio 2015 uses version 14 of the C runtime (MSVCRT14). The
Zachary Ware30cc6fa2015-04-13 12:28:11 -050085executables 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
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500109
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
Zachary Ware50ebf032015-04-13 12:30:53 -0500126categories:
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500127_freeze_importlib
128 _freeze_importlib.exe, used to regenerate Python\importlib.h after
129 changes have been made to Lib\importlib\_bootstrap.py
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500130python3dll
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
Zachary Ware068534a2016-10-10 21:57:20 -0500172 Python wrapper for version 1.0.2j of the OpenSSL secure sockets
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500173 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
Zachary Wared1f7c592015-06-16 23:27:56 -0500183 OpenSSL. If you use the PCbuild\get_externals.bat method
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500184 for getting sources, it also downloads a version of NASM which the
Zachary Ware6c7f2ac2015-06-17 09:45:22 -0500185 libeay/ssleay sub-projects use.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500186
Zachary Ware50ebf032015-04-13 12:30:53 -0500187 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
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500199 http://www.activestate.com/activeperl/
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500200
Zachary Ware50ebf032015-04-13 12:30:53 -0500201 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500206_sqlite3
Zachary Ware547d1562016-10-10 22:36:21 -0500207 Wraps SQLite 3.14.2.0, which is itself built by sqlite3.vcxproj
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500208 Homepage:
209 http://www.sqlite.org/
210_tkinter
Zachary Ware28c31842016-07-28 18:39:11 -0500211 Wraps version 8.6.6 of the Tk windowing system.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500212 Homepage:
213 http://www.tcl.tk/
214
Zachary Ware50ebf032015-04-13 12:30:53 -0500215 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500228
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
Zachary Ware50ebf032015-04-13 12:30:53 -0500236can 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
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500239 http://svn.python.org/projects/external
Zachary Ware50ebf032015-04-13 12:30:53 -0500240via Subversion (so you'll need svn.exe on your PATH) and places them
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500241in ..\externals (relative to this directory).
242
243It is also possible to download sources from each project's homepage,
Zachary Ware50ebf032015-04-13 12:30:53 -0500244though 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500248
Zachary Ware875ef4c2015-09-08 01:12:00 -0500249The get_externals.bat script is called automatically by build.bat when
250you pass the '-e' option to it.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500251
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
Zachary Ware875ef4c2015-09-08 01:12:00 -0500267 http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.140).aspx
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500268for 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
Zachary Ware50ebf032015-04-13 12:30:53 -0500285The 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.
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500289
Zachary Ware50ebf032015-04-13 12:30:53 -0500290The 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)
Zachary Ware30cc6fa2015-04-13 12:28:11 -0500295
Zachary Ware50ebf032015-04-13 12:30:53 -0500296The 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.