From 5f2b49a93ed50dd295d131056b25c9d77389a4a4 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 8 Jun 2023 23:12:43 +0200 Subject: [PATCH 1/6] Rewrite 'Regenerating configure' --- getting-started/setup-building.rst | 52 +++++++++++++++++++----------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 993f3e40b..f610df1b2 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -483,31 +483,47 @@ Regenerate ``configure`` If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the -``configure`` script to test for availability of the functionality. +:file:`configure` script to test for availability of the functionality. +Python's :file:`configure` script is generated from :file:`configure.ac` +using GNU Autoconf. -Python's ``configure`` script is generated from ``configure.ac`` using Autoconf. -Instead of editing ``configure``, edit ``configure.ac`` and then run -``autoreconf`` to regenerate ``configure`` and a number of other files (such as -``pyconfig.h``). +After editing :file:`configure.ac`, run :program:`autoreconf` to regenerate +:file:`configure`, :file:`pyconfig.h.in`, and :file:`aclocal.m4`. +When submitting a patch with changes made to :file:`configure.ac`, +you must also those generated files. -When submitting a patch with changes made to ``configure.ac``, you should also -include the generated files. +The recommended and by far the easiest way to regenerate :file:`configure` is:: -Note that running ``autoreconf`` is not the same as running ``autoconf``. For -example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``. -``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is -appropriate. + $ make regen-configure -Python's ``configure.ac`` script typically requires a specific version of -Autoconf. At the moment, this reads: ``AC_PREREQ(2.69)``. It also requires -to have the ``autoconf-archive`` and ``pkg-config`` utilities installed in -the system and the ``pkg.m4`` macro file located in the appropriate ``alocal`` -location. You can easily check if this is correctly configured by running:: +This Make target will run a Podman or Docker container (depending on your +environment); you only need to commit the changes. +Behind the scenes this Make target runs one of the following container images:: + + $ podman run --rm --pull=always -v $(pwd):/src:Z quay.io/tiran/cpython_autoconf:271 + $ docker run --rm --pull=always -v $(pwd):/src quay.io/tiran/cpython_autoconf:271 + +Notice that the images are tagged with ``271``. +Python's :file:`configure.ac` script requires a specific version of +GNU Autoconf. +For Python 3.12 and newer, GNU Autoconf v2.71 is required. +For Python 3.11 and earlier, GNU Autoconf v2.69 is required. +For GNU Autoconf v2.69, change the ``:271`` tag to ``:269``. + +If you cannot, or don't want to use the ``cpython_autoconf`` containers, +install the :program:`autoconf-archive` and :program:`pkg-config` utilities, +and make sure the :file:`pkg.m4` macro file located in the appropriate +:program:`alocal` location:: $ ls $(aclocal --print-ac-dir) | grep pkg.m4 -If the system copy of Autoconf does not match this version, you will need to -install your own copy of Autoconf. +.. note:: + + Running :program:`autoreconf` is not the same as running :program:`autoconf`. + For example, running :program:`autoconf` by itself will not regenerate + :file:`pyconfig.h.in`. + :program:`autoreconf` runs :program:`autoconf` and a number of other tools + repeatedly as is appropriate. .. _build_troubleshooting: From 4ffc84d6aec5ae52ab0a1e0e197e770f1f474fe7 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 8 Jun 2023 23:19:46 +0200 Subject: [PATCH 2/6] Put more emphasis on the make target --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index f610df1b2..4c3d4dfa1 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -487,7 +487,7 @@ functionality (such as using a new system call), it is necessary to update the Python's :file:`configure` script is generated from :file:`configure.ac` using GNU Autoconf. -After editing :file:`configure.ac`, run :program:`autoreconf` to regenerate +After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :file:`pyconfig.h.in`, and :file:`aclocal.m4`. When submitting a patch with changes made to :file:`configure.ac`, you must also those generated files. From 887d7e8ea4bacc9893dbc155d0eeab68674b08f9 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 8 Jun 2023 23:28:45 +0200 Subject: [PATCH 3/6] Spelling Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 4c3d4dfa1..13611178d 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -490,7 +490,7 @@ using GNU Autoconf. After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :file:`pyconfig.h.in`, and :file:`aclocal.m4`. When submitting a patch with changes made to :file:`configure.ac`, -you must also those generated files. +you must also regenerate these files. The recommended and by far the easiest way to regenerate :file:`configure` is:: From 78f59f5b41e1b51a8c794dc3c633f1ad33aadbc4 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 8 Jun 2023 23:44:32 +0200 Subject: [PATCH 4/6] Address reviews: Use :cpy-file: role Put Docker and Podman commands in separate blocks Rewrite part about running the containers --- getting-started/setup-building.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 13611178d..0ca34e151 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -483,24 +483,30 @@ Regenerate ``configure`` If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the -:file:`configure` script to test for availability of the functionality. -Python's :file:`configure` script is generated from :file:`configure.ac` +:cpy-file:`configure` script to test for availability of the functionality. +Python's :file:`configure` script is generated from :cpy-file:`configure.ac` using GNU Autoconf. After editing :file:`configure.ac`, run ``make regen-configure`` to generate -:file:`configure`, :file:`pyconfig.h.in`, and :file:`aclocal.m4`. +:file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. When submitting a patch with changes made to :file:`configure.ac`, you must also regenerate these files. -The recommended and by far the easiest way to regenerate :file:`configure` is:: +The recommended and by far the easiest way to regenerate :file:`configure` is: + +.. code-block:: bash $ make regen-configure -This Make target will run a Podman or Docker container (depending on your -environment); you only need to commit the changes. -Behind the scenes this Make target runs one of the following container images:: +If you are regenerating :file:`configure` in a clean repo, +run one of the following containers instead: + +.. code-block:: bash $ podman run --rm --pull=always -v $(pwd):/src:Z quay.io/tiran/cpython_autoconf:271 + +.. code-block:: bash + $ docker run --rm --pull=always -v $(pwd):/src quay.io/tiran/cpython_autoconf:271 Notice that the images are tagged with ``271``. @@ -513,7 +519,9 @@ For GNU Autoconf v2.69, change the ``:271`` tag to ``:269``. If you cannot, or don't want to use the ``cpython_autoconf`` containers, install the :program:`autoconf-archive` and :program:`pkg-config` utilities, and make sure the :file:`pkg.m4` macro file located in the appropriate -:program:`alocal` location:: +:program:`alocal` location: + +.. code-block:: bash $ ls $(aclocal --print-ac-dir) | grep pkg.m4 From 4c65d6faf5b00f4b305ed62d8518e0a3d6e42f10 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 9 Jun 2023 00:04:42 +0200 Subject: [PATCH 5/6] make is slightly more explicit that generated files must be committed --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 0ca34e151..8463ae240 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -490,7 +490,7 @@ using GNU Autoconf. After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. When submitting a patch with changes made to :file:`configure.ac`, -you must also regenerate these files. +you must also include the changes in these generated files. The recommended and by far the easiest way to regenerate :file:`configure` is: From a4827a860593498465a137926ca8d82dbb18091e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 9 Jun 2023 08:48:19 +0200 Subject: [PATCH 6/6] Address CAM's review: - link to GNU Autoconf - use modern terminology: pull request iso. patch - formatting: use default code-blocks - fix weird phrasing - fix aclocal name - as appropriate, not as is appropriate --- getting-started/setup-building.rst | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 54b652aa5..4c2f5dac3 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -479,27 +479,23 @@ If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the :cpy-file:`configure` script to test for availability of the functionality. Python's :file:`configure` script is generated from :cpy-file:`configure.ac` -using GNU Autoconf. +using `GNU Autoconf `_. After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. -When submitting a patch with changes made to :file:`configure.ac`, -you must also include the changes in these generated files. +When submitting a pull request with changes made to :file:`configure.ac`, +make sure you also commit the changes in the generated files. -The recommended and by far the easiest way to regenerate :file:`configure` is: - -.. code-block:: bash +The recommended and by far the easiest way to regenerate :file:`configure` is:: $ make regen-configure If you are regenerating :file:`configure` in a clean repo, -run one of the following containers instead: - -.. code-block:: bash +run one of the following containers instead:: $ podman run --rm --pull=always -v $(pwd):/src:Z quay.io/tiran/cpython_autoconf:271 -.. code-block:: bash +:: $ docker run --rm --pull=always -v $(pwd):/src quay.io/tiran/cpython_autoconf:271 @@ -510,12 +506,10 @@ For Python 3.12 and newer, GNU Autoconf v2.71 is required. For Python 3.11 and earlier, GNU Autoconf v2.69 is required. For GNU Autoconf v2.69, change the ``:271`` tag to ``:269``. -If you cannot, or don't want to use the ``cpython_autoconf`` containers, +If you cannot (or don't want to) use the ``cpython_autoconf`` containers, install the :program:`autoconf-archive` and :program:`pkg-config` utilities, and make sure the :file:`pkg.m4` macro file located in the appropriate -:program:`alocal` location: - -.. code-block:: bash +:program:`aclocal` location:: $ ls $(aclocal --print-ac-dir) | grep pkg.m4 @@ -525,7 +519,7 @@ and make sure the :file:`pkg.m4` macro file located in the appropriate For example, running :program:`autoconf` by itself will not regenerate :file:`pyconfig.h.in`. :program:`autoreconf` runs :program:`autoconf` and a number of other tools - repeatedly as is appropriate. + repeatedly as appropriate. .. _build_troubleshooting: