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