| Quick Start Guide |
| ----------------- |
| |
| 1. Install Microsoft Visual Studio 2008, any edition. |
| 2. Install Microsoft Visual Studio 2010, any edition, or Windows SDK 7.1 |
| and any version of Microsoft Visual Studio newer than 2010. |
| 2a. Optionally install Python 3.6 or later. If not installed, |
| get_externals.bat (build.bat -e) will download and use Python via |
| NuGet. |
| 3. Run "build.bat -e" to build Python in 32-bit Release configuration. |
| 4. (Optional, but recommended) Run the test suite with "rt.bat -q". |
| |
| |
| Building Python using MSVC 9.0 via MSBuild |
| ------------------------------------------ |
| |
| This directory is used to build Python for Win32 and x64 platforms, e.g. |
| Windows 2000 and later. In order to use the project files in this |
| directory, you must have installed the MSVC 9.0 compilers, the v90 |
| PlatformToolset project files for MSBuild, and MSBuild version 4.0 or later. |
| The easiest way to make sure you have all of these components is to install |
| Visual Studio 2008 and Visual Studio 2010. Another configuration proven |
| to work is Visual Studio 2008, Windows SDK 7.1, and Visual Studio 2013. |
| |
| If you only have Visual Studio 2008 available, use the project files in |
| ../PC/VS9.0 which are fully supported and specifically for VS 2008. |
| |
| If you do not have Visual Studio 2008 available, you can use these project |
| files to build using a different version of MSVC. For example, use |
| |
| PCbuild\build.bat "/p:PlatformToolset=v100" |
| |
| to build using MSVC10 (Visual Studio 2010). |
| |
| ***WARNING*** |
| Building Python 2.7 for Windows using any toolchain that doesn't link |
| against MSVCRT90.dll is *unsupported* as the resulting python.exe will |
| not be able to use precompiled extension modules that do link against |
| MSVCRT90.dll. |
| |
| For other Windows platforms and compilers, see ../PC/readme.txt. |
| |
| To build modules that depend on external libraries, you need to download |
| (and, for some of them, build) those first. It's thus recommended to build |
| from the command line once as specified below under "Getting External Sources" |
| as that does this automatically. |
| |
| Then, to continue development, you can open the solution "pcbuild.sln" in |
| Visual Studio, select the desired combination of configuration and platform, |
| then build with "Build Solution". You can also build from the command |
| line using the "build.bat" script in this directory; see below for |
| details. The solution is configured to build the projects in the correct |
| order. |
| |
| To build an installer package, refer to the README in the Tools/msi folder. |
| |
| The solution currently supports two platforms. The Win32 platform is |
| used to build standard x86-compatible 32-bit binaries, output into this |
| directory. The x64 platform is used for building 64-bit AMD64 (aka |
| x86_64 or EM64T) binaries, output into the amd64 sub-directory. The |
| Itanium (IA-64) platform is no longer supported. |
| |
| Four configuration options are supported by the solution: |
| Debug |
| Used to build Python with extra debugging capabilities, equivalent |
| to using ./configure --with-pydebug on UNIX. All binaries built |
| using this configuration have "_d" added to their name: |
| python27_d.dll, python_d.exe, parser_d.pyd, and so on. Both the |
| build and rt (run test) batch files in this directory accept a -d |
| option for debug builds. If you are building Python to help with |
| development of CPython, you will most likely use this configuration. |
| PGInstrument, PGUpdate |
| Used to build Python in Release configuration using PGO, which |
| requires Professional Edition of Visual Studio 2008. See the |
| "Profile Guided Optimization" section below for more information. |
| Build output from each of these configurations lands in its own |
| sub-directory of this directory. The official Python releases may |
| be built using these configurations. |
| Release |
| Used to build Python as it is meant to be used in production |
| settings, though without PGO. |
| |
| |
| Building Python using the build.bat script |
| ---------------------------------------------- |
| |
| In this directory you can find build.bat, a script designed to make |
| building Python on Windows simpler. This script will use the env.bat |
| script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of |
| which contains a usable version of MSBuild. |
| |
| By default, build.bat will build Python in Release configuration for |
| the 32-bit Win32 platform. It accepts several arguments to change |
| this behavior, try `build.bat -h` to learn more. |
| |
| |
| Legacy support |
| -------------- |
| |
| You can find build directories for older versions of Visual Studio and |
| Visual C++ in the PC directory. The project files in PC/VS9.0/ are |
| specific to Visual Studio 2008, and will be fully supported for the life |
| of Python 2.7. |
| |
| The following legacy build directories are no longer maintained and may |
| not work out of the box. |
| |
| PC/VC6/ |
| Visual C++ 6.0 |
| PC/VS7.1/ |
| Visual Studio 2003 (7.1) |
| PC/VS8.0/ |
| Visual Studio 2005 (8.0) |
| |
| |
| C Runtime |
| --------- |
| |
| Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9). The executables |
| are linked to a CRT "side by side" assembly which must be present on the target |
| machine. This is available under the VC/Redist folder of your visual studio |
| distribution. On XP and later operating systems that support |
| side-by-side assemblies it is not enough to have the msvcrt90.dll present, |
| it has to be there as a whole assembly, that is, a folder with the .dll |
| and a .manifest. Also, a check is made for the correct version. |
| Therefore, one should distribute this assembly with the dlls, and keep |
| it in the same directory. For compatibility with older systems, one should |
| also set the PATH to this directory so that the dll can be found. |
| For more info, see the Readme in the VC/Redist folder. |
| |
| |
| Sub-Projects |
| ------------ |
| |
| The CPython project is split up into several smaller sub-projects which |
| are managed by the pcbuild.sln solution file. Each sub-project is |
| represented by a .vcxproj and a .vcxproj.filters file starting with the |
| name of the sub-project. These sub-projects fall into a few general |
| categories: |
| |
| The following sub-projects represent the bare minimum required to build |
| a functioning CPython interpreter. If nothing else builds but these, |
| you'll have a very limited but usable python.exe: |
| pythoncore |
| .dll and .lib |
| python |
| .exe |
| |
| These sub-projects provide extra executables that are useful for running |
| CPython in different ways: |
| pythonw |
| pythonw.exe, a variant of python.exe that doesn't open a Command |
| Prompt window |
| pylauncher |
| py.exe, the Python Launcher for Windows, see |
| http://docs.python.org/3/using/windows.html#launcher |
| pywlauncher |
| pyw.exe, a variant of py.exe that doesn't open a Command Prompt |
| window |
| |
| The following sub-projects are for individual modules of the standard |
| library which are implemented in C; each one builds a DLL (renamed to |
| .pyd) of the same name as the project: |
| _ctypes |
| _ctypes_test |
| _elementtree |
| _hashlib |
| _msi |
| _multiprocessing |
| _socket |
| _testcapi |
| pyexpat |
| select |
| unicodedata |
| winsound |
| |
| There is also a w9xpopen project to build w9xpopen.exe, which is used |
| for platform.popen() on platforms whose COMSPEC points to 'command.com'. |
| |
| The following Python-controlled sub-projects wrap external projects. |
| Note that these external libraries are not necessary for a working |
| interpreter, but they do implement several major features. See the |
| "Getting External Sources" section below for additional information |
| about getting the source for building these libraries. The sub-projects |
| are: |
| _bsddb |
| Python wrapper for Berkeley DB version 4.7.25. |
| Homepage: |
| http://www.oracle.com/us/products/database/berkeley-db/ |
| _bz2 |
| Python wrapper for version 1.0.6 of the libbzip2 compression library |
| Homepage: |
| http://www.bzip.org/ |
| _ssl |
| Python wrapper for version 1.0.2o of the OpenSSL secure sockets |
| library, which is built by ssl.vcxproj |
| Homepage: |
| http://www.openssl.org/ |
| |
| Building OpenSSL requires nasm.exe (the Netwide Assembler), version |
| 2.10 or newer from |
| http://www.nasm.us/ |
| to be somewhere on your PATH. More recent versions of OpenSSL may |
| need a later version of NASM. If OpenSSL's self tests don't pass, |
| you should first try to update NASM and do a full rebuild of |
| OpenSSL. If you use the PCbuild\get_externals.bat method |
| for getting sources, it also downloads a version of NASM which the |
| libeay/ssleay sub-projects use. |
| |
| The libeay/ssleay sub-projects expect your OpenSSL sources to have |
| already been configured and be ready to build. If you get your sources |
| from svn.python.org as suggested in the "Getting External Sources" |
| section below, the OpenSSL source will already be ready to go. If |
| you want to build a different version, you will need to run |
| |
| PCbuild\prepare_ssl.py path\to\openssl-source-dir |
| |
| That script will prepare your OpenSSL sources in the same way that |
| those available on svn.python.org have been prepared. Note that |
| Perl must be installed and available on your PATH to configure |
| OpenSSL. ActivePerl is recommended and is available from |
| http://www.activestate.com/activeperl/ |
| |
| The libeay and ssleay sub-projects will build the modules of OpenSSL |
| required by _ssl and _hashlib and may need to be manually updated when |
| upgrading to a newer version of OpenSSL or when adding new |
| functionality to _ssl or _hashlib. They will not clean up their output |
| with the normal Clean target; CleanAll should be used instead. |
| _sqlite3 |
| Wraps SQLite 3.8.11.0, which is itself built by sqlite3.vcxproj |
| Homepage: |
| http://www.sqlite.org/ |
| _tkinter |
| Wraps version 8.5.19 of the Tk windowing system. |
| Homepage: |
| http://www.tcl.tk/ |
| |
| Tkinter's dependencies are built by the tcl.vcxproj and tk.vcxproj |
| projects. The tix.vcxproj project also builds the Tix extended |
| widget set for use with Tkinter. |
| |
| Those three projects install their respective components in a |
| directory alongside the source directories called "tcltk" on |
| Win32 and "tcltk64" on x64. They also copy the Tcl and Tk DLLs |
| into the current output directory, which should ensure that Tkinter |
| is able to load Tcl/Tk without having to change your PATH. |
| |
| The tcl, tk, and tix sub-projects do not clean their builds with |
| the normal Clean target; if you need to rebuild, you should use the |
| CleanAll target or manually delete their builds. |
| |
| |
| Getting External Sources |
| ------------------------ |
| |
| The last category of sub-projects listed above wrap external projects |
| Python doesn't control, and as such a little more work is required in |
| order to download the relevant source files for each project before they |
| can be built. However, a simple script is provided to make this as |
| painless as possible, called "get_externals.bat" and located in this |
| directory. This script extracts all the external sub-projects from |
| https://github.com/python/cpython-source-deps |
| and |
| https://github.com/python/cpython-bin-deps |
| via a Python script called "get_external.py", located in this directory. |
| If Python 3.6 or later is not available via the "py.exe" launcher, the |
| path or command to use for Python can be provided in the PYTHON_FOR_BUILD |
| environment variable, or get_externals.bat will download the latest |
| version of NuGet and use it to download the latest "pythonx86" package |
| for use with get_external.py. Everything downloaded by these scripts is |
| stored in ..\externals (relative to this directory). |
| |
| It is also possible to download sources from each project's homepage, |
| though you may have to change folder names or pass the names to MSBuild |
| as the values of certain properties in order for the build solution to |
| find them. This is an advanced topic and not necessarily fully |
| supported. |
| |
| The get_externals.bat script is called automatically by build.bat when |
| you pass the '-e' option to it. |
| |
| |
| Profile Guided Optimization |
| --------------------------- |
| |
| The solution has two configurations for PGO. The PGInstrument |
| configuration must be built first. The PGInstrument binaries are linked |
| against a profiling library and contain extra debug information. The |
| PGUpdate configuration takes the profiling data and generates optimized |
| binaries. |
| |
| The build_pgo.bat script automates the creation of optimized binaries. |
| It creates the PGI files, runs the unit test suite or PyBench with the |
| PGI python, and finally creates the optimized files. |
| |
| See |
| http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx |
| for more on this topic. |
| |
| |
| Static library |
| -------------- |
| |
| The solution has no configuration for static libraries. However it is |
| easy to build a static library instead of a DLL. You simply have to set |
| the "Configuration Type" to "Static Library (.lib)" and alter the |
| preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may |
| also have to change the "Runtime Library" from "Multi-threaded DLL |
| (/MD)" to "Multi-threaded (/MT)". |
| |
| |
| Visual Studio properties |
| ------------------------ |
| |
| The PCbuild solution makes use of Visual Studio property files (*.props) |
| to simplify each project. The properties can be viewed in the Property |
| Manager (View -> Other Windows -> Property Manager) but should be |
| carefully modified by hand. |
| |
| The property files used are: |
| * python (versions, directories and build names) |
| * pyproject (base settings for all projects) |
| * openssl (used by libeay and ssleay projects) |
| * tcltk (used by _tkinter, tcl, tk and tix projects) |
| |
| The pyproject property file defines all of the build settings for each |
| project, with some projects overriding certain specific values. The GUI |
| doesn't always reflect the correct settings and may confuse the user |
| with false information, especially for settings that automatically adapt |
| for diffirent configurations. |