Project:Python/python-r1

python-r1 is the python-r1 suite eclass intended for ebuilds that install files that may be used with one or more of installed Python interpreters but not use the distutils build system.

For this reason, the ebuild itself needs to ensure proper install procedure for multiple Python implementations. This often means that it is the hardest to use of all -r1 eclasses. Therefore, if your package doesn't really need to be installed for multiple implementations, you may consider using python-single-r1 instead.

Description
python-r1 eclass is suited for installing Python modules and scripts that do not use the distutils build system. This often involves Python bindings and conditional Python support in applications.

As with other eclasses, you need to set PYTHON_COMPAT (and optionally PYTHON_REQ_USE) before inheriting the eclass. This is necessary so that proper values can be generated for global scope variables.

This eclass affects ebuild metadata only by adding PYTHON_TARGETS flags to IUSE. It also exports PYTHON_DEPS and PYTHON_REQUIRED_USE that need to be explicitly used in RDEPEND, DEPEND and REQUIRED_USE.

No phase functions are exported, and no global environment is set. Instead, local Python build scopes are established within functions run through python_foreach_impl and python_parallel_foreach_impl. Those functions need to be used to build and install the Python parts of the ebuild.

For information on variables and functions available for building packages, see Python build environment.

Two additional eclass-specific functions are provided. python_export_best can set up global Python build environment for the most preferred Python implementation, for example to build documentation. python_replicate_script can be used to convert a plain Python script installed by package to have proper shebang and wrapping.

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

Variables exported by eclass
Obligatory: It is the ebuild author's responsibility to set DEPEND, RDEPEND, and REQUIRED_USE; the eclass does not set them.

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

It must be used within RDEPEND and/or DEPEND. 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 must be used within REQUIRED_USE. 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 must be used on package dependencies which are using the python-r1 eclass.

Example use of PYTHON_USEDEP

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

REQUIRED_USE needs to be defined by the ebuild so that at least one of the supported Python branches is enabled at installation time, pulling in proper Python dependencies. The eclass fills PYTHON_REQUIRED_USE for you to use. Two examples:

REQUIRED_USE example with guard

REQUIRED_USE example without guard

python_gen_usedep
Usage: python_gen_usedep ...

Outputs USE dependency string that requires the implementations matching pattern(s) to match. Can be used to output USE-dependencies on dependencies that are available or needed only in some of the supported implementations.

If multiple patterns are provided, implementations that match any of them are used. Please remember to quote wildcard characters in patterns to avoid random filename expansion.

Often, python_gen_usedep needs to be used with proper REQUIRED_USE in order to require any of the implementations to be enabled.

Example use of python_gen_usedep

python_gen_useflags
Usage: python_gen_useflags ...

Outputs space separated list of flags for implementations matching pattern(s). Can be used to create REQUIRED_USE values, usually in conjunction with python_gen_usedep.

If multiple patterns are provided, implementations that match any of them are used. Please remember to quote wildcard characters in patterns to avoid random filename expansion.

python_gen_cond_dep
Usage: python_gen_cond_dep  ...

Outputs provided dependency strings enclosed in USE-conditional block, making them conditional to one of the implementations matching patterns being enabled.

If multiple patterns are provided, implementations that match any of them are used. Please remember to quote wildcard characters in patterns to avoid random filename expansion.

${PYTHON_USEDEP} may be passwed as part of the dependency string. It will be expanded appropriately.

Example use of python_gen_cond_dep

python_foreach_impl
Usage: python_foreach_impl [ ...]

Runs given bash command for each of enabled Python implementations, starting with least preferred one. The execution will continue throughout all the implementations unless one of the command calls die.

The command is run within properly initiated Python build environment. EPYTHON, PYTHON and BUILD_DIR will be exported, and Python executable & pkg-config wrappers will be set up.

If all commands succeed (return 0 status), the command returns 0. Otherwise, it returns the first non-zero status.

Example use of python_foreach_impl

python_parallel_foreach_impl
Usage: python_parallel_foreach_impl [ ...]

Runs given bash command for each of enabled Python implementations, starting with least preferred one. Multiple invocations, up to the number of jobs in MAKEOPTS, will be run in parallel. If one of the commands die, it is not guaranteed that the execution will abort before the end of the phase.

The command is run within properly initiated Python build environment. EPYTHON, PYTHON and BUILD_DIR will be exported, and Python executable & pkg-config wrappers will be set up.

If all commands succeed (return 0 status), the command returns 0. Otherwise, it returns the first non-zero status.

python_setup
Usage: python_setup

Find the best supported Python interpreter that the user enabled 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 needs to be called only if Python support is required outside of python_foreach_impl calls since the latter sets up a local build environment itself. It needs to be called only once for the ebuild scope.

Example use of python_setup

python_export_best
Usage: python_export_best [ ...]

Export the build environment variables for the most preferred of enabled Python implementations. If variable names are passed, the specified variables will be exported. Otherwise, default set of EPYTHON and PYTHON will be exported.

It is recommended to follow the call to this function with python_wrapper_setup to obtain properly wrapped Python executables and pkg-config.

This can be used to set the build environment for running operations that need to be run only once during build-time, e.g. building documentation.

python_replicate_script
Usage: python_replicate_script ...

Copy the scripts at specified paths for all enabled implementations, alternating the shebangs and wrapping them properly. Expects absolute path (including ${D}). Dies on failure.

This can be used to clean up scripts installed by non-distutils build systems.

Example use of python_replicate_script

python_copy_sources
Usage: python_copy_sources

Create a separate copy of package sources for each of enabled Python implementations. The sources will be obtained from initial BUILD_DIR (or S, if it is unset), and they will be copied to implementation-specific BUILD_DIRs as set by python_foreach_impl.

This function is usually used to handle broken build systems. When possible, out-of-source build is preferred.