From 4884ed5853e4f48a4ffab7dc28d42ec96f78f151 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 21 Nov 2022 18:11:19 -0600 Subject: [PATCH 1/4] Add -c Debug & note on changing build config/platform for Windows build --- getting-started/setup-building.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 646495601..2c4a315ff 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -269,10 +269,31 @@ are downloaded: .. code-block:: dosbatch - PCbuild\build.bat + PCbuild\build.bat -c Debug + +The above command line build uses the ``-c Debug`` argument +to build in the ``Debug`` configuration, +which enables checks and assertions helpful for developing Python. +By default, it builds in the ``Release`` configuration +and for the 64-bit ``x64`` platform rather than 32-bit ``Win32``; +use ``-c`` and ``-p`` to control build config and platform, respectively. + +After this build succeeds, you can open the ``PCbuild\pcbuild.sln`` solution +in the Visual Studio IDE to continue development, if you prefer. +When building in Visual Studio, +make sure to select build settings that match what you used with the script +(the :guilabel:`Debug` configuration and the :guilabel:`x64` platform) +from the dropdown menus in the toolbar. -After this build succeeds, you can open the ``PCbuild\pcbuild.sln`` solution in -Visual Studio to continue development. +.. note:: + + If you need to change the build configuration or platform, + build once with the ``build.bat`` script set to those options first + before building with them in VS to ensure all files are rebuilt properly, + or you may encouter errors when loading modules that were not rebuilt. + + Avoid selecting the ``PGInstrument`` and ``PGUpdate`` configurations, + as these are intended for PGO builds and not for normal development. See the `readme`_ for more details on what other software is necessary and how to build. From 57f959827738d9d820bd0ba59f09f42f49c19490 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 21 Nov 2022 18:20:03 -0600 Subject: [PATCH 2/4] Use Sphinx syntax and links w/descriptive titles in section --- getting-started/setup-building.rst | 56 +++++++++++++++++------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 2c4a315ff..cd524b340 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -245,29 +245,31 @@ still build properly). Windows ------- -For a quick guide to building you can read `this documentation`_ from Victor -Stinner. +For a concise step by step summary of building Python on Windows, +you can read `Victor Stinner's guide`_. -All current versions of Python can be built using Microsoft Visual Studio 2017 -or later. You can download -and use any of the free or paid versions of `Visual Studio 2017`_. +All supported versions of Python can be built +using Microsoft Visual Studio 2017 or later. +You can download and use any of the free or paid versions of `Visual Studio`_. -When installing Visual Studio 2017, select the **Python development** workload -and the optional **Python native development tools** component to obtain all of -the necessary build tools. If you do not already have git installed, you can -find git for Windows on the **Individual components** tab of the installer. +When installing it, select the :guilabel:`Python development` workload +and the optional :guilabel:`Python native development tools` component +to obtain all of the necessary build tools. +You can find Git for Windows on the :guilabel:`Individual components` tab +if you don't already have it installed. .. note:: If you want to build MSI installers, be aware that the build toolchain - for them has a dependency on the Microsoft .NET Framework Version 3.5 (which - may not be configured on recent versions of Windows, such as Windows 10). If - you are building on a recent Windows version, use the Control Panel (Programs - | Programs and Features | Turn Windows Features on or off) and ensure that the - entry ".NET Framework 3.5 (includes .NET 2.0 and 3.0)" is enabled. + for them has a dependency on the Microsoft .NET Framework Version 3.5 + (which may not be included on recent versions of Windows, such as Windows 10). + If you are building on a recent Windows version, use the Control Panel + (:menuselection:`Programs --> Programs and Features --> Turn Windows Features on or off`) + and ensure that the entry + :guilabel:`.NET Framework 3.5 (includes .NET 2.0 and 3.0)` is enabled. Your first build should use the command line to ensure any external dependencies are downloaded: -.. code-block:: dosbatch +.. code-block:: batch PCbuild\build.bat -c Debug @@ -295,18 +297,22 @@ from the dropdown menus in the toolbar. Avoid selecting the ``PGInstrument`` and ``PGUpdate`` configurations, as these are intended for PGO builds and not for normal development. -See the `readme`_ for more details on what other software is necessary and how -to build. +See the `PCBuild readme`_ for more details on what other software is necessary +and how to build. -.. note:: If you are using the Windows Subsystem for Linux (WSL), clone the - repository from a native Windows terminal program like cmd.exe command prompt - or PowerShell as well as use a build of git targeted for Windows, e.g., the - official one from ``_. Otherwise, Visual Studio will - not be able to find all the project's files and will fail the build. +.. note:: If you are using the Windows Subsystem for Linux (WSL), + :ref:`clone the repository ` from a native Windows shell program + like PowerShell or the ``cmd.exe`` command prompt, + and use a build of Git targeted for Windows, + e.g. the `Git for Windows download from the official Git website`_. + Otherwise, Visual Studio will not be able to find all the project's files + and will fail the build. + +.. _Victor Stinner's guide: https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html +.. _Visual Studio: https://visualstudio.microsoft.com/ +.. _PCBuild readme: https://github.com/python/cpython/blob/main/PCbuild/readme.txt +.. _Git for Windows download from the official Git website: https://git-scm.com/download/win -.. _this documentation: https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html -.. _Visual Studio 2017: https://visualstudio.microsoft.com/ -.. _readme: https://github.com/python/cpython/blob/main/PCbuild/readme.txt .. _build-dependencies: From c45525f519e12150ba68a5a7250f78b4e744c475 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 21 Nov 2022 18:23:13 -0600 Subject: [PATCH 3/4] Move WSL note to the top of the section where it is more easily noticed --- getting-started/setup-building.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index cd524b340..c563c663a 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -245,6 +245,14 @@ still build properly). Windows ------- +.. note:: If you are using the Windows Subsystem for Linux (WSL), + :ref:`clone the repository ` from a native Windows shell program + like PowerShell or the ``cmd.exe`` command prompt, + and use a build of Git targeted for Windows, + e.g. the `Git for Windows download from the official Git website`_. + Otherwise, Visual Studio will not be able to find all the project's files + and will fail the build. + For a concise step by step summary of building Python on Windows, you can read `Victor Stinner's guide`_. @@ -300,14 +308,6 @@ from the dropdown menus in the toolbar. See the `PCBuild readme`_ for more details on what other software is necessary and how to build. -.. note:: If you are using the Windows Subsystem for Linux (WSL), - :ref:`clone the repository ` from a native Windows shell program - like PowerShell or the ``cmd.exe`` command prompt, - and use a build of Git targeted for Windows, - e.g. the `Git for Windows download from the official Git website`_. - Otherwise, Visual Studio will not be able to find all the project's files - and will fail the build. - .. _Victor Stinner's guide: https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html .. _Visual Studio: https://visualstudio.microsoft.com/ .. _PCBuild readme: https://github.com/python/cpython/blob/main/PCbuild/readme.txt From 82ea4e9aa6cfaab5d6fb32a7b5d8efd9a8b0cea9 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 21 Nov 2022 18:49:30 -0600 Subject: [PATCH 4/4] Add a line explaining how to run the built Python on Windows --- getting-started/setup-building.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index c563c663a..cd0f47c22 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -305,6 +305,12 @@ from the dropdown menus in the toolbar. Avoid selecting the ``PGInstrument`` and ``PGUpdate`` configurations, as these are intended for PGO builds and not for normal development. +You can run the build of Python you've compiled with: + +.. code-block:: batch + + PCbuild\amd64\python_d.exe + See the `PCBuild readme`_ for more details on what other software is necessary and how to build.