readme.txt
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 10 Building Python using Microsoft Visual C++ 11 ------------------------------------------ 12 13 This directory is used to build CPython for Microsoft Windows NT version 14 6.0 or higher (Windows Vista, Windows Server 2008, or later) on 32 and 64 15 bit platforms. Using this directory requires an installation of 16 Microsoft Visual C++ 2015 (MSVC 14.0) of any edition. The specific 17 requirements are as follows: 18 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. 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 29 Visual Studio Premium 2015 30 Required for building Release configuration builds that make use of 31 Profile Guided Optimization (PGO), on either platform. 32 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, 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. 39 40 The solution currently supports two platforms. The Win32 platform is 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. 45 46 Four configuration options are supported by the solution: 47 Debug 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. 55 PGInstrument, 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. 62 Release 63 Used to build Python as it is meant to be used in production 64 settings, though without PGO. 65 66 67 Building Python using the build.bat script 68 ---------------------------------------------- 69 70 In this directory you can find build.bat, a script designed to make 71 building Python on Windows simpler. This script will use the env.bat 72 script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of 73 which may be used to build Python, though only Visual Studio 2015 is 74 officially supported. 75 76 By default, build.bat will build Python in Release configuration for 77 the 32-bit Win32 platform. It accepts several arguments to change 78 this behavior, try `build.bat -h` to learn more. 79 80 81 C Runtime 82 --------- 83 84 Visual Studio 2015 uses version 14 of the C runtime (MSVCRT14). The 85 executables no longer use the "Side by Side" assemblies used in previous 86 versions of the compiler. This simplifies distribution of applications. 87 88 The run time libraries are available under the VC/Redist folder of your 89 Visual Studio distribution. For more info, see the Readme in the 90 VC/Redist folder. 91 92 93 Sub-Projects 94 ------------ 95 96 The CPython project is split up into several smaller sub-projects which 97 are managed by the pcbuild.sln solution file. Each sub-project is 98 represented by a .vcxproj and a .vcxproj.filters file starting with the 99 name of the sub-project. These sub-projects fall into a few general 100 categories: 101 102 The following sub-projects represent the bare minimum required to build 103 a functioning CPython interpreter. If nothing else builds but these, 104 you'll have a very limited but usable python.exe: 105 pythoncore 106 .dll and .lib 107 python 108 .exe 109 110 These sub-projects provide extra executables that are useful for running 111 CPython in different ways: 112 pythonw 113 pythonw.exe, a variant of python.exe that doesn't open a Command 114 Prompt window 115 pylauncher 116 py.exe, the Python Launcher for Windows, see 117 http://docs.python.org/3/using/windows.html#launcher 118 pywlauncher 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 125 These are miscellaneous sub-projects that don't really fit the other 126 categories: 127 _freeze_importlib 128 _freeze_importlib.exe, used to regenerate Python\importlib.h after 129 changes have been made to Lib\importlib\_bootstrap.py 130 python3dll 131 python3.dll, the PEP 384 Stable ABI dll 132 xxlimited 133 builds an example module that makes use of the PEP 384 Stable ABI, 134 see Modules\xxlimited.c 135 136 The following sub-projects are for individual modules of the standard 137 library 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 151 pyexpat 152 select 153 unicodedata 154 winsound 155 156 The following Python-controlled sub-projects wrap external projects. 157 Note that these external libraries are not necessary for a working 158 interpreter, but they do implement several major features. See the 159 "Getting External Sources" section below for additional information 160 about getting the source for building these libraries. The sub-projects 161 are: 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 230 Getting External Sources 231 ------------------------ 232 233 The last category of sub-projects listed above wrap external projects 234 Python doesn't control, and as such a little more work is required in 235 order to download the relevant source files for each project before they 236 can be built. However, a simple script is provided to make this as 237 painless as possible, called "get_externals.bat" and located in this 238 directory. This script extracts all the external sub-projects from 239 http://svn.python.org/projects/external 240 via Subversion (so you'll need svn.exe on your PATH) and places them 241 in ..\externals (relative to this directory). 242 243 It is also possible to download sources from each project's homepage, 244 though you may have to change folder names or pass the names to MSBuild 245 as the values of certain properties in order for the build solution to 246 find them. This is an advanced topic and not necessarily fully 247 supported. 248 249 The get_externals.bat script is called automatically by build.bat when 250 you pass the '-e' option to it. 251 252 253 Profile Guided Optimization 254 --------------------------- 255 256 The solution has two configurations for PGO. The PGInstrument 257 configuration must be built first. The PGInstrument binaries are linked 258 against a profiling library and contain extra debug information. The 259 PGUpdate configuration takes the profiling data and generates optimized 260 binaries. 261 262 The build_pgo.bat script automates the creation of optimized binaries. 263 It creates the PGI files, runs the unit test suite or PyBench with the 264 PGI python, and finally creates the optimized files. 265 266 See 267 http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.140).aspx 268 for more on this topic. 269 270 271 Static library 272 -------------- 273 274 The solution has no configuration for static libraries. However it is 275 easy to build a static library instead of a DLL. You simply have to set 276 the "Configuration Type" to "Static Library (.lib)" and alter the 277 preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may 278 also have to change the "Runtime Library" from "Multi-threaded DLL 279 (/MD)" to "Multi-threaded (/MT)". 280 281 282 Visual Studio properties 283 ------------------------ 284 285 The PCbuild solution makes use of Visual Studio property files (*.props) 286 to simplify each project. The properties can be viewed in the Property 287 Manager (View -> Other Windows -> Property Manager) but should be 288 carefully modified by hand. 289 290 The 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 296 The pyproject property file defines all of the build settings for each 297 project, with some projects overriding certain specific values. The GUI 298 doesn't always reflect the correct settings and may confuse the user 299 with false information, especially for settings that automatically adapt 300 for diffirent configurations. 301
