You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
331 lines
14 KiB
331 lines
14 KiB
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.
|