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.

No USE flags are set in the ebuild. The dependencies generated are purely any-of (||). The package needs to either include PYTHON_DEPS or a call to python_gen_any_dep (if it needs to depend on additional Python packages) in DEPEND.

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

Simple package
This is the most trivial use case for python-any-r1 — a simple package that unconditionally needs Python at build time. The scripts are compatible with both Python 2 and 3.4 through 3.6, and have no additional dependencies.

Package with conditional dependency on Python
This is the case of a package that uses Python only for a subset of build (e.g. documentation, tests…). Python bits are enabled only with USE=test. Only Python 2.7 is supported.

Package with additional dependencies
This is the most complex use case — a package that has dependencies on external Python packages (Sphinx with a plugin). The Python bits are enabled only for USE=doc. A number of Python implementations is supported.

PYTHON_COMPAT
Obligatory. Must be set above the inherit line.

A list of all Python implementations supported by ebuild. The possible values are listed in the implementations article.

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.

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.

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.

If the package needs to depend on modules provided by other Python packages, python_gen_any_dep should be used instead of PYTHON_DEPS.

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.

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.

python_check_deps
If defined, this function is called by python_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.