From 8071acbc330759569388636f9ac027ed627fde2a Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:45:31 -0500 Subject: [PATCH 01/15] Rename README.txt to README.rst --- Doc/{README.txt => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Doc/{README.txt => README.rst} (100%) diff --git a/Doc/README.txt b/Doc/README.rst similarity index 100% rename from Doc/README.txt rename to Doc/README.rst From d9c256342a5a56ebe44ba88ad9f5a94ae5b546c8 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:47:01 -0500 Subject: [PATCH 02/15] Rename README to README.rst --- Mac/{README => README.rst} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename Mac/{README => README.rst} (99%) diff --git a/Mac/README b/Mac/README.rst similarity index 99% rename from Mac/README rename to Mac/README.rst index 07f09fa8366528..18e760c4ee5984 100644 --- a/Mac/README +++ b/Mac/README.rst @@ -355,4 +355,4 @@ Resources * http://www.python.org/community/sigs/current/pythonmac-sig/ - * http://docs.python.org/devguide/ \ No newline at end of file + * http://docs.python.org/devguide/ From 14be2f129e1ffe4937444425731115a370b78908 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:47:31 -0500 Subject: [PATCH 03/15] Rename README to README.rst --- Misc/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Misc/{README => README.rst} (100%) diff --git a/Misc/README b/Misc/README.rst similarity index 100% rename from Misc/README rename to Misc/README.rst From ec51512a58075b10c92273519a2101288724559e Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:48:20 -0500 Subject: [PATCH 04/15] Rename README to README.rst --- Modules/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Modules/{README => README.rst} (100%) diff --git a/Modules/README b/Modules/README.rst similarity index 100% rename from Modules/README rename to Modules/README.rst From 13b7241e4df0c5fc1b5899590e826202f65607dc Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:48:47 -0500 Subject: [PATCH 05/15] Rename README to README.rst --- Objects/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Objects/{README => README.rst} (100%) diff --git a/Objects/README b/Objects/README.rst similarity index 100% rename from Objects/README rename to Objects/README.rst From 3356de730baa4485e22f6e27036253beddb7662b Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:49:21 -0500 Subject: [PATCH 06/15] Rename readme.txt to readme.rst --- PC/{readme.txt => readme.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename PC/{readme.txt => readme.rst} (100%) diff --git a/PC/readme.txt b/PC/readme.rst similarity index 100% rename from PC/readme.txt rename to PC/readme.rst From d86a6d5b3b148fa8a476ce2dfdcf08af5ef395a7 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:49:46 -0500 Subject: [PATCH 07/15] Rename readme.txt to readme.rst --- PCbuild/{readme.txt => readme.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename PCbuild/{readme.txt => readme.rst} (100%) diff --git a/PCbuild/readme.txt b/PCbuild/readme.rst similarity index 100% rename from PCbuild/readme.txt rename to PCbuild/readme.rst From 56150b52e61ef57a3e792d855e0ce8ff2e17c179 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:50:12 -0500 Subject: [PATCH 08/15] Rename README to README.rst --- Programs/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Programs/{README => README.rst} (100%) diff --git a/Programs/README b/Programs/README.rst similarity index 100% rename from Programs/README rename to Programs/README.rst From 8c2ad0da18bf12f2281c548c46429787b7b08e76 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:50:33 -0500 Subject: [PATCH 09/15] Rename README to README.rst --- Python/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Python/{README => README.rst} (100%) diff --git a/Python/README b/Python/README.rst similarity index 100% rename from Python/README rename to Python/README.rst From 14d769e15612a5e3fb33dde77e105583a6ded4dc Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:50:55 -0500 Subject: [PATCH 10/15] Rename README to README.rst --- Tools/{README => README.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Tools/{README => README.rst} (100%) diff --git a/Tools/README b/Tools/README.rst similarity index 100% rename from Tools/README rename to Tools/README.rst From c0d7ad0e503ac9257effd22d44fa5f65b68cf004 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 20:59:16 -0500 Subject: [PATCH 11/15] Update README.rst --- Tools/README.rst | 67 +++++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 26 deletions(-) diff --git a/Tools/README.rst b/Tools/README.rst index 73ce6a7eee01f6..c67d6e21a805e5 100644 --- a/Tools/README.rst +++ b/Tools/README.rst @@ -1,46 +1,61 @@ This directory contains a number of Python programs that are useful while building or extending Python. -buildbot Batchfiles for running on Windows buildslaves. +buildbot + Batchfiles for running on Windows buildslaves. -ccbench A Python threads-based concurrency benchmark. (*) +ccbench + A Python threads-based concurrency benchmark. (*) -demo Several Python programming demos. +demo + Several Python programming demos. -freeze Create a stand-alone executable from a Python program. +freeze + Create a stand-alone executable from a Python program. -gdb Python code to be run inside gdb, to make it easier to - debug Python itself (by David Malcolm). +gdb + Python code to be run inside gdb, to make it easier to + debug Python itself (by David Malcolm). -i18n Tools for internationalization. pygettext.py - parses Python source code and generates .pot files, - and msgfmt.py generates a binary message catalog - from a catalog in text format. +i18n + Tools for internationalization. pygettext.py + parses Python source code and generates .pot files, + and msgfmt.py generates a binary message catalog + from a catalog in text format. -iobench Benchmark for the new Python I/O system. (*) +iobench + Benchmark for the new Python I/O system. (*) -msi Support for packaging Python as an MSI package on Windows. +msi + Support for packaging Python as an MSI package on Windows. -parser Un-parsing tool to generate code from an AST. +parser + Un-parsing tool to generate code from an AST. -pynche A Tkinter-based color editor. +pynche + A Tkinter-based color editor. -scripts A number of useful single-file programs, e.g. tabnanny.py - by Tim Peters, which checks for inconsistent mixing of - tabs and spaces, and 2to3, which converts Python 2 code - to Python 3 code. +scripts + A number of useful single-file programs, e.g. tabnanny.py + by Tim Peters, which checks for inconsistent mixing of + tabs and spaces, and 2to3, which converts Python 2 code + to Python 3 code. -stringbench A suite of micro-benchmarks for various operations on - strings (both 8-bit and unicode). (*) +stringbench + A suite of micro-benchmarks for various operations on + strings (both 8-bit and unicode). (*) -test2to3 A demonstration of how to use 2to3 transparently in setup.py. +test2to3 + A demonstration of how to use 2to3 transparently in setup.py. -unicode Tools for generating unicodedata and codecs from unicode.org - and other mapping files (by Fredrik Lundh, Marc-Andre Lemburg - and Martin von Loewis). +unicode + Tools for generating unicodedata and codecs from unicode.org + and other mapping files (by Fredrik Lundh, Marc-Andre Lemburg + and Martin von Loewis). -unittestgui A Tkinter based GUI test runner for unittest, with test - discovery. +unittestgui + A Tkinter based GUI test runner for unittest, with test + discovery. (*) A generic benchmark suite is maintained separately at http://hg.python.org/benchmarks/ From 3af48ee1051d9acac4e8728b5a41ed38c620a7ea Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 22:09:49 -0500 Subject: [PATCH 12/15] Update file table so it renders properly. --- Misc/README.rst | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Misc/README.rst b/Misc/README.rst index ddb8f3f975904a..b62405ff2261aa 100644 --- a/Misc/README.rst +++ b/Misc/README.rst @@ -6,22 +6,23 @@ documents are only of historic importance. Files found here ---------------- - -ACKS Acknowledgements -gdbinit Handy stuff to put in your .gdbinit file, if you use gdb -HISTORY News from previous releases -- oldest last -indent.pro GNU indent profile approximating my C style -NEWS News for this release (for some meaning of "this") -Porting Mini-FAQ on porting to new platforms -python-config.in Python script template for python-config -python.man UNIX man page for the python interpreter -python.pc.in Package configuration info template for pkg-config -python-wing*.wpr Wing IDE project file -README The file you're reading now -README.AIX Information about using Python on AIX -README.coverity Information about running Coverity's Prevent on Python -README.valgrind Information for Valgrind users, see valgrind-python.supp -SpecialBuilds.txt Describes extra symbols you can set for debug builds -svnmap.txt Map of old SVN revs and branches to hg changeset ids -valgrind-python.supp Valgrind suppression file, see README.valgrind -vgrindefs Python configuration for vgrind (a generic pretty printer) +==================== ========================================================== +ACKS Acknowledgements +gdbinit Handy stuff to put in your .gdbinit file, if you use gdb +HISTORY News from previous releases -- oldest last +indent.pro GNU indent profile approximating my C style +NEWS News for this release (for some meaning of "this") +Porting Mini-FAQ on porting to new platforms +python-config.in Python script template for python-config +python.man UNIX man page for the python interpreter +python.pc.in Package configuration info template for pkg-config +python-wing*.wpr Wing IDE project file +README The file you're reading now +README.AIX Information about using Python on AIX +README.coverity Information about running Coverity's Prevent on Python +README.valgrind Information for Valgrind users, see valgrind-python.supp +SpecialBuilds.txt Describes extra symbols you can set for debug builds +svnmap.txt Map of old SVN revs and branches to hg changeset ids +valgrind-python.supp Valgrind suppression file, see README.valgrind +vgrindefs Python configuration for vgrind (a generic pretty printer) +==================== ========================================================== From 615facf39078a4fed42374f7d904888322b1b1f8 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 22:16:37 -0500 Subject: [PATCH 13/15] Update .rst formatting --- PC/readme.rst | 56 ++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/PC/readme.rst b/PC/readme.rst index 0a96d269b0977d..e5adfc64d79d42 100644 --- a/PC/readme.rst +++ b/PC/readme.rst @@ -16,23 +16,23 @@ path, start Python and enter "import sys" and "print sys.path". All PC ports use this scheme to try to set up a module search path: - 1) The script location; the current directory without script. - 2) The PYTHONPATH variable, if set. - 3) For Win32 platforms (NT/95), paths specified in the Registry. - 4) Default directories lib, lib/win, lib/test, lib/tkinter; - these are searched relative to the environment variable - PYTHONHOME, if set, or relative to the executable and its - ancestors, if a landmark file (Lib/string.py) is found , - or the current directory (not useful). - 5) The directory containing the executable. +1. The script location; the current directory without script. +2. The PYTHONPATH variable, if set. +3. For Win32 platforms (NT/95), paths specified in the Registry. +4. Default directories lib, lib/win, lib/test, lib/tkinter; +these are searched relative to the environment variable +PYTHONHOME, if set, or relative to the executable and its +ancestors, if a landmark file (Lib/string.py) is found , +or the current directory (not useful). +5. The directory containing the executable. The best installation strategy is to put the Python executable (and DLL, for Win32 platforms) in some convenient directory such as C:/python, and copy all library files and subdirectories (using XCOPY) to C:/python/lib. Then you don't need to set PYTHONPATH. Otherwise, set the environment variable PYTHONPATH to your Python search path. -For example, - set PYTHONPATH=.;d:\python\lib;d:\python\lib\win;d:\python\lib\dos-8x3 +For example:: + set PYTHONPATH=.;d:\python\lib;d:\python\lib\win;d:\python\lib\dos-8x3 There are several add-in modules to build Python programs which use the native Windows operating environment. The ports here just make @@ -45,31 +45,37 @@ To make a Python port, start the Integrated Development Environment (or makefile) provided. This will enable you to change any source files or build settings so you can make custom builds. -pyconfig.h An important configuration file specific to PC's. +pyconfig.h + An important configuration file specific to PC's. -config.c The list of C modules to include in the Python PC - version. Manually edit this file to add or - remove Python modules. +config.c + The list of C modules to include in the Python PC + version. Manually edit this file to add or + remove Python modules. -testpy.py A Python test program. Run this to test your - Python port. It should produce copious output, - ending in a report on how many tests were OK, how many - failed, and how many were skipped. Don't worry about - skipped tests (these test unavailable optional features). +testpy.py + A Python test program. Run this to test your + Python port. It should produce copious output, + ending in a report on how many tests were OK, how many + failed, and how many were skipped. Don't worry about + skipped tests (these test unavailable optional features). Additional files and subdirectories for 32-bit Windows ====================================================== -python_nt.rc Resource compiler input for python15.dll. +python_nt.rc + Resource compiler input for python15.dll. dl_nt.c - Additional sources used for 32-bit Windows features. + Additional sources used for 32-bit Windows features. -getpathp.c Default sys.path calculations (for all PC platforms). +getpathp.c + Default sys.path calculations (for all PC platforms). -dllbase_nt.txt A (manually maintained) list of base addresses for - various DLLs, to avoid run-time relocation. +dllbase_nt.txt + A (manually maintained) list of base addresses for + various DLLs, to avoid run-time relocation. Note for Windows 3.x and DOS users From 9122fa27a4aeb9cb80d053ad58de2eb5e8e5bf62 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 23:21:47 -0500 Subject: [PATCH 14/15] Update README with .rst formatting --- PCbuild/readme.rst | 145 +++++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 70 deletions(-) diff --git a/PCbuild/readme.rst b/PCbuild/readme.rst index 00b50be0175565..0e277615f22841 100644 --- a/PCbuild/readme.rst +++ b/PCbuild/readme.rst @@ -2,9 +2,9 @@ Quick Start Guide ----------------- 1. Install Microsoft Visual Studio 2015, any edition. -2. Install Subversion, and make sure 'svn.exe' is on your PATH. -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". +2. Install Subversion, and make sure ``svn.exe`` is on your PATH. +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 Microsoft Visual C++ @@ -16,8 +16,7 @@ bit platforms. Using this directory requires an installation of Microsoft Visual C++ 2015 (MSVC 14.0) of any edition. The specific requirements are as follows: -Visual Studio Express 2015 for Desktop -Visual Studio Professional 2015 +Visual Studio Professional 2015 / Visual Studio Express 2015 for Desktop Either edition is sufficient for building all configurations except for Profile Guided Optimization. The Python build solution pcbuild.sln makes use of Solution Folders, @@ -25,15 +24,16 @@ Visual Studio Professional 2015 or reloaded by Visual Studio, a warning about Solution Folders will be displayed, which can be safely dismissed with no impact on your ability to build Python. - Required for building 64-bit Debug and Release configuration builds + Required for building 64-bit Debug and Release configuration builds. + Visual Studio Premium 2015 Required for building Release configuration builds that make use of Profile Guided Optimization (PGO), on either platform. -All you need to do to build is open the solution "pcbuild.sln" in Visual +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 +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. @@ -44,14 +44,16 @@ win32 sub-directory. The x64 platform is used for building 64-bit AMD64 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 + to using ``./configure --with-pydebug`` on UNIX. All binaries built using this configuration have "_d" added to their name: - python37_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 + ``python37_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 Premium Edition of Visual Studio. See the "Profile @@ -59,6 +61,7 @@ PGInstrument, PGUpdate 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. @@ -73,7 +76,7 @@ script to detect one of Visual Studio 2015, 2013, 2012, or 2010, any of which may be used to build Python, though only Visual Studio 2015 is officially supported. -By default, build.bat will build Python in Release configuration for +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. @@ -94,48 +97,58 @@ 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 +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: +you'll have a very limited but usable ``python.exe``:: + pythoncore - .dll and .lib + ``.dll`` and ``.lib`` + python - .exe + ``.exe`` These sub-projects provide extra executables that are useful for running -CPython in different ways: +CPython in different ways:: + pythonw - pythonw.exe, a variant of python.exe that doesn't open a Command + ``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 + ``py.exe``, the Python Launcher for Windows, see + ``_ + pywlauncher - pyw.exe, a variant of py.exe that doesn't open a Command Prompt + ``pyw.exe``, a variant of py.exe that doesn't open a Command Prompt window + _testembed - _testembed.exe, a small program that embeds Python for testing - purposes, used by test_capi.py + ``_testembed.exe``, a small program that embeds Python for testing + purposes, used by ``test_capi.py`` These are miscellaneous sub-projects that don't really fit the other -categories: +categories:: + _freeze_importlib _freeze_importlib.exe, used to regenerate Python\importlib.h after changes have been made to Lib\importlib\_bootstrap.py + python3dll python3.dll, the PEP 384 Stable ABI dll + xxlimited builds an example module that makes use of the PEP 384 Stable ABI, see Modules\xxlimited.c 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: +.pyd) of the same name as the project:: + _ctypes _ctypes_test _decimal @@ -158,37 +171,32 @@ 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: -_bz2 - Python wrapper for version 1.0.6 of the libbzip2 compression library - Homepage: - http://www.bzip.org/ -_lzma +are:: + +`_bz2 `_ + Python wrapper for version 1.0.6 of the libbzip2 compression library. + +`_lzma `_ Python wrapper for the liblzma compression library, using pre-built - binaries of XZ Utils version 5.0.5 - Homepage: - http://tukaani.org/xz/ -_ssl + binaries of XZ Utils version 5.0.5. + +`_ssl `_ Python wrapper for version 1.0.2j of the OpenSSL secure sockets - library, which is built by ssl.vcxproj - Homepage: - http://www.openssl.org/ - + library, which is built by ssl.vcxproj. + 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. + 2.10 or newer from ``_ 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 + you want to build a different version, you will need to run:: PCbuild\prepare_ssl.py path\to\openssl-source-dir @@ -196,29 +204,27 @@ _ssl 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.14.2.0, which is itself built by sqlite3.vcxproj - Homepage: - http://www.sqlite.org/ -_tkinter + +`_sqlite3 `_ + Wraps SQLite 3.14.2.0, which is itself built by sqlite3.vcxproj. + +`_tkinter `_ Wraps version 8.6.6 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 + 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 + 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. @@ -234,11 +240,11 @@ 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 +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). +``_ via Subversion (so you'll +need svn.exe on your PATH) and places them 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 @@ -246,8 +252,8 @@ 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. +The ``get_externals.bat`` script is called automatically by ``build.bat`` when +you pass the ``-e`` option to it. Profile Guided Optimization @@ -263,8 +269,7 @@ 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.140).aspx +See ``_ for more on this topic. @@ -274,7 +279,7 @@ 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 +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)". From e3e0d5f1c1c85cc998ee71dedde25650d50c4044 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Feb 2017 23:45:34 -0500 Subject: [PATCH 15/15] Update README with proper .rst formatting. --- PCbuild/readme.rst | 72 ++++++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/PCbuild/readme.rst b/PCbuild/readme.rst index 0e277615f22841..48e61020dda867 100644 --- a/PCbuild/readme.rst +++ b/PCbuild/readme.rst @@ -104,7 +104,7 @@ 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``:: +you'll have a very limited but usable ``python.exe``: pythoncore ``.dll`` and ``.lib`` @@ -113,73 +113,75 @@ python ``.exe`` These sub-projects provide extra executables that are useful for running -CPython in different ways:: +CPython in different ways: pythonw ``pythonw.exe``, a variant of python.exe that doesn't open a Command - Prompt window + Prompt window. pylauncher ``py.exe``, the Python Launcher for Windows, see - ``_ + ``_. pywlauncher ``pyw.exe``, a variant of py.exe that doesn't open a Command Prompt - window + window. _testembed ``_testembed.exe``, a small program that embeds Python for testing - purposes, used by ``test_capi.py`` + purposes, used by ``test_capi.py``. + These are miscellaneous sub-projects that don't really fit the other -categories:: +categories: _freeze_importlib - _freeze_importlib.exe, used to regenerate Python\importlib.h after - changes have been made to Lib\importlib\_bootstrap.py + ``_freeze_importlib.exe``, used to regenerate Python\importlib.h after + changes have been made to ``Lib\importlib\_bootstrap.py``. python3dll - python3.dll, the PEP 384 Stable ABI dll + ``python3.dll``, the PEP 384 Stable ABI dll. xxlimited builds an example module that makes use of the PEP 384 Stable ABI, - see Modules\xxlimited.c + see ``Modules\xxlimited.c``. + 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 -_decimal -_elementtree -_hashlib -_msi -_multiprocessing -_overlapped -_socket -_testcapi -_testbuffer -_testimportmultiple -pyexpat -select -unicodedata -winsound + _ctypes + _ctypes_test + _decimal + _elementtree + _hashlib + _msi + _multiprocessing + _overlapped + _socket + _testcapi + _testbuffer + _testimportmultiple + pyexpat + select + unicodedata + winsound 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 +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:: +about getting the source for building these libraries. The sub-projects +are: `_bz2 `_ Python wrapper for version 1.0.6 of the libbzip2 compression library. - + `_lzma `_ Python wrapper for the liblzma compression library, using pre-built binaries of XZ Utils version 5.0.5. - + `_ssl `_ Python wrapper for version 1.0.2j of the OpenSSL secure sockets library, which is built by ssl.vcxproj. @@ -211,10 +213,12 @@ are:: 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.14.2.0, which is itself built by sqlite3.vcxproj. - + + `_tkinter `_ Wraps version 8.6.6 of the Tk windowing system.