Project:Python/distutils-r1

The distutils-r1 eclass is the modern eclass aimed at packages using distutils, setuptools or a compatible build system.

Phase functions
As a build system eclass, distutils-r1 provides implementations for most of phase functions. Each of the phases is split into two sub-phases as outlined in the following table:

The distutils-r1 standard phase functions just call sub-phases appropriately. The per-impl sub-phases are called first, with the call being repeated for each of the enabled Python implementations. Then, the common sub-phase is called once, with the build environment of last enabled Python implementation.

In other words, the per-impl sub-phases such as python_compile are used to perform tasks that need to be repeated for each of the enabled implementations, such as building and installing the Python modules. The common sub-phases such as python_compile_all are used to perform tasks that need being done only once such as building and installing documentation.

PYTHON_COMPAT
Obligatory. Must be set above the inherit line.

A list of all Python implementations supported by ebuild. This variable is described more thoroughly in PYTHON_COMPAT article.

Example PYTHON_COMPAT

PYTHON_REQ_USE
Optional, defaults to none. Must be set above the inherit line.

USE-dependency that will be applied to all Python interpreters pulled in as dependencies. Takes the form of EAPI 4 USE dependency string, must apply cleanly to all supported Python implementations. See Python/Implementation USE flags for reference.

Example for PYTHON_REQ_USE

DISTUTILS_SINGLE_IMPL
Boolean. Enabled if non-empty, defaults to disabled. Must be set above the inherit line.

Enables the single implementation mode. If enabled, the eclass will use python-single-r1 backend. The package will be built with support for a single implementation only but it will be able to depend on libraries that do not support multiple implementations. Otherwise (the default), the eclass uses python-r1 backend and the package is built with support for multiple implementations of choice.

DISTUTILS_OPTIONAL
Boolean. Enabled if non-empty, defaults to disabled. Must be set above the inherit line.

Enables optional distutils mode. In this mode, no phase functions are exported, dependencies and REQUIRED_USE are not set by default. User is expected to define his own phase functions and call the eclass implementations properly, and to use PYTHON_DEPS and PYTHON_REQUIRED_USE.

DISTUTILS_IN_SOURCE_BUILD
Boolean. Enabled if non-empty, defaults to disabled.

Enables in-source builds. In this mode, a separate copy of package sources is created for each of the enabled Python implementations and the build is performed within this copy. Otherwise (the default), an out-of-source build is performed, with sources being shared by all builds and output being placed in separate build trees.

Use as last resort only. If an out-of-source build fails, it is recommended to find the underlying issue and fix it instead.

DISTUTILS_NO_PARALLEL_BUILD
Boolean. Enabled if non-empty, defaults to disabled.

Enables non-parallel build. When used, only one build will be performed at a time. Otherwise, the builds for multiple Python implementations will be done in parallel, up to the number of jobs.

This can be used if the build system itself performs the build in parallel or is particularly resource hungry.

PYTHON_DEPS
Contains the dependency string on Python interpreters and auxiliary tools.

It should be used only with DISTUTILS_OPTIONAL enabled. Otherwise, the dependencies are placed in RDEPEND and DEPEND automatically.

If the Python dependency is conditional to a USE flag, the reference should be placed in appropriate USE-conditional block.

Example use of PYTHON_DEPS

PYTHON_REQUIRED_USE
Contains the REQUIRED_USE constraint requiring at least one Python implementation to be selected.

It should be used only with DISTUTILS_OPTIONAL enabled. Otherwise, the constraint is placed in REQUIRED_USE automatically.

If the Python dependency is conditional to a USE flag, the reference should be placed in appropriate USE-conditional block.

Example use of PYTHON_REQUIRED_USE

PYTHON_USEDEP
Contains a USE dependency string that can be used to enforce matching Python implementations on package dependencies.

It should be used on package dependencies which are using the python-r1 eclass. If DISTUTILS_SINGLE_IMPL is enabled, it can be used against python-single-r1 packages as well.

Example use of PYTHON_USEDEP