Skip to content

Add a section about how to regenerate the ABI file #903

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 22, 2022
Merged

Add a section about how to regenerate the ABI file #903

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dd9e789
Add a section about how to regenerate the ABI file
pablogsal Jun 22, 2022
d17c5f6
Apply suggestions from code review
pablogsal Jun 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,51 @@ install your own copy of Autoconf.

.. _build_troubleshooting:

Regenerate the ABI dump
=======================

Maintainance 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 :ref:`release candidate <rc>` phase.

You can regenerate the ABI file by yourself by invoking the ``regen abidump``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

regen-abidump, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will fix this when I update the code block after we merge python/cpython#94135

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:

.. code-block:: bash
# In the CPython root:
$ docker run -v`pwd`:/src -it ubuntu:20.04 bash
$ cd /src
# Install dependencies to compile CPython
$ .github/workflows/posix-deps-apt.sh
# Install dependencies to run the ABI regeneration
$ apt-get install -yq abigail-tools python3
# Ensure CPython is built with all the debugging information
$ export CFLAGS="-g3 -O0"
# Build Python
$ ./configure --enable-shared && make
# Regenerate the ABI file
$ make regen-abidump
Comment on lines +505 to +518
Copy link
Member

@encukou encukou Jun 22, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a long script. Would you object to adding it to the source, and reducing the instructions to just e.g. docker run -v$(pwd):/src -w/src --rm ubuntu:20.04 bash /src/.github/workflows/regen-abidump.sh?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I think is a good idea. Will prepare a PR

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

python/cpython#94135


This will change the ``Doc/data/pythonX.Y.abi`` file with the latest changes
so it can be committed to the Pull Request and the check can pass.

Troubleshoot the build
======================

Expand Down