Project:Python/python-any-r1

python-any-r1 is the python-r1 suite eclass intended for ebuilds that need Python during build-time only and therefore need not to be strongly bound to a particular Python implementation.

Description
python-any-r1 is suited to provide ebuild with any Python implementation matching proper constraints without enforcing any specific action on the user. It exports a simple pkg_setup implementation that finds a proper Python implementation installed and performs a complete build environment setup for it.

This kind of setup is enough for most build systems to be able to find and use the implementation of choice properly.

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 Project:Python/Implementation USE flags for reference.

Example for PYTHON_REQ_USE

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

It should be used within RDEPEND and DEPEND. If the Python dependency is conditional to a USE flag, the reference should be placed in appropriate USE-conditional block.

If python_gen_any_dep is used, its output contains the atoms from PYTHON_DEPS already. The variable does not need to be used then.

Example use of PYTHON_DEPS

DEPEND
Obligatory. Must be set (somewhere after the inherit line).

DEPEND needs to be defined by the ebuild to provide dependencies on proper Python implementations.

The eclass provides PYTHON_DEPS convenience variable with a proper dependency on Python interpreters. If the Python support in package is unconditional, PYTHON_DEPS needs to be placed directly in DEPEND. If the Python support is conditional to a USE flag, the PYTHON_DEPS reference needs to be placed inside matching USE conditional.

DEPEND example with USE conditional

DEPEND example for unconditional use of Python

python_setup
Usage: python_setup

Find a supported Python interpreter that is installed and set up the build environment for it. EPYTHON, PYTHON and BUILD_DIR are exported, and Python executable & pkg-config wrappers will be set up.

This function will accept Python implementations that are installed, listed in PYTHON_COMPAT and that satisfy PYTHON_REQ_USE if defined. If the ebuild defines python_check_deps function, it will be called to perform additional tests on the implementation afterwards. Please make sure to place a suitable dependency string (e.g. using python_gen_any_dep) that will enforce at least one matching Python implementation.

python-any-r1_pkg_setup
Usage: python-any-r1_pkg_setup

The standard exported pkg_setup phase. Calls python_setup if the package is built from sources. In a binary package install, this function is a no-op.

If Python support in the package is conditional to a USE flag, a custom pkg_setup must be used with python-any-r1_pkg_setup being invoked conditionally to the flag. If Python support is desired during binary package's pkg_preinst/postinst phases, python_setup needs to be used directly instead.

Example use of conditional python-any-r1_pkg_setup

python_gen_any_dep
Usage: python_gen_any_dep 

Outputs a dependency string that requires at least one supported Python implementation to be installed along with packages having support for that implementation enabled.

The dependency-block is a free-form dependency string. It may contain verbatim ${PYTHON_USEDEP} string (use single quotes to avoid its early expansion) that will be replaced by USE dependency string matching particular implementation. The string will be repeated for each of the supported implementations.

This function needs to be used in conjunction with python_check_deps. The dependency strings will enforce a matching implementation being installed but python_check_deps needs to determine which of the supported implementations matched the any-of dep.

The output of python_gen_any_dep contains the dependency string on Python interpreter as well. If it is used, it is no longer necessary to use PYTHON_DEPS.

Example use of python_gen_any_dep and python_check_deps

Resulting dependency string

python_check_deps
If defined, this function is called by python-any-r1_pkg_setup for each installed and supported Python implementation to determine whether it is properly suited for the build.

The function is run with a minimal build environment, consisting of EPYTHON and PYTHON_USEDEP. The implementation in question is guaranteed to be installed and match PYTHON_REQ_USE.

The function needs to return 0 if the implementation can be used for the build, non-zero code otherwise. The checks done in the function should be accompanied by proper dependency strings (usually obtained using python_gen_any_dep). If all calls to this function return failure, the eclass dies with 'No supported Python implementation installed' message.