Browse Source

migration: EAPI 8 migration

Signed-off-by: Michał Górny <>
Michał Górny 3 months ago
No known key found for this signature in database GPG Key ID: 639ADAE2329E240E
  1. 121


@ -40,3 +40,124 @@ The recommended rule of thumb for migrating old ebuilds is to:
This way, you can generally convert ebuilds using trial-and-error
.. index:: EAPI 8
Migrating from EAPI 7 to EAPI 8
EAPI 8 has banned everything that's been deprecated in EAPI 7, as well
as some other obsolete stuff. The following table lists all banned
things along with their suggested replacements.
| Deprecated thing | Replacement |
| Private eclass API |
| python_export | python_setup / getters |
| python_wrapper_setup | python_setup |
| Obsolete API |
| distutils_install_for_testing | no argument (``--via-root``) |
| ``--via-home`` | or ``--via-venv`` |
| python_gen_usedep | python_gen_cond_dep |
| mydistutilsargs rename |
| mydistutilsargs | DISTUTILS_ARGS |
| Post-Python 2 cleanup |
| python_gen* -2 / python2 | remove entirely |
| / pypy | |
| python_gen* -3 | make unconditional |
| python_is_python3 | always assume true |
The changes can be split roughly into four groups: ban of now-private
eclass API, ban of obsolete API functions, mydistutilsargs rename
and bans related to post-Python 2 cleanup.
The private eclass API part involves ``python_export``
and ``python_wrapper_setup``. Both were deprecated in March 2020,
and they were never covered in this guide. The former was historically
used to get information about the Python interpreter (either the current
``${EPYTHON}`` or an arbitrary choice), the latter to create the wrapper
directory containing ``python`` and other executables.
When the functions were used to establish a Python build environment,
the replacement for both is a single ``python_setup`` call. When
``python_export`` was used to grab additional details about the Python
interpreter, the various ``python_get*`` functions should be used
.. code-block:: bash
src_configure() {
# ...
# OLD:
# NEW:
The second group involves sundry API that were deprecated earlier.
These are:
1. ``distutils_install_for_testing --via-home`` layout that stopped
working correctly at some point. The default ``--via-root`` should
work most of the time, and ``-via-venv`` replace the remaining cases
for the removed layout.
2. ``python_gen_usedep`` function that was historically used to generate
partial USE dependencies, and was generally combined with
``REQUIRED_USE`` to force specific (usually old) Python interpreters
for specific features. This was really ugly. Nowadays, you should
really use ``python_gen_cond_dep`` instead.
3. ``PYTHON_MULTI_USEDEP`` placeholder that was temporarily used
in python-single-r1 ebuilds. ``PYTHON_USEDEP`` is equivalent now.
The third group is a sole rename of ``mydistutilsargs`` variable.
Since you usually need to pass the same arguments in all phase
functions, this variable was not really used in local scope. It has
been renamed to uppercase ``DISTUTILS_ARGS`` to follow the common
pattern for global scope variables.
Finally, the fourth group involves banning some of the features that
were specifically used in order to support distinguish between Python 2
and Python 3. This is meant to force cleaning up old cruft from
ebuilds. It comes in three parts:
1. Banning arguments to ``python_gen*`` that reference Python 2
(e.g. ``-2``, ``python2*``, ``python2_7``, ``pypy``). Since Python 2
is no longer supported in the relevant code paths, the relevant calls
should just be removed.
2. Banning the ``-3`` short-hand to ``python_gen*``. Since all
supported interpreters are compatible with Python 3 now, the relevant
code should be made unconditional. Note that ``python3*`` is still
useful, as it distinguishes CPython from PyPy3.
3. Banning the ``python_is_python3`` function. Since the removal
of Python 2 support, it always evaluated to true.
All the aforementioned replacements are available in all EAPIs.