[Python-checkins] cpython (2.7): Update PCbuild/readme.txt

zach.ware python-checkins at python.org
Tue Sep 8 08:13:09 CEST 2015


https://hg.python.org/cpython/rev/1c5a171e7a13
changeset:   97772:1c5a171e7a13
branch:      2.7
parent:      97762:705ec4145f06
user:        Zachary Ware <zachary.ware at gmail.com>
date:        Tue Sep 08 01:04:01 2015 -0500
summary:
  Update PCbuild/readme.txt

It now better matches 3.5+ and the new reality of 2.7's PCbuild dir.

files:
  PCbuild/readme.txt |  382 ++++++++++++++++++--------------
  1 files changed, 215 insertions(+), 167 deletions(-)


diff --git a/PCbuild/readme.txt b/PCbuild/readme.txt
--- a/PCbuild/readme.txt
+++ b/PCbuild/readme.txt
@@ -1,3 +1,14 @@
+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.
+3.  Install Subversion, and make sure 'svn.exe' is on your PATH.
+4.  Run "build.bat -e" to build Python in 32-bit Release configuration.
+5.  (Optional, but recommended) Run the test suite with "rt.bat -q".
+
+
 Building Python using MSVC 9.0 via MSBuild
 ------------------------------------------
 
@@ -27,43 +38,63 @@
 
 For other Windows platforms and compilers, see ../PC/readme.txt.
 
-All you need to do is open the workspace "pcbuild.sln" in Visual Studio,
-select the desired combination of configuration and platform and eventually
-build the solution. Unless you are going to debug a problem in the core or
-you are going to create an optimized build you want to select "Release" as
-configuration.
+All you need to do to build is 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.
 
-The PCbuild directory is compatible with all versions of Visual Studio from
-VS C++ Express Edition over the standard edition up to the professional
-edition. However the express edition does not support features like solution
-folders or profile guided optimization (PGO). The missing bits and pieces
-won't stop you from building Python.
+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.
 
-The solution is configured to build the projects in the correct order. "Build
-Solution" or F7 takes care of dependencies except for x64 builds. To make
-cross compiling x64 builds on a 32bit OS possible the x64 builds require a
-32bit version of Python.
+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.
 
-NOTE:
-   You probably don't want to build most of the other subprojects, unless
-   you're building an entire Python distribution from scratch, or
-   specifically making changes to the subsystems they implement, or are
-   running a Python core buildbot test slave; see SUBPROJECTS below)
 
-When using the Debug setting, the output files have a _d added to
-their name:  python27_d.dll, python_d.exe, parser_d.pyd, and so on. Both
-the build and rt batch files accept a -d option for debug builds.
+Building Python using the build.bat script
+----------------------------------------------
 
-The 32bit builds end up in the solution folder PCbuild while the x64 builds
-land in the amd64 subfolder. The PGI and PGO builds for profile guided
-optimization end up in their own folders, too.
+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 legacy build directories are no longer
-actively maintained and may not work out of the box.
+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
@@ -73,7 +104,7 @@
     Visual Studio 2005 (8.0)
 
 
-C RUNTIME
+C Runtime
 ---------
 
 Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9).  The executables
@@ -88,187 +119,204 @@
 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.
 
-SUBPROJECTS
------------
-These subprojects should build out of the box.  Subprojects other than the
-main ones (pythoncore, python, pythonw) generally build a DLL (renamed to
-.pyd) from a specific module so that users don't have to load the code
-supporting that module unless they import the module.
 
+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 pop up a DOS box
+    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
-    socketmodule.c
 _testcapi
-    tests of the Python C API, run via Lib/test/test_capi.py, and
-    implemented by module Modules/_testcapimodule.c
 pyexpat
-    Python wrapper for accelerated XML parsing, which incorporates stable
-    code from the Expat project:  http://sourceforge.net/projects/expat/
 select
-    selectmodule.c
 unicodedata
-    large tables of Unicode data
 winsound
-    play sounds (typically .wav files) under Windows
 
-Python-controlled subprojects that wrap external projects:
+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
-    Wraps Berkeley DB 4.7.25, which is currently built by _bsddb.vcproj.
-    project.
+    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.2d 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.6.21, which is currently built by sqlite3.vcproj.
+    Wraps SQLite 3.6.21, which is itself built by sqlite3.vcxproj
+    Homepage:
+        http://www.sqlite.org/
 _tkinter
-    Wraps the Tk windowing system.  Unlike _bsddb and _sqlite3, there's no
-    corresponding tcltk.vcproj-type project that builds Tcl/Tk from vcproj's
-    within our pcbuild.sln, which means this module expects to find a
-    pre-built Tcl/Tk in either ..\externals\tcltk for 32-bit or
-    ..\externals\tcltk64 for 64-bit (relative to this directory).  See below
-    for instructions to build Tcl/Tk.
-bz2
-    Python wrapper for the libbz2 compression library.  Homepage
-        http://sources.redhat.com/bzip2/
-    Download the source from the python.org copy into the dist
-    directory:
+    Wraps version 8.5.15 of the Tk windowing system.
+    Homepage:
+        http://www.tcl.tk/
 
-    svn export http://svn.python.org/projects/external/bzip2-1.0.6
+    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.
 
-    ** NOTE: if you use the PCbuild\get_externals.bat approach for
-    obtaining external sources then you don't need to manually get the source
-    above via subversion. **
+    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.
 
-_ssl
-    Python wrapper for the secure sockets library.
+    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.
 
-    Get the source code through
 
-    svn export http://svn.python.org/projects/external/openssl-1.0.2d
+Getting External Sources
+------------------------
 
-    ** NOTE: if you use the PCbuild\get_externals.bat approach for
-    obtaining external sources then you don't need to manually get the source
-    above via subversion. **
+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
+    http://svn.python.org/projects/external
+via Subversion (so you'll need svn.exe on your PATH) and places them
+in ..\externals (relative to this directory).
 
-    The NASM assembler is required to build OpenSSL.  If you use the
-    PCbuild\get_externals.bat script to get external library sources, it also
-    downloads a version of NASM, which the ssl build script will add to PATH.
-    Otherwise, you can download the NASM installer from
-        http://www.nasm.us/
-    and add NASM to your PATH.
+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.
 
-    You can also install ActivePerl from
-        http://www.activestate.com/activeperl/
-    if you like to use the official sources instead of the files from
-    python's subversion repository. The svn version contains pre-build
-    makefiles and assembly files.
+The get_externals.bat script is called automatically by build.bat when
+you pass the '-e' option to it.
 
-    The build process makes sure that no patented algorithms are included.
-    For now RC5, MDC2 and IDEA are excluded from the build. You may have
-    to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if the build process
-    complains about missing files or forbidden IDEA. Again the files provided
-    in the subversion repository are already fixed.
-
-    The MSVC project simply invokes PCBuild/build_ssl.py to perform
-    the build.  This Python script locates and builds your OpenSSL
-    installation, then invokes a simple makefile to build the final .pyd.
-
-    build_ssl.py attempts to catch the most common errors (such as not
-    being able to find OpenSSL sources, or not being able to find a Perl
-    that works with OpenSSL) and give a reasonable error message.
-    If you have a problem that doesn't seem to be handled correctly
-    (eg, you know you have ActivePerl but we can't find it), please take
-    a peek at build_ssl.py and suggest patches.  Note that build_ssl.py
-    should be able to be run directly from the command-line.
-
-    build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do
-    this by hand.
-
-The subprojects 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.  The easiest way to do this
-is to use the `build.bat` script in this directory to build Python, and pass
-the '-e' switch to tell it to use get_externals.bat to fetch external sources
-and build Tcl/Tk and Tix.  To use get_externals.bat, you'll need to have
-Subversion installed and svn.exe on your PATH.  The script will fetch external
-library sources from http://svn.python.org/external and place them in
-..\externals (relative to this directory).
-
-Building for Itanium
---------------------
-
-Official support for Itanium builds have been dropped from the build. Please
-contact us and provide patches if you are interested in Itanium builds.
-
-Building for AMD64
-------------------
-
-The build process for AMD64 / x64 is very similar to standard builds. You just
-have to set x64 as platform. In addition, the HOST_PYTHON environment variable
-must point to a Python interpreter (at least 2.4), to support cross-compilation.
-
-Building Python Using the free MS Toolkit Compiler
---------------------------------------------------
-
-Microsoft has withdrawn the free MS Toolkit Compiler, so this can no longer
-be considered a supported option. Instead you can use the free VS C++ Express
-Edition.
 
 Profile Guided Optimization
 ---------------------------
 
 The solution has two configurations for PGO. The PGInstrument
-configuration must be build 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.
+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.
+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.
 
-http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx
+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
-it 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)".
+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 heavy use of Visual Studio property files
-(*.vsprops). The properties can be viewed and altered in the Property
-Manager (View -> Other Windows -> Property Manager).
+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.
 
- * debug (debug macro: _DEBUG)
- * pginstrument (PGO)
- * pgupdate (PGO)
-    +-- pginstrument
- * pyd (python extension, release build)
-    +-- release
-    +-- pyproject
- * pyd_d (python extension, debug build)
-    +-- debug
-    +-- pyproject
- * pyproject (base settings for all projects, user macros like PyDllName)
- * release (release macro: NDEBUG)
- * x64 (AMD64 / x64 platform specific settings)
+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 propertyfile defines _WIN32 and x64 defines _WIN64 and _M_X64
-although the macros are set by the compiler, too. The GUI doesn't always know
-about the macros and confuse the user with false information.
+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.
 
-YOUR OWN EXTENSION DLLs
+
+Your Own Extension DLLs
 -----------------------
 
-If you want to create your own extension module DLL, there's an example
-with easy-to-follow instructions in ../PC/example/; read the file
-readme.txt there first.
+If you want to create your own extension module DLL (.pyd), there's an
+example with easy-to-follow instructions in ..\PC\example_nt\; read the
+file readme.txt there first.

-- 
Repository URL: https://hg.python.org/cpython


More information about the Python-checkins mailing list