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.

Examples

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.

CODE Simple ebuild code for using python-any-r1

PYTHON_COMPAT=( python2_7 python3_{4,5,6} )

inherit python-any-r1

DEPEND="${PYTHON_DEPS}"

# pkg_setup exported by eclass, call it if you need to redefine
# pkg_setup() {
#   python-any-r1_pkg_setup
# }

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.

CODE Ebuild code for USE-conditional python-any-r1 use

PYTHON_COMPAT=( python2_7 )

inherit python-any-r1

IUSE="test"

DEPEND="test? ( ${PYTHON_DEPS} )"

pkg_setup() {
    use test && python-any-r1_pkg_setup
}

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.

CODE Ebuild code for python-any-r1 with dependencies

PYTHON_COMPAT=( python2_7 python3_{4,5} )

inherit python-any-r1

IUSE="doc"

DEPEND="doc? (
        $(python_gen_any_dep '
            dev-python/rst-linker[${PYTHON_USEDEP}]
            dev-python/sphinx[${PYTHON_USEDEP}]
        '
    )"

# used to determine which impl matched
python_check_deps() {
    has_version "dev-python/rst-linker[${PYTHON_USEDEP}]" &&
    has_version "dev-python/sphinx[${PYTHON_USEDEP}]"
}

pkg_setup() {
    use doc && python-any-r1_pkg_setup
}

API reference

Variables set by ebuilds

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.

CODE Example PYTHON_COMPAT

PYTHON_COMPAT=( python{2_7,3_4,3_5} pypy )

PYTHON_REQ_USE

Note
Please do not confuse this with PYTHON_REQUIRED_USE. REQ stands for requested.

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.

CODE Example for PYTHON_REQ_USE

USE="ssl(+)?,xml(+)"

Variables exported by eclass

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.

CODE Example use of PYTHON_DEPS

DEPEND="test? ( ${PYTHON_DEPS} )"

Metadata needing to be set by ebuilds

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.

CODE DEPEND example with USE conditional

DEPEND="python? ( ${PYTHON_DEPS} )"

CODE DEPEND example for unconditional use of Python

DEPEND="${PYTHON_DEPS}"

Eclass functions

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.

CODE Example use of conditional python-any-r1_pkg_setup

pkg_setup() {
    use python && python-any-r1_pkg_setup
}

CODE Reference implementation of python-any-r1_pkg_setup

python-any-r1_pkg_setup() {
    [[ ${MERGE_TYPE} != binary ]] && python_setup
}

python_gen_any_dep

Usage: python_gen_any_dep <dependency-block>

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.

CODE Example use of python_gen_any_dep and python_check_deps

DEPEND="
    $(python_gen_any_dep '
        dev-python/pygobject:2[${PYTHON_USEDEP}]
        dev-python/pygobject:3[${PYTHON_USEDEP}]
    ')"

python_check_deps() {
    has_version "dev-python/pygobject:2[${PYTHON_USEDEP}]" \
        && has_version "dev-python/pygobject:3[${PYTHON_USEDEP}]"
}

CODE Resulting dependency string

|| (
    (
        dev-lang/python:2.7
        dev-python/pygobject:2[python_targets_python2_7(-),python_single_target_python2_7(+)]
        dev-python/pygobject:3[python_targets_python2_7(-),python_single_target_python2_7(+)]
    )
    (
        dev-lang/python:2.6
        dev-python/pygobject:2[python_targets_python2_6(-),python_single_target_python2_6(+)]
        dev-python/pygobject:3[python_targets_python2_6(-),python_single_target_python2_6(+)]
    )
)

Ebuild callbacks

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.