readme.txt
1 Quick Start Guide 2 ----------------- 3 4 1. Install Microsoft Visual Studio 2008, any edition. 5 2. Install Microsoft Visual Studio 2010, any edition, or Windows SDK 7.1 6 and any version of Microsoft Visual Studio newer than 2010. 7 2a. Optionally install Python 3.6 or later. If not installed, 8 get_externals.bat (build.bat -e) will download and use Python via 9 NuGet. 10 3. Run "build.bat -e" to build Python in 32-bit Release configuration. 11 4. (Optional, but recommended) Run the test suite with "rt.bat -q". 12 13 14 Building Python using MSVC 9.0 via MSBuild 15 ------------------------------------------ 16 17 This directory is used to build Python for Win32 and x64 platforms, e.g. 18 Windows 2000 and later. In order to use the project files in this 19 directory, you must have installed the MSVC 9.0 compilers, the v90 20 PlatformToolset project files for MSBuild, and MSBuild version 4.0 or later. 21 The easiest way to make sure you have all of these components is to install 22 Visual Studio 2008 and Visual Studio 2010. Another configuration proven 23 to work is Visual Studio 2008, Windows SDK 7.1, and Visual Studio 2013. 24 25 If you only have Visual Studio 2008 available, use the project files in 26 ../PC/VS9.0 which are fully supported and specifically for VS 2008. 27 28 If you do not have Visual Studio 2008 available, you can use these project 29 files to build using a different version of MSVC. For example, use 30 31 PCbuild\build.bat "/p:PlatformToolset=v100" 32 33 to build using MSVC10 (Visual Studio 2010). 34 35 ***WARNING*** 36 Building Python 2.7 for Windows using any toolchain that doesn't link 37 against MSVCRT90.dll is *unsupported* as the resulting python.exe will 38 not be able to use precompiled extension modules that do link against 39 MSVCRT90.dll. 40 41 For other Windows platforms and compilers, see ../PC/readme.txt. 42 43 To build modules that depend on external libraries, you need to download 44 (and, for some of them, build) those first. It's thus recommended to build 45 from the command line once as specified below under "Getting External Sources" 46 as that does this automatically. 47 48 Then, to continue development, you can open the solution "pcbuild.sln" in 49 Visual Studio, select the desired combination of configuration and platform, 50 then build with "Build Solution". You can also build from the command 51 line using the "build.bat" script in this directory; see below for 52 details. The solution is configured to build the projects in the correct 53 order. 54 55 To build an installer package, refer to the README in the Tools/msi folder. 56 57 The solution currently supports two platforms. The Win32 platform is 58 used to build standard x86-compatible 32-bit binaries, output into this 59 directory. The x64 platform is used for building 64-bit AMD64 (aka 60 x86_64 or EM64T) binaries, output into the amd64 sub-directory. The 61 Itanium (IA-64) platform is no longer supported. 62 63 Four configuration options are supported by the solution: 64 Debug 65 Used to build Python with extra debugging capabilities, equivalent 66 to using ./configure --with-pydebug on UNIX. All binaries built 67 using this configuration have "_d" added to their name: 68 python27_d.dll, python_d.exe, parser_d.pyd, and so on. Both the 69 build and rt (run test) batch files in this directory accept a -d 70 option for debug builds. If you are building Python to help with 71 development of CPython, you will most likely use this configuration. 72 PGInstrument, PGUpdate 73 Used to build Python in Release configuration using PGO, which 74 requires Professional Edition of Visual Studio 2008. See the 75 "Profile Guided Optimization" section below for more information. 76 Build output from each of these configurations lands in its own 77 sub-directory of this directory. The official Python releases may 78 be built using these configurations. 79 Release 80 Used to build Python as it is meant to be used in production 81 settings, though without PGO. 82 83 84 Building Python using the build.bat script 85 ---------------------------------------------- 86 87 In this directory you can find build.bat, a script designed to make 88 building Python on Windows simpler. This script will use the env.bat 89 script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of 90 which contains a usable version of MSBuild. 91 92 By default, build.bat will build Python in Release configuration for 93 the 32-bit Win32 platform. It accepts several arguments to change 94 this behavior, try `build.bat -h` to learn more. 95 96 97 Legacy support 98 -------------- 99 100 You can find build directories for older versions of Visual Studio and 101 Visual C++ in the PC directory. The project files in PC/VS9.0/ are 102 specific to Visual Studio 2008, and will be fully supported for the life 103 of Python 2.7. 104 105 The following legacy build directories are no longer maintained and may 106 not work out of the box. 107 108 PC/VC6/ 109 Visual C++ 6.0 110 PC/VS7.1/ 111 Visual Studio 2003 (7.1) 112 PC/VS8.0/ 113 Visual Studio 2005 (8.0) 114 115 116 C Runtime 117 --------- 118 119 Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9). The executables 120 are linked to a CRT "side by side" assembly which must be present on the target 121 machine. This is available under the VC/Redist folder of your visual studio 122 distribution. On XP and later operating systems that support 123 side-by-side assemblies it is not enough to have the msvcrt90.dll present, 124 it has to be there as a whole assembly, that is, a folder with the .dll 125 and a .manifest. Also, a check is made for the correct version. 126 Therefore, one should distribute this assembly with the dlls, and keep 127 it in the same directory. For compatibility with older systems, one should 128 also set the PATH to this directory so that the dll can be found. 129 For more info, see the Readme in the VC/Redist folder. 130 131 132 Sub-Projects 133 ------------ 134 135 The CPython project is split up into several smaller sub-projects which 136 are managed by the pcbuild.sln solution file. Each sub-project is 137 represented by a .vcxproj and a .vcxproj.filters file starting with the 138 name of the sub-project. These sub-projects fall into a few general 139 categories: 140 141 The following sub-projects represent the bare minimum required to build 142 a functioning CPython interpreter. If nothing else builds but these, 143 you'll have a very limited but usable python.exe: 144 pythoncore 145 .dll and .lib 146 python 147 .exe 148 149 These sub-projects provide extra executables that are useful for running 150 CPython in different ways: 151 pythonw 152 pythonw.exe, a variant of python.exe that doesn't open a Command 153 Prompt window 154 pylauncher 155 py.exe, the Python Launcher for Windows, see 156 http://docs.python.org/3/using/windows.html#launcher 157 pywlauncher 158 pyw.exe, a variant of py.exe that doesn't open a Command Prompt 159 window 160 161 The following sub-projects are for individual modules of the standard 162 library which are implemented in C; each one builds a DLL (renamed to 163 .pyd) of the same name as the project: 164 _ctypes 165 _ctypes_test 166 _elementtree 167 _hashlib 168 _msi 169 _multiprocessing 170 _socket 171 _testcapi 172 pyexpat 173 select 174 unicodedata 175 winsound 176 177 There is also a w9xpopen project to build w9xpopen.exe, which is used 178 for platform.popen() on platforms whose COMSPEC points to 'command.com'. 179 180 The following Python-controlled sub-projects wrap external projects. 181 Note that these external libraries are not necessary for a working 182 interpreter, but they do implement several major features. See the 183 "Getting External Sources" section below for additional information 184 about getting the source for building these libraries. The sub-projects 185 are: 186 _bsddb 187 Python wrapper for Berkeley DB version 4.7.25. 188 Homepage: 189 http://www.oracle.com/us/products/database/berkeley-db/ 190 _bz2 191 Python wrapper for version 1.0.6 of the libbzip2 compression library 192 Homepage: 193 http://www.bzip.org/ 194 _ssl 195 Python wrapper for version 1.0.2o of the OpenSSL secure sockets 196 library, which is built by ssl.vcxproj 197 Homepage: 198 http://www.openssl.org/ 199 200 Building OpenSSL requires nasm.exe (the Netwide Assembler), version 201 2.10 or newer from 202 http://www.nasm.us/ 203 to be somewhere on your PATH. More recent versions of OpenSSL may 204 need a later version of NASM. If OpenSSL's self tests don't pass, 205 you should first try to update NASM and do a full rebuild of 206 OpenSSL. If you use the PCbuild\get_externals.bat method 207 for getting sources, it also downloads a version of NASM which the 208 libeay/ssleay sub-projects use. 209 210 The libeay/ssleay sub-projects expect your OpenSSL sources to have 211 already been configured and be ready to build. If you get your sources 212 from svn.python.org as suggested in the "Getting External Sources" 213 section below, the OpenSSL source will already be ready to go. If 214 you want to build a different version, you will need to run 215 216 PCbuild\prepare_ssl.py path\to\openssl-source-dir 217 218 That script will prepare your OpenSSL sources in the same way that 219 those available on svn.python.org have been prepared. Note that 220 Perl must be installed and available on your PATH to configure 221 OpenSSL. ActivePerl is recommended and is available from 222 http://www.activestate.com/activeperl/ 223 224 The libeay and ssleay sub-projects will build the modules of OpenSSL 225 required by _ssl and _hashlib and may need to be manually updated when 226 upgrading to a newer version of OpenSSL or when adding new 227 functionality to _ssl or _hashlib. They will not clean up their output 228 with the normal Clean target; CleanAll should be used instead. 229 _sqlite3 230 Wraps SQLite 3.8.11.0, which is itself built by sqlite3.vcxproj 231 Homepage: 232 http://www.sqlite.org/ 233 _tkinter 234 Wraps version 8.5.19 of the Tk windowing system. 235 Homepage: 236 http://www.tcl.tk/ 237 238 Tkinter's dependencies are built by the tcl.vcxproj and tk.vcxproj 239 projects. The tix.vcxproj project also builds the Tix extended 240 widget set for use with Tkinter. 241 242 Those three projects install their respective components in a 243 directory alongside the source directories called "tcltk" on 244 Win32 and "tcltk64" on x64. They also copy the Tcl and Tk DLLs 245 into the current output directory, which should ensure that Tkinter 246 is able to load Tcl/Tk without having to change your PATH. 247 248 The tcl, tk, and tix sub-projects do not clean their builds with 249 the normal Clean target; if you need to rebuild, you should use the 250 CleanAll target or manually delete their builds. 251 252 253 Getting External Sources 254 ------------------------ 255 256 The last category of sub-projects listed above wrap external projects 257 Python doesn't control, and as such a little more work is required in 258 order to download the relevant source files for each project before they 259 can be built. However, a simple script is provided to make this as 260 painless as possible, called "get_externals.bat" and located in this 261 directory. This script extracts all the external sub-projects from 262 https://github.com/python/cpython-source-deps 263 and 264 https://github.com/python/cpython-bin-deps 265 via a Python script called "get_external.py", located in this directory. 266 If Python 3.6 or later is not available via the "py.exe" launcher, the 267 path or command to use for Python can be provided in the PYTHON_FOR_BUILD 268 environment variable, or get_externals.bat will download the latest 269 version of NuGet and use it to download the latest "pythonx86" package 270 for use with get_external.py. Everything downloaded by these scripts is 271 stored in ..\externals (relative to this directory). 272 273 It is also possible to download sources from each project's homepage, 274 though you may have to change folder names or pass the names to MSBuild 275 as the values of certain properties in order for the build solution to 276 find them. This is an advanced topic and not necessarily fully 277 supported. 278 279 The get_externals.bat script is called automatically by build.bat when 280 you pass the '-e' option to it. 281 282 283 Profile Guided Optimization 284 --------------------------- 285 286 The solution has two configurations for PGO. The PGInstrument 287 configuration must be built first. The PGInstrument binaries are linked 288 against a profiling library and contain extra debug information. The 289 PGUpdate configuration takes the profiling data and generates optimized 290 binaries. 291 292 The build_pgo.bat script automates the creation of optimized binaries. 293 It creates the PGI files, runs the unit test suite or PyBench with the 294 PGI python, and finally creates the optimized files. 295 296 See 297 http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx 298 for more on this topic. 299 300 301 Static library 302 -------------- 303 304 The solution has no configuration for static libraries. However it is 305 easy to build a static library instead of a DLL. You simply have to set 306 the "Configuration Type" to "Static Library (.lib)" and alter the 307 preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may 308 also have to change the "Runtime Library" from "Multi-threaded DLL 309 (/MD)" to "Multi-threaded (/MT)". 310 311 312 Visual Studio properties 313 ------------------------ 314 315 The PCbuild solution makes use of Visual Studio property files (*.props) 316 to simplify each project. The properties can be viewed in the Property 317 Manager (View -> Other Windows -> Property Manager) but should be 318 carefully modified by hand. 319 320 The property files used are: 321 * python (versions, directories and build names) 322 * pyproject (base settings for all projects) 323 * openssl (used by libeay and ssleay projects) 324 * tcltk (used by _tkinter, tcl, tk and tix projects) 325 326 The pyproject property file defines all of the build settings for each 327 project, with some projects overriding certain specific values. The GUI 328 doesn't always reflect the correct settings and may confuse the user 329 with false information, especially for settings that automatically adapt 330 for diffirent configurations. 331
