+Quick Start Guide\r
+-----------------\r
+\r
+1. Install Microsoft Visual Studio 2008, any edition.\r
+2. Install Microsoft Visual Studio 2010, any edition, or Windows SDK 7.1\r
+ and any version of Microsoft Visual Studio newer than 2010.\r
+3. Install Subversion, and make sure 'svn.exe' is on your PATH.\r
+4. Run "build.bat -e" to build Python in 32-bit Release configuration.\r
+5. (Optional, but recommended) Run the test suite with "rt.bat -q".\r
+\r
+\r
Building Python using MSVC 9.0 via MSBuild\r
------------------------------------------\r
\r
\r
For other Windows platforms and compilers, see ../PC/readme.txt.\r
\r
-All you need to do is open the workspace "pcbuild.sln" in Visual Studio,\r
-select the desired combination of configuration and platform and eventually\r
-build the solution. Unless you are going to debug a problem in the core or\r
-you are going to create an optimized build you want to select "Release" as\r
-configuration.\r
-\r
-The PCbuild directory is compatible with all versions of Visual Studio from\r
-VS C++ Express Edition over the standard edition up to the professional\r
-edition. However the express edition does not support features like solution\r
-folders or profile guided optimization (PGO). The missing bits and pieces\r
-won't stop you from building Python.\r
-\r
-The solution is configured to build the projects in the correct order. "Build\r
-Solution" or F7 takes care of dependencies except for x64 builds. To make\r
-cross compiling x64 builds on a 32bit OS possible the x64 builds require a\r
-32bit version of Python.\r
-\r
-NOTE:\r
- You probably don't want to build most of the other subprojects, unless\r
- you're building an entire Python distribution from scratch, or\r
- specifically making changes to the subsystems they implement, or are\r
- running a Python core buildbot test slave; see SUBPROJECTS below)\r
-\r
-When using the Debug setting, the output files have a _d added to\r
-their name: python27_d.dll, python_d.exe, parser_d.pyd, and so on. Both\r
-the build and rt batch files accept a -d option for debug builds.\r
-\r
-The 32bit builds end up in the solution folder PCbuild while the x64 builds\r
-land in the amd64 subfolder. The PGI and PGO builds for profile guided\r
-optimization end up in their own folders, too.\r
+All you need to do to build is open the solution "pcbuild.sln" in Visual\r
+Studio, select the desired combination of configuration and platform,\r
+then build with "Build Solution". You can also build from the command\r
+line using the "build.bat" script in this directory; see below for\r
+details. The solution is configured to build the projects in the correct\r
+order.\r
+\r
+The solution currently supports two platforms. The Win32 platform is\r
+used to build standard x86-compatible 32-bit binaries, output into this\r
+directory. The x64 platform is used for building 64-bit AMD64 (aka\r
+x86_64 or EM64T) binaries, output into the amd64 sub-directory. The\r
+Itanium (IA-64) platform is no longer supported.\r
+\r
+Four configuration options are supported by the solution:\r
+Debug\r
+ Used to build Python with extra debugging capabilities, equivalent\r
+ to using ./configure --with-pydebug on UNIX. All binaries built\r
+ using this configuration have "_d" added to their name:\r
+ python27_d.dll, python_d.exe, parser_d.pyd, and so on. Both the\r
+ build and rt (run test) batch files in this directory accept a -d\r
+ option for debug builds. If you are building Python to help with\r
+ development of CPython, you will most likely use this configuration.\r
+PGInstrument, PGUpdate\r
+ Used to build Python in Release configuration using PGO, which\r
+ requires Professional Edition of Visual Studio 2008. See the\r
+ "Profile Guided Optimization" section below for more information.\r
+ Build output from each of these configurations lands in its own\r
+ sub-directory of this directory. The official Python releases may\r
+ be built using these configurations.\r
+Release\r
+ Used to build Python as it is meant to be used in production\r
+ settings, though without PGO.\r
+\r
+\r
+Building Python using the build.bat script\r
+----------------------------------------------\r
+\r
+In this directory you can find build.bat, a script designed to make\r
+building Python on Windows simpler. This script will use the env.bat\r
+script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of\r
+which contains a usable version of MSBuild.\r
+\r
+By default, build.bat will build Python in Release configuration for\r
+the 32-bit Win32 platform. It accepts several arguments to change\r
+this behavior, try `build.bat -h` to learn more.\r
+\r
\r
Legacy support\r
--------------\r
\r
You can find build directories for older versions of Visual Studio and\r
-Visual C++ in the PC directory. The legacy build directories are no longer\r
-actively maintained and may not work out of the box.\r
+Visual C++ in the PC directory. The project files in PC/VS9.0/ are\r
+specific to Visual Studio 2008, and will be fully supported for the life\r
+of Python 2.7.\r
+\r
+The following legacy build directories are no longer maintained and may\r
+not work out of the box.\r
\r
PC/VC6/\r
Visual C++ 6.0\r
Visual Studio 2005 (8.0)\r
\r
\r
-C RUNTIME\r
+C Runtime\r
---------\r
\r
Visual Studio 2008 uses version 9 of the C runtime (MSVCRT9). The executables\r
also set the PATH to this directory so that the dll can be found.\r
For more info, see the Readme in the VC/Redist folder.\r
\r
-SUBPROJECTS\r
------------\r
-These subprojects should build out of the box. Subprojects other than the\r
-main ones (pythoncore, python, pythonw) generally build a DLL (renamed to\r
-.pyd) from a specific module so that users don't have to load the code\r
-supporting that module unless they import the module.\r
\r
+Sub-Projects\r
+------------\r
+\r
+The CPython project is split up into several smaller sub-projects which\r
+are managed by the pcbuild.sln solution file. Each sub-project is\r
+represented by a .vcxproj and a .vcxproj.filters file starting with the\r
+name of the sub-project. These sub-projects fall into a few general\r
+categories:\r
+\r
+The following sub-projects represent the bare minimum required to build\r
+a functioning CPython interpreter. If nothing else builds but these,\r
+you'll have a very limited but usable python.exe:\r
pythoncore\r
.dll and .lib\r
python\r
.exe\r
+\r
+These sub-projects provide extra executables that are useful for running\r
+CPython in different ways:\r
pythonw\r
- pythonw.exe, a variant of python.exe that doesn't pop up a DOS box\r
+ pythonw.exe, a variant of python.exe that doesn't open a Command\r
+ Prompt window\r
+pylauncher\r
+ py.exe, the Python Launcher for Windows, see\r
+ http://docs.python.org/3/using/windows.html#launcher\r
+pywlauncher\r
+ pyw.exe, a variant of py.exe that doesn't open a Command Prompt\r
+ window\r
+\r
+The following sub-projects are for individual modules of the standard\r
+library which are implemented in C; each one builds a DLL (renamed to\r
+.pyd) of the same name as the project:\r
+_ctypes\r
+_ctypes_test\r
+_elementtree\r
+_hashlib\r
+_msi\r
+_multiprocessing\r
_socket\r
- socketmodule.c\r
_testcapi\r
- tests of the Python C API, run via Lib/test/test_capi.py, and\r
- implemented by module Modules/_testcapimodule.c\r
pyexpat\r
- Python wrapper for accelerated XML parsing, which incorporates stable\r
- code from the Expat project: http://sourceforge.net/projects/expat/\r
select\r
- selectmodule.c\r
unicodedata\r
- large tables of Unicode data\r
winsound\r
- play sounds (typically .wav files) under Windows\r
\r
-Python-controlled subprojects that wrap external projects:\r
+There is also a w9xpopen project to build w9xpopen.exe, which is used\r
+for platform.popen() on platforms whose COMSPEC points to 'command.com'.\r
+\r
+The following Python-controlled sub-projects wrap external projects.\r
+Note that these external libraries are not necessary for a working\r
+interpreter, but they do implement several major features. See the\r
+"Getting External Sources" section below for additional information\r
+about getting the source for building these libraries. The sub-projects\r
+are:\r
_bsddb\r
- Wraps Berkeley DB 4.7.25, which is currently built by _bsddb.vcproj.\r
- project.\r
+ Python wrapper for Berkeley DB version 4.7.25.\r
+ Homepage:\r
+ http://www.oracle.com/us/products/database/berkeley-db/\r
+_bz2\r
+ Python wrapper for version 1.0.6 of the libbzip2 compression library\r
+ Homepage:\r
+ http://www.bzip.org/\r
+_ssl\r
+ Python wrapper for version 1.0.2d of the OpenSSL secure sockets\r
+ library, which is built by ssl.vcxproj\r
+ Homepage:\r
+ http://www.openssl.org/\r
+\r
+ Building OpenSSL requires nasm.exe (the Netwide Assembler), version\r
+ 2.10 or newer from\r
+ http://www.nasm.us/\r
+ to be somewhere on your PATH. More recent versions of OpenSSL may\r
+ need a later version of NASM. If OpenSSL's self tests don't pass,\r
+ you should first try to update NASM and do a full rebuild of\r
+ OpenSSL. If you use the PCbuild\get_externals.bat method\r
+ for getting sources, it also downloads a version of NASM which the\r
+ libeay/ssleay sub-projects use.\r
+\r
+ The libeay/ssleay sub-projects expect your OpenSSL sources to have\r
+ already been configured and be ready to build. If you get your sources\r
+ from svn.python.org as suggested in the "Getting External Sources"\r
+ section below, the OpenSSL source will already be ready to go. If\r
+ you want to build a different version, you will need to run\r
+\r
+ PCbuild\prepare_ssl.py path\to\openssl-source-dir\r
+\r
+ That script will prepare your OpenSSL sources in the same way that\r
+ those available on svn.python.org have been prepared. Note that\r
+ Perl must be installed and available on your PATH to configure\r
+ OpenSSL. ActivePerl is recommended and is available from\r
+ http://www.activestate.com/activeperl/\r
+\r
+ The libeay and ssleay sub-projects will build the modules of OpenSSL\r
+ required by _ssl and _hashlib and may need to be manually updated when\r
+ upgrading to a newer version of OpenSSL or when adding new\r
+ functionality to _ssl or _hashlib. They will not clean up their output\r
+ with the normal Clean target; CleanAll should be used instead.\r
_sqlite3\r
- Wraps SQLite 3.6.21, which is currently built by sqlite3.vcproj.\r
+ Wraps SQLite 3.6.21, which is itself built by sqlite3.vcxproj\r
+ Homepage:\r
+ http://www.sqlite.org/\r
_tkinter\r
- Wraps the Tk windowing system. Unlike _bsddb and _sqlite3, there's no\r
- corresponding tcltk.vcproj-type project that builds Tcl/Tk from vcproj's\r
- within our pcbuild.sln, which means this module expects to find a\r
- pre-built Tcl/Tk in either ..\externals\tcltk for 32-bit or\r
- ..\externals\tcltk64 for 64-bit (relative to this directory). See below\r
- for instructions to build Tcl/Tk.\r
-bz2\r
- Python wrapper for the libbz2 compression library. Homepage\r
- http://sources.redhat.com/bzip2/\r
- Download the source from the python.org copy into the dist\r
- directory:\r
-\r
- svn export http://svn.python.org/projects/external/bzip2-1.0.6\r
-\r
- ** NOTE: if you use the PCbuild\get_externals.bat approach for\r
- obtaining external sources then you don't need to manually get the source\r
- above via subversion. **\r
+ Wraps version 8.5.15 of the Tk windowing system.\r
+ Homepage:\r
+ http://www.tcl.tk/\r
\r
-_ssl\r
- Python wrapper for the secure sockets library.\r
+ Tkinter's dependencies are built by the tcl.vcxproj and tk.vcxproj\r
+ projects. The tix.vcxproj project also builds the Tix extended\r
+ widget set for use with Tkinter.\r
\r
- Get the source code through\r
+ Those three projects install their respective components in a\r
+ directory alongside the source directories called "tcltk" on\r
+ Win32 and "tcltk64" on x64. They also copy the Tcl and Tk DLLs\r
+ into the current output directory, which should ensure that Tkinter\r
+ is able to load Tcl/Tk without having to change your PATH.\r
\r
- svn export http://svn.python.org/projects/external/openssl-1.0.2d\r
+ The tcl, tk, and tix sub-projects do not clean their builds with\r
+ the normal Clean target; if you need to rebuild, you should use the\r
+ CleanAll target or manually delete their builds.\r
\r
- ** NOTE: if you use the PCbuild\get_externals.bat approach for\r
- obtaining external sources then you don't need to manually get the source\r
- above via subversion. **\r
\r
- The NASM assembler is required to build OpenSSL. If you use the\r
- PCbuild\get_externals.bat script to get external library sources, it also\r
- downloads a version of NASM, which the ssl build script will add to PATH.\r
- Otherwise, you can download the NASM installer from\r
- http://www.nasm.us/\r
- and add NASM to your PATH.\r
+Getting External Sources\r
+------------------------\r
+\r
+The last category of sub-projects listed above wrap external projects\r
+Python doesn't control, and as such a little more work is required in\r
+order to download the relevant source files for each project before they\r
+can be built. However, a simple script is provided to make this as\r
+painless as possible, called "get_externals.bat" and located in this\r
+directory. This script extracts all the external sub-projects from\r
+ http://svn.python.org/projects/external\r
+via Subversion (so you'll need svn.exe on your PATH) and places them\r
+in ..\externals (relative to this directory).\r
+\r
+It is also possible to download sources from each project's homepage,\r
+though you may have to change folder names or pass the names to MSBuild\r
+as the values of certain properties in order for the build solution to\r
+find them. This is an advanced topic and not necessarily fully\r
+supported.\r
+\r
+The get_externals.bat script is called automatically by build.bat when\r
+you pass the '-e' option to it.\r
\r
- You can also install ActivePerl from\r
- http://www.activestate.com/activeperl/\r
- if you like to use the official sources instead of the files from\r
- python's subversion repository. The svn version contains pre-build\r
- makefiles and assembly files.\r
-\r
- The build process makes sure that no patented algorithms are included.\r
- For now RC5, MDC2 and IDEA are excluded from the build. You may have\r
- to manually remove $(OBJ_D)\i_*.obj from ms\nt.mak if the build process\r
- complains about missing files or forbidden IDEA. Again the files provided\r
- in the subversion repository are already fixed.\r
-\r
- The MSVC project simply invokes PCBuild/build_ssl.py to perform\r
- the build. This Python script locates and builds your OpenSSL\r
- installation, then invokes a simple makefile to build the final .pyd.\r
-\r
- build_ssl.py attempts to catch the most common errors (such as not\r
- being able to find OpenSSL sources, or not being able to find a Perl\r
- that works with OpenSSL) and give a reasonable error message.\r
- If you have a problem that doesn't seem to be handled correctly\r
- (eg, you know you have ActivePerl but we can't find it), please take\r
- a peek at build_ssl.py and suggest patches. Note that build_ssl.py\r
- should be able to be run directly from the command-line.\r
-\r
- build_ssl.py/MSVC isn't clever enough to clean OpenSSL - you must do\r
- this by hand.\r
-\r
-The subprojects above wrap external projects Python doesn't control, and as\r
-such, a little more work is required in order to download the relevant source\r
-files for each project before they can be built. The easiest way to do this\r
-is to use the `build.bat` script in this directory to build Python, and pass\r
-the '-e' switch to tell it to use get_externals.bat to fetch external sources\r
-and build Tcl/Tk and Tix. To use get_externals.bat, you'll need to have\r
-Subversion installed and svn.exe on your PATH. The script will fetch external\r
-library sources from http://svn.python.org/external and place them in\r
-..\externals (relative to this directory).\r
-\r
-Building for Itanium\r
---------------------\r
-\r
-Official support for Itanium builds have been dropped from the build. Please\r
-contact us and provide patches if you are interested in Itanium builds.\r
-\r
-Building for AMD64\r
-------------------\r
-\r
-The build process for AMD64 / x64 is very similar to standard builds. You just\r
-have to set x64 as platform. In addition, the HOST_PYTHON environment variable\r
-must point to a Python interpreter (at least 2.4), to support cross-compilation.\r
-\r
-Building Python Using the free MS Toolkit Compiler\r
---------------------------------------------------\r
-\r
-Microsoft has withdrawn the free MS Toolkit Compiler, so this can no longer\r
-be considered a supported option. Instead you can use the free VS C++ Express\r
-Edition.\r
\r
Profile Guided Optimization\r
---------------------------\r
\r
The solution has two configurations for PGO. The PGInstrument\r
-configuration must be build first. The PGInstrument binaries are\r
-linked against a profiling library and contain extra debug\r
-information. The PGUpdate configuration takes the profiling data and\r
-generates optimized binaries.\r
+configuration must be built first. The PGInstrument binaries are linked\r
+against a profiling library and contain extra debug information. The\r
+PGUpdate configuration takes the profiling data and generates optimized\r
+binaries.\r
\r
-The build_pgo.bat script automates the creation of optimized binaries. It\r
-creates the PGI files, runs the unit test suite or PyBench with the PGI\r
-python and finally creates the optimized files.\r
+The build_pgo.bat script automates the creation of optimized binaries.\r
+It creates the PGI files, runs the unit test suite or PyBench with the\r
+PGI python, and finally creates the optimized files.\r
+\r
+See\r
+ http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx\r
+for more on this topic.\r
\r
-http://msdn.microsoft.com/en-us/library/e7k32f4k(VS.90).aspx\r
\r
Static library\r
--------------\r
\r
-The solution has no configuration for static libraries. However it is easy\r
-it build a static library instead of a DLL. You simply have to set the\r
-"Configuration Type" to "Static Library (.lib)" and alter the preprocessor\r
-macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may also have to\r
-change the "Runtime Library" from "Multi-threaded DLL (/MD)" to\r
-"Multi-threaded (/MT)".\r
+The solution has no configuration for static libraries. However it is\r
+easy to build a static library instead of a DLL. You simply have to set\r
+the "Configuration Type" to "Static Library (.lib)" and alter the\r
+preprocessor macro "Py_ENABLE_SHARED" to "Py_NO_ENABLE_SHARED". You may\r
+also have to change the "Runtime Library" from "Multi-threaded DLL\r
+(/MD)" to "Multi-threaded (/MT)".\r
+\r
\r
Visual Studio properties\r
------------------------\r
\r
-The PCbuild solution makes heavy use of Visual Studio property files\r
-(*.vsprops). The properties can be viewed and altered in the Property\r
-Manager (View -> Other Windows -> Property Manager).\r
-\r
- * debug (debug macro: _DEBUG)\r
- * pginstrument (PGO)\r
- * pgupdate (PGO)\r
- +-- pginstrument\r
- * pyd (python extension, release build)\r
- +-- release\r
- +-- pyproject\r
- * pyd_d (python extension, debug build)\r
- +-- debug\r
- +-- pyproject\r
- * pyproject (base settings for all projects, user macros like PyDllName)\r
- * release (release macro: NDEBUG)\r
- * x64 (AMD64 / x64 platform specific settings)\r
-\r
-The pyproject propertyfile defines _WIN32 and x64 defines _WIN64 and _M_X64\r
-although the macros are set by the compiler, too. The GUI doesn't always know\r
-about the macros and confuse the user with false information.\r
-\r
-YOUR OWN EXTENSION DLLs\r
+The PCbuild solution makes use of Visual Studio property files (*.props)\r
+to simplify each project. The properties can be viewed in the Property\r
+Manager (View -> Other Windows -> Property Manager) but should be\r
+carefully modified by hand.\r
+\r
+The property files used are:\r
+ * python (versions, directories and build names)\r
+ * pyproject (base settings for all projects)\r
+ * openssl (used by libeay and ssleay projects)\r
+ * tcltk (used by _tkinter, tcl, tk and tix projects)\r
+\r
+The pyproject property file defines all of the build settings for each\r
+project, with some projects overriding certain specific values. The GUI\r
+doesn't always reflect the correct settings and may confuse the user\r
+with false information, especially for settings that automatically adapt\r
+for diffirent configurations.\r
+\r
+\r
+Your Own Extension DLLs\r
-----------------------\r
\r
-If you want to create your own extension module DLL, there's an example\r
-with easy-to-follow instructions in ../PC/example/; read the file\r
-readme.txt there first.\r
+If you want to create your own extension module DLL (.pyd), there's an\r
+example with easy-to-follow instructions in ..\PC\example_nt\; read the\r
+file readme.txt there first.\r
projects / thirdparty / Python / cpython.git / commitdiff
