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