Zachary Ware | 30cc6fa | 2015-04-13 12:28:11 -0500 | [diff] [blame] | 1 | Building Python using Microsoft Visual C++
|
| 2 | ------------------------------------------
|
| 3 |
|
| 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 |
|
| 10 | Visual C++ 2010 Express Edition
|
| 11 | Required for building 32-bit Debug and Release configuration builds.
|
| 12 | The Python build solution pcbuild.sln makes use of Solution Folders,
|
| 13 | which this edition does not support. Any time pcbuild.sln is opened
|
| 14 | or reloaded by Visual C++, a warning about Solution Folders will be
|
| 15 | displayed which can be safely dismissed with no impact on your
|
| 16 | ability to build Python.
|
| 17 | Visual Studio 2010 Professional Edition
|
| 18 | Required for building 64-bit Debug and Release configuration builds
|
| 19 | Visual Studio 2010 Premium Edition
|
| 20 | Required for building Release configuration builds that make use of
|
| 21 | Profile Guided Optimization (PGO), on either platform.
|
| 22 |
|
| 23 | Installing Service Pack 1 for Visual Studio 2010 is highly recommended
|
| 24 | to avoid LNK1123 errors.
|
| 25 |
|
| 26 | All you need to do to build is open the solution "pcbuild.sln" in Visual
|
| 27 | Studio, select the desired combination of configuration and platform,
|
| 28 | then build with "Build Solution" or the F7 keyboard shortcut. You can
|
| 29 | also build from the command line using the "build.bat" script in this
|
| 30 | directory. The solution is configured to build the projects in the
|
| 31 | correct order.
|
| 32 |
|
| 33 | The solution currently supports two platforms. The Win32 platform is
|
| 34 | used to build standard x86-compatible 32-bit binaries, output into this
|
| 35 | directory. The x64 platform is used for building 64-bit AMD64 (aka
|
| 36 | x86_64 or EM64T) binaries, output into the amd64 sub-directory which
|
| 37 | will be created if it doesn't already exist. The Itanium (IA-64)
|
| 38 | platform is no longer supported. See the "Building for AMD64" section
|
| 39 | below for more information about 64-bit builds.
|
| 40 |
|
| 41 | Four configuration options are supported by the solution:
|
| 42 | Debug
|
| 43 | Used to build Python with extra debugging capabilities, equivalent
|
| 44 | to using ./configure --with-pydebug on UNIX. All binaries built
|
| 45 | using this configuration have "_d" added to their name:
|
| 46 | python34_d.dll, python_d.exe, parser_d.pyd, and so on. Both the
|
| 47 | build and rt (run test) batch files in this directory accept a -d
|
| 48 | option for debug builds. If you are building Python to help with
|
| 49 | development of CPython, you will most likely use this configuration.
|
| 50 | PGInstrument, PGUpdate
|
| 51 | Used to build Python in Release configuration using PGO, which
|
| 52 | requires Premium Edition of Visual Studio. See the "Profile
|
| 53 | Guided Optimization" section below for more information. Build
|
| 54 | output from each of these configurations lands in its own
|
| 55 | sub-directory of this directory. The official Python releases are
|
| 56 | built using these configurations.
|
| 57 | Release
|
| 58 | Used to build Python as it is meant to be used in production
|
| 59 | settings, though without PGO.
|
| 60 |
|
| 61 |
|
| 62 | Legacy support
|
| 63 | --------------
|
| 64 |
|
| 65 | You can find build directories for older versions of Visual Studio and
|
| 66 | Visual C++ in the PC directory. The legacy build directories are no
|
| 67 | longer actively maintained and may not work out of the box.
|
| 68 |
|
| 69 | Currently, the only legacy build directory is PC\VS9.0, for Visual
|
| 70 | Studio 2008 (9.0).
|
| 71 |
|
| 72 |
|
| 73 | C Runtime
|
| 74 | ---------
|
| 75 |
|
| 76 | Visual Studio 2010 uses version 10 of the C runtime (MSVCRT10). The
|
| 77 | executables no longer use the "Side by Side" assemblies used in previous
|
| 78 | versions of the compiler. This simplifies distribution of applications.
|
| 79 |
|
| 80 | The run time libraries are available under the VC/Redist folder of your
|
| 81 | Visual Studio distribution. For more info, see the Readme in the
|
| 82 | VC/Redist folder.
|
| 83 |
|
| 84 |
|
| 85 | Sub-Projects
|
| 86 | ------------
|
| 87 |
|
| 88 | The CPython project is split up into several smaller sub-projects which
|
| 89 | are managed by the pcbuild.sln solution file. Each sub-project is
|
| 90 | represented by a .vcxproj and a .vcxproj.filters file starting with the
|
| 91 | name of the sub-project. These sub-projects fall into a few general
|
| 92 | categories:
|
| 93 |
|
| 94 | The following sub-projects represent the bare minimum required to build
|
| 95 | a functioning CPython interpreter. If nothing else builds but these,
|
| 96 | you'll have a very limited but usable python.exe:
|
| 97 | pythoncore
|
| 98 | .dll and .lib
|
| 99 | python
|
| 100 | .exe
|
| 101 | kill_python
|
| 102 | kill_python.exe, a small program designed to kill any instances of
|
| 103 | python(_d).exe that are running and live in the build output
|
| 104 | directory; this is meant to avoid build issues due to locked files
|
| 105 | make_buildinfo, make_versioninfo
|
| 106 | helpers to provide necessary information to the build process
|
| 107 |
|
| 108 | These sub-projects provide extra executables that are useful for running
|
| 109 | CPython in different ways:
|
| 110 | pythonw
|
| 111 | pythonw.exe, a variant of python.exe that doesn't open a Command
|
| 112 | Prompt window
|
| 113 | pylauncher
|
| 114 | py.exe, the Python Launcher for Windows, see
|
| 115 | http://docs.python.org/3/using/windows.html#launcher
|
| 116 | pywlauncher
|
| 117 | pyw.exe, a variant of py.exe that doesn't open a Command Prompt
|
| 118 | window
|
| 119 | _testembed
|
| 120 | _testembed.exe, a small program that embeds Python for testing
|
| 121 | purposes, used by test_capi.py
|
| 122 |
|
| 123 | These are miscellaneous sub-projects that don't really fit the other
|
| 124 | categories. By default, these projects do not build in Debug
|
| 125 | configuration:
|
| 126 | _freeze_importlib
|
| 127 | _freeze_importlib.exe, used to regenerate Python\importlib.h after
|
| 128 | changes have been made to Lib\importlib\_bootstrap.py
|
| 129 | bdist_wininst
|
| 130 | ..\Lib\distutils\command\wininst-10.0[-amd64].exe, the base
|
| 131 | executable used by the distutils bdist_wininst command
|
| 132 | python3dll
|
| 133 | python3.dll, the PEP 384 Stable ABI dll
|
| 134 | xxlimited
|
| 135 | builds an example module that makes use of the PEP 384 Stable ABI,
|
| 136 | see Modules\xxlimited.c
|
| 137 |
|
| 138 | The following sub-projects are for individual modules of the standard
|
| 139 | library which are implemented in C; each one builds a DLL (renamed to
|
| 140 | .pyd) of the same name as the project:
|
| 141 | _ctypes
|
| 142 | _ctypes_test
|
| 143 | _decimal
|
| 144 | _elementtree
|
| 145 | _hashlib
|
| 146 | _msi
|
| 147 | _multiprocessing
|
| 148 | _overlapped
|
| 149 | _socket
|
| 150 | _testcapi
|
| 151 | _testbuffer
|
| 152 | _testimportmultiple
|
| 153 | pyexpat
|
| 154 | select
|
| 155 | unicodedata
|
| 156 | winsound
|
| 157 |
|
| 158 | The following Python-controlled sub-projects wrap external projects.
|
| 159 | Note that these external libraries are not necessary for a working
|
| 160 | interpreter, but they do implement several major features. See the
|
| 161 | "Getting External Sources" section below for additional information
|
| 162 | about getting the source for building these libraries. The sub-projects
|
| 163 | are:
|
| 164 | _bz2
|
| 165 | Python wrapper for version 1.0.6 of the libbzip2 compression library
|
| 166 | Homepage:
|
| 167 | http://www.bzip.org/
|
| 168 | _lzma
|
| 169 | Python wrapper for the liblzma compression library, using pre-built
|
| 170 | binaries of XZ Utils version 5.0.5
|
| 171 | Homepage:
|
| 172 | http://tukaani.org/xz/
|
| 173 | _ssl
|
| 174 | Python wrapper for version 1.0.2a of the OpenSSL secure sockets
|
| 175 | library, which is built by ssl.vcxproj
|
| 176 | Homepage:
|
| 177 | http://www.openssl.org/
|
| 178 |
|
| 179 | Building OpenSSL requires nasm.exe (the Netwide Assembler), version
|
| 180 | 2.10 or newer from
|
| 181 | http://www.nasm.us/
|
| 182 | to be somewhere on your PATH. More recent versions of OpenSSL may
|
| 183 | need a later version of NASM. If OpenSSL's self tests don't pass,
|
| 184 | you should first try to update NASM and do a full rebuild of
|
Zachary Ware | d1f7c59 | 2015-06-16 23:27:56 -0500 | [diff] [blame^] | 185 | OpenSSL. If you use the PCbuild\get_externals.bat method
|
Zachary Ware | 30cc6fa | 2015-04-13 12:28:11 -0500 | [diff] [blame] | 186 | for getting sources, it also downloads a version of NASM which the
|
| 187 | ssl build script will add to PATH.
|
| 188 |
|
| 189 | If you like to use the official sources instead of the files from
|
| 190 | python.org's subversion repository, Perl is required to build the
|
| 191 | necessary makefiles and assembly files. ActivePerl is available
|
| 192 | from
|
| 193 | http://www.activestate.com/activeperl/
|
| 194 | The svn.python.org version contains pre-built makefiles and assembly
|
| 195 | files.
|
| 196 |
|
| 197 | The build process makes sure that no patented algorithms are
|
| 198 | included. For now RC5, MDC2 and IDEA are excluded from the build.
|
| 199 | You may have to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if
|
| 200 | using official sources; the svn.python.org-hosted version is already
|
| 201 | fixed.
|
| 202 |
|
| 203 | The ssl.vcxproj sub-project simply invokes PCbuild/build_ssl.py,
|
| 204 | which locates and builds OpenSSL.
|
| 205 |
|
| 206 | build_ssl.py attempts to catch the most common errors (such as not
|
| 207 | being able to find OpenSSL sources, or not being able to find a Perl
|
| 208 | that works with OpenSSL) and give a reasonable error message. If
|
| 209 | you have a problem that doesn't seem to be handled correctly (e.g.,
|
| 210 | you know you have ActivePerl but we can't find it), please take a
|
| 211 | peek at build_ssl.py and suggest patches. Note that build_ssl.py
|
| 212 | should be able to be run directly from the command-line.
|
| 213 |
|
| 214 | The ssl sub-project does not have the ability to clean the OpenSSL
|
| 215 | build; if you need to rebuild, you'll have to clean it by hand.
|
| 216 | _sqlite3
|
| 217 | Wraps SQLite 3.8.3.1, which is itself built by sqlite3.vcxproj
|
| 218 | Homepage:
|
| 219 | http://www.sqlite.org/
|
| 220 | _tkinter
|
| 221 | Wraps version 8.6.1 of the Tk windowing system.
|
| 222 | Homepage:
|
| 223 | http://www.tcl.tk/
|
| 224 |
|
| 225 | Unlike the other external libraries listed above, Tk must be built
|
| 226 | separately before the _tkinter module can be built. This means that
|
| 227 | a pre-built Tcl/Tk installation is expected in ..\externals\tcltk
|
| 228 | (tcltk64 for 64-bit) relative to this directory. See "Getting
|
| 229 | External Sources" below for the easiest method to ensure Tcl/Tk is
|
| 230 | built.
|
| 231 |
|
| 232 |
|
| 233 | Getting External Sources
|
| 234 | ------------------------
|
| 235 |
|
| 236 | The last category of sub-projects listed above wrap external projects
|
| 237 | Python doesn't control, and as such a little more work is required in
|
| 238 | order to download the relevant source files for each project before they
|
Zachary Ware | d1f7c59 | 2015-06-16 23:27:56 -0500 | [diff] [blame^] | 239 | can be built. The easiest way to do this is to use the `build.bat`
|
| 240 | script in this directory to build Python, and pass the '-e' switch to
|
| 241 | tell it to use get_externals.bat to fetch external sources and build
|
| 242 | Tcl/Tk and Tix. To use get_externals.bat, you'll need to have
|
| 243 | Subversion installed and svn.exe on your PATH. The script will fetch
|
| 244 | external library sources from http://svn.python.org/external and place
|
| 245 | them in ..\externals (relative to this directory).
|
Zachary Ware | 30cc6fa | 2015-04-13 12:28:11 -0500 | [diff] [blame] | 246 |
|
| 247 |
|
| 248 | Building for AMD64
|
| 249 | ------------------
|
| 250 |
|
| 251 | The build process for AMD64 / x64 is very similar to standard builds,
|
| 252 | you just have to set x64 as platform. In addition, the HOST_PYTHON
|
| 253 | environment variable must point to a Python interpreter (at least 2.4),
|
| 254 | to support cross-compilation from Win32. Note that Visual Studio
|
| 255 | requires Professional Edition or better in order to build 64-bit
|
| 256 | binaries.
|
| 257 |
|
| 258 |
|
| 259 | Profile Guided Optimization
|
| 260 | ---------------------------
|
| 261 |
|
| 262 | The solution has two configurations for PGO. The PGInstrument
|
| 263 | configuration must be built first. The PGInstrument binaries are linked
|
| 264 | against a profiling library and contain extra debug information. The
|
| 265 | PGUpdate configuration takes the profiling data and generates optimized
|
| 266 | binaries.
|
| 267 |
|
| 268 | The build_pgo.bat script automates the creation of optimized binaries.
|
| 269 | It creates the PGI files, runs the unit test suite or PyBench with the
|
| 270 | PGI python, and finally creates the optimized files.
|
| 271 |
|
| 272 | See
|
| 273 | http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.100).aspx
|
| 274 | for more on this topic.
|
| 275 |
|
| 276 |
|
| 277 | Static library
|
| 278 | --------------
|
| 279 |
|
| 280 | The solution has no configuration for static libraries. However it is
|
| 281 | easy to build a static library instead of a DLL. You simply have to set
|
| 282 | the "Configuration Type" to "Static Library (.lib)" and alter the
|
| 283 | preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may
|
| 284 | also have to change the "Runtime Library" from "Multi-threaded DLL
|
| 285 | (/MD)" to "Multi-threaded (/MT)".
|
| 286 |
|
| 287 |
|
| 288 | Visual Studio properties
|
| 289 | ------------------------
|
| 290 |
|
| 291 | The PCbuild solution makes heavy use of Visual Studio property files
|
| 292 | (*.props). The properties can be viewed and altered in the Property
|
| 293 | Manager (View -> Other Windows -> Property Manager).
|
| 294 |
|
| 295 | The property files used are (+-- = "also imports"):
|
| 296 | * debug (debug macro: _DEBUG)
|
| 297 | * pginstrument (PGO)
|
| 298 | * pgupdate (PGO)
|
| 299 | +-- pginstrument
|
| 300 | * pyd (python extension, release build)
|
| 301 | +-- release
|
| 302 | +-- pyproject
|
| 303 | * pyd_d (python extension, debug build)
|
| 304 | +-- debug
|
| 305 | +-- pyproject
|
| 306 | * pyproject (base settings for all projects, user macros like PyDllName)
|
| 307 | * release (release macro: NDEBUG)
|
| 308 | * sqlite3 (used only by sqlite3.vcxproj)
|
| 309 | * x64 (AMD64 / x64 platform specific settings)
|
| 310 |
|
| 311 | The pyproject property file defines _WIN32 and x64 defines _WIN64 and
|
| 312 | _M_X64 although the macros are set by the compiler, too. The GUI doesn't
|
| 313 | always know about the macros and confuse the user with false
|
| 314 | information.
|
| 315 |
|
| 316 |
|
| 317 | Your Own Extension DLLs
|
| 318 | -----------------------
|
| 319 |
|
| 320 | If you want to create your own extension module DLL (.pyd), there's an
|
| 321 | example with easy-to-follow instructions in ..\PC\example\; read the
|
| 322 | file readme.txt there first.
|