python-r1.eclass
Description
A common eclass providing helper functions to build and install packages supporting being installed for multiple Python implementations.
This eclass sets correct IUSE
. Modification of REQUIRED_USE
has to
be done by the author of the ebuild (but PYTHON_REQUIRED_USE
is
provided for convenience, see below). python-r1
exports PYTHON_DEPS
and PYTHON_USEDEP
so you can create correct dependencies for your
package easily. It also provides methods to easily run a command for
each enabled Python implementation and duplicate the sources for them.
Please note that python-r1
will always inherit python-utils-r1
as
well. Thus, all the functions defined there can be used
in the packages using python-r1
, and there is no need ever to inherit
both.
For more information, please see the Python Guide: https://projects.gentoo.org/python/guide/
Functions
- python_gen_useflags [<pattern>...]
-
Output a list of USE flags for Python implementations which are both in
PYTHON_COMPAT
and match any of the patterns passed as parameters to the function.For the pattern syntax, please see
_python_impl_matches
inpython-utils-r1.eclass
.Example:
PYTHON_COMPAT=( python{2_7,3_4} ) REQUIRED_USE="doc? ( || ( $(python_gen_useflags python2*) ) )"
It will cause the variable to look like:
REQUIRED_USE="doc? ( || ( python_targets_python2_7 ) )"
- python_gen_cond_dep <dependency> [<pattern>...]
-
Output a list of <dependency>-ies made conditional to USE flags of Python implementations which are both in
PYTHON_COMPAT
and match any of the patterns passed as the remaining parameters.For the pattern syntax, please see
_python_impl_matches
inpython-utils-r1.eclass
.In order to enforce USE constraints on the packages, verbatim
'${PYTHON_USEDEP}'
(quoted!) may be placed in the dependency specification. It will get expanded within the function into a proper USE dependency string.Example:
PYTHON_COMPAT=( python{2_7,3_{3,4}} pypy ) RDEPEND="$(python_gen_cond_dep \ 'dev-python/unittest2[${PYTHON_USEDEP}]' python2_7 pypy )"
It will cause the variable to look like:
RDEPEND="python_targets_python2_7? ( dev-python/unittest2[python_targets_python2_7?] ) python_targets_pypy? ( dev-python/unittest2[python_targets_pypy?] )"
- python_gen_impl_dep [<requested-use-flags> [<impl-pattern>...]]
-
Output a dependency on Python implementations with the specified USE dependency string appended, or no USE dependency string if called without the argument (or with empty argument). If any implementation patterns are passed, the output dependencies will be generated only for the implementations matching them.
For the pattern syntax, please see
_python_impl_matches
inpython-utils-r1.eclass
.Use this function when you need to request different USE flags on the Python interpreter depending on package's USE flags. If you only need a single set of interpreter USE flags, just set
PYTHON_REQ_USE
and use${PYTHON_DEPS}
globally.Example:
PYTHON_COMPAT=( python{2_7,3_{3,4}} pypy ) RDEPEND="foo? ( $(python_gen_impl_dep 'xml(+)') )"
It will cause the variable to look like:
RDEPEND="foo? ( python_targets_python2_7? ( dev-lang/python:2.7[xml(+)] ) python_targets_pypy? ( dev-python/pypy[xml(+)] ) )"
- python_gen_any_dep [<dependency-block> [<impl-pattern>...]]
-
Generate an any-of dependency that enforces a version match between the Python interpreter and Python packages.
<dependency-block>
may list one or more dependencies with verbatim'${PYTHON_USEDEP}'
or'${PYTHON_SINGLE_USEDEP}'
references (quoted!) that will get expanded inside the function. If<dependency-block>
is an empty string (or no arguments are passed), a pure dependency on any Python interpreter will be generated.Optionally, patterns may be specified to restrict the dependency to a subset of Python implementations supported by the ebuild. For the pattern syntax, please see
_python_impl_matches
inpython-utils-r1.eclass
.This should be used along with an appropriate
python_check_deps()
that checks which of the any-of blocks were matched, andpython_setup
call that enables use of the matched implementation.Example use:
BDEPEND="$(python_gen_any_dep ' dev-python/foo[${PYTHON_SINGLE_USEDEP}] || ( dev-python/bar[${PYTHON_USEDEP}] dev-python/baz[${PYTHON_USEDEP}] )' -2)" python_check_deps() { has_version "dev-python/foo[${PYTHON_SINGLE_USEDEP}]" \ && { has_version "dev-python/bar[${PYTHON_USEDEP}]" \ || has_version "dev-python/baz[${PYTHON_USEDEP}]"; } } src_compile() { python_foreach_impl usual_code # some common post-build task that requires Python 2 python_setup -2 emake frobnicate }
Example value:
|| ( ( dev-lang/python:3.7 dev-python/foo[python_single_target_python3_7(-)] || ( dev-python/bar[python_targets_python3_7(-),-python_single_target_python3_7(-)] dev-python/baz[python_targets_python3_7(-),-python_single_target_python3_7(-)] ) ) ( dev-lang/python:3.8 dev-python/foo[python_single_target_python3_8(-)] || ( dev-python/bar[python_targets_python3_8(-)] dev-python/baz[python_targets_python3_8(-)] ) ) )
- python_copy_sources
-
Create a single copy of the package sources for each enabled Python implementation.
The sources are always copied from initial
BUILD_DIR
(orS
if unset) to implementation-specific build directory matchingBUILD_DIR
used bypython_foreach_abi()
. - python_foreach_impl <command> [<args>...]
-
Run the given command for each of the enabled Python implementations. If additional parameters are passed, they will be passed through to the command.
The function will return 0 status if all invocations succeed. Otherwise, the return code from first failing invocation will be returned.
For each command being run,
EPYTHON
,PYTHON
andBUILD_DIR
are set locally, and the former two are exported to the command environment. - python_setup [<impl-pattern>...]
-
Find the best (most preferred) Python implementation that is suitable for running common Python code. Set the Python build environment up for that implementation. This function has two modes of operation: pure and any-of dep.
The pure mode is used if
python_check_deps()
function is not declared. In this case, an implementation is considered suitable if it is supported (inPYTHON_COMPAT
), enabled (via USE flags) and matches at least one of the patterns passed (or'*'
if no patterns passed).Implementation restrictions in the pure mode need to be accompanied by appropriate
REQUIRED_USE
constraints. Otherwise, the eclass may fail at build time due to unsatisfied dependencies.The any-of dep mode is used if
python_check_deps()
is declared. In this mode, an implementation is considered suitable if it is supported, matches at least one of the patterns andpython_check_deps()
has successful return code. USE flags are not considered.The
python_check_deps()
function in the any-of mode needs to be accompanied by appropriate any-of dependencies.For the pattern syntax, please see
_python_impl_matches
inpython-utils-r1.eclass
.This function needs to be used when Python is being called outside of
python_foreach_impl
calls (e.g. for shared processes like doc building).python_foreach_impl
sets up the build environment itself.Pure mode example:
BDEPEND="doc? ( dev-python/epydoc[$(python_gen_usedep 'python2*')] )" REQUIRED_USE="doc? ( $(python_gen_useflags 'python2*') )" src_compile() { #... if use doc; then python_setup 'python2*' make doc fi }
Any-of mode example:
BDEPEND="doc? ( $(python_gen_any_dep 'dev-python/epydoc[${PYTHON_USEDEP}]' 'python2*') )" python_check_deps() { has_version "dev-python/epydoc[${PYTHON_USEDEP}]" } src_compile() { #... if use doc; then python_setup 'python2*' make doc fi }
- python_replicate_script <path>...
-
Copy the given script to variants for all enabled Python implementations, then replace it with a symlink to the wrapper.
All specified files must start with a
python
shebang. A file not having a matching shebang will be refused.
Variables
- PYTHON_COMPAT (REQUIRED)
-
This variable contains a list of Python implementations the package supports. It must be set before the
inherit
call. It has to be an array.Example:
PYTHON_COMPAT=( python2_7 python3_3 python3_4 )
Please note that you can also use bash brace expansion if you like:
PYTHON_COMPAT=( python2_7 python3_{3,4} )
- PYTHON_COMPAT_OVERRIDE (USER VARIABLE)
-
This variable can be used when working with ebuilds to override the in-ebuild
PYTHON_COMPAT
. It is a string listing all the implementations which package will be built for. It need be specified in the calling environment, and not in ebuilds.It should be noted that in order to preserve metadata immutability,
PYTHON_COMPAT_OVERRIDE
does not affectIUSE
nor dependencies. The state ofPYTHON_TARGETS
is ignored, and all the implementations inPYTHON_COMPAT_OVERRIDE
are built. Dependencies need to be satisfied manually.Example:
PYTHON_COMPAT_OVERRIDE='pypy python3_3' emerge -1v dev-python/foo
- PYTHON_REQ_USE
-
The list of USEflags required to be enabled on the chosen Python implementations, formed as a USE-dependency string. It should be valid for all implementations in
PYTHON_COMPAT
, so it may be necessary to use USE defaults.This should be set before calling
inherit
.Example:
PYTHON_REQ_USE="gdbm,ncurses(-)?"
It will cause the Python dependencies to look like:
python_targets_pythonX_Y? ( dev-lang/python:X.Y[gdbm,ncurses(-)?] )
- PYTHON_DEPS (GENERATED BY ECLASS)
-
This is an eclass-generated Python dependency string for all implementations listed in
PYTHON_COMPAT
.Example use:
RDEPEND="${PYTHON_DEPS} dev-foo/mydep" BDEPEND="${PYTHON_DEPS}"
Example value:
python_targets_python2_7? ( dev-lang/python:2.7[gdbm] ) python_targets_pypy? ( dev-python/pypy[gdbm] )
- PYTHON_USEDEP (GENERATED BY ECLASS)
-
This is an eclass-generated USE-dependency string which can be used to depend on another Python package being built for the same Python implementations.
The generate USE-flag list is compatible with packages using
python-r1
andpython-distutils-ng
eclasses. It must not be used on packages usingpython.eclass
.Example use:
RDEPEND="dev-python/foo[${PYTHON_USEDEP}]"
Example value:
python_targets_python2_7(-)?,python_targets_python3_4(-)?
- PYTHON_SINGLE_USEDEP (GENERATED BY ECLASS)
-
An eclass-generated USE-dependency string for the currently tested implementation. It is set locally for
python_check_deps()
call.The generated USE-flag list is compatible with packages using
python-single-r1
eclass. Forpython-r1
dependencies, usePYTHON_USEDEP
.Example use:
python_check_deps() { has_version "dev-python/bar[${PYTHON_SINGLE_USEDEP}]" }
Example value:
python_single_target_python3_7(-)
- PYTHON_REQUIRED_USE (GENERATED BY ECLASS)
-
This is an eclass-generated required-use expression which ensures at least one Python implementation has been enabled.
This expression should be utilized in an ebuild by including it in
REQUIRED_USE
, optionally behind a use flag.Example use:
REQUIRED_USE="python? ( ${PYTHON_REQUIRED_USE} )"
Example value:
|| ( python_targets_python2_7 python_targets_python3_4 )
- BUILD_DIR (GENERATED BY ECLASS)
-
The current build directory. In global scope, it is supposed to contain an initial build directory; if unset, it defaults to
${S}
.In functions run by
python_foreach_impl()
, theBUILD_DIR
is locally set to an implementation-specific build directory. That path is created through appending a hyphen and the implementation name to the final component of the initialBUILD_DIR
.Example value:
${WORKDIR}/foo-1.3-python2_7
Authors
Author: Michał Górny <mgorny@gentoo.org>
Based on work of: Krzysztof Pawlik <nelchael@gentoo.org>
Maintainers
Python team <python@gentoo.org>
Reporting Bugs
Please report bugs via https://bugs.gentoo.org/