Important

This is part of a Draft of the Python Contributor’s Guide. Text in square brackets are notes about content to fill in. Currently, the devguide and this new Contributor’s Guide co-exist in the repo. We are using Sphinx include directives to demonstrate the re-organization. The final Contributor’s Guide will replace the devguide with content in only one place. We welcome help with this!

The [Plan for the Contributor’s Guide] page has more details about the current state of this draft and how you can help. See more info about the Contributor Guide in the discussion forum: Refactoring the DevGuide.

Regenerating auto-created files

Note

[These are two similar sections from the is the Setup and building section from the devguide.]

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. Python’s configure script is generated from configure.ac using GNU Autoconf.

After editing configure.ac, run make regen-configure to generate configure, pyconfig.h.in, and aclocal.m4. When submitting a pull request with changes made to configure.ac, make sure you also commit the changes in the generated files.

Python’s 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.

The recommended and by far the easiest way to regenerate configure is:

$ make regen-configure

This will use Podman or Docker to do the regeneration with the proper version of GNU Autoconf.

If you cannot (or don’t want to) use make regen-configure, install the autoconf-archive and pkg-config utilities, and make sure the pkg.m4 macro file located in the appropriate aclocal location:

$ ls $(aclocal --print-ac-dir) | grep pkg.m4

Note

Running autoreconf is not the same as running autoconf. For example, running autoconf by itself will not regenerate pyconfig.h.in. autoreconf runs autoconf and a number of other tools repeatedly as appropriate.

Regenerate the ABI dump

Maintenance branches (not main) have a special file located in Doc/data/pythonX.Y.abi that allows us to know if a given pull request affects the public ABI. This file is used by the GitHub CI in a check called Check if the ABI has changed that will fail if a given pull request has changes to the ABI and the ABI file is not updated.

This check acts as a fail-safe and doesn’t necessarily mean that the pull request cannot be merged. When this check fails you should add the relevant release manager to the PR so that they are aware of the change and they can validate if the change can be made or not.

Important

ABI changes are allowed before the first release candidate. After the first release candidate, all further releases must have the same ABI for ensuring compatibility with native extensions and other tools that interact with the Python interpreter. See the documentation about the release candidate phase.

When the PR check fails, the associated run will have the updated ABI file attached as an artifact. After release manager approval, you can download and add this file into your PR to pass the check.

You can regenerate the ABI file by yourself by invoking the regen abidump Make target. Note that for doing this you need to regenerate the ABI file in the same environment that the GitHub CI uses to check for it. This is because different platforms may include some platform-specific details that make the check fail even if the Python ABI is the same. The easier way to regenerate the ABI file using the same platform as the CI uses is by using Docker:

# In the CPython root:
$ docker run -v$(pwd):/src:Z -w /src --rm -it ubuntu:22.04 \
    bash /src/.github/workflows/regen-abidump.sh

Note that the ubuntu version used to execute the script matters and must match the version used by the CI to check the ABI. See the .github/workflows/build.yml file for more information.