Gentoo Development Guide

PYTHON-R1

Section: portage (5)
Updated: Oct 2014
Index Return to Main Contents
 

NAME

python-r1 - A common, simple eclass for Python packages.  

DESCRIPTION

A common eclass providing helper functions to build and install packages supporting being installed for multiple Python implementations.

This eclass sets correct IUSE and REQUIRED_USE. It 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-r1 Developer's Guide: http://www.gentoo.org/proj/en/Python/python-r1/dev-guide.xml  

FUNCTIONS

python_gen_usedep <pattern> [...]
Output a USE dependency string for Python implementations which are both in PYTHON_COMPAT and match any of the patterns passed as parameters to the function.

Remember to escape or quote the patterns to premature evaluation as a file name glob.

When all implementations are requested, please use ${PYTHON_USEDEP} instead. Please also remember to set an appropriate REQUIRED_USE to avoid ineffective USE flags.

Example:

PYTHON_COMPAT=( python{2_7,3_2} )
DEPEND="doc? ( dev-python/epydoc[$(python_gen_usedep 'python2*')] )"

It will cause the dependency to look like:

DEPEND="doc? ( dev-python/epydoc[python_targets_python2_7?] )"
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.

Example:

PYTHON_COMPAT=( python{2_7,3_2} )
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.

In order to enforce USE constraints on the packages, verbatim specification. It will get expanded within the function into a proper USE dependency string.

Example:

PYTHON_COMPAT=( python{2_5,2_6,2_7} )
RDEPEND="$(python_gen_cond_dep \
  'dev-python/unittest2[${PYTHON_USEDEP}]' python{2_5,2_6})"

It will cause the variable to look like:

RDEPEND="python_targets_python2_5? (
    dev-python/unittest2[python_targets_python2_5?] )
python_targets_python2_6? (
    dev-python/unittest2[python_targets_python2_6?] )"
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 (or S if unset) to implementation-specific build directory matching BUILD_DIR used by python_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 and BUILD_DIR are set locally, and the former two are exported to the command environment.

python_parallel_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 and BUILD_DIR are set locally, and the former two are exported to the command environment.

Multiple invocations of the command will be run in parallel, up to DISTUTILS_JOBS (defaulting to '-j' option argument from MAKEOPTS).

python_setup
Find the best (most preferred) Python implementation enabled and set the Python build environment up for it.

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.

python_export_best [<variable>...]
Find the best (most preferred) Python implementation enabled and export given variables for it. If no variables are provided, EPYTHON & PYTHON will be exported.
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.

 

ECLASS 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_5 python2_6 python2_7 )

Please note that you can also use bash brace expansion if you like:

PYTHON_COMPAT=( python{2_5,2_6,2_7} )
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
This is an eclass-generated Python dependency string for all implementations listed in PYTHON_COMPAT.

Example use:

RDEPEND="${PYTHON_DEPS}
dev-foo/mydep"
DEPEND="${RDEPEND}"

Example value:

dev-lang/python-exec:=
python_targets_python2_6? ( dev-lang/python:2.6[gdbm] )
python_targets_python2_7? ( dev-lang/python:2.7[gdbm] )
PYTHON_USEDEP
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 and python-distutils-ng eclasses. It must not be used on packages using python.eclass.

Example use:

RDEPEND="dev-python/foo[${PYTHON_USEDEP}]"

Example value:

python_targets_python2_6(-)?,python_targets_python2_7(-)?
PYTHON_REQUIRED_USE
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_6 python_targets_python2_7 )
DISTUTILS_JOBS
The number of parallel jobs to run for distutils-r1 parallel builds. If unset, the job-count in ${MAKEOPTS} will be used.

This variable is intended to be set in make.conf.

BUILD_DIR
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(), the BUILD_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 initial BUILD_DIR.

Example value:

${WORKDIR}/foo-1.3-python2_6
 

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 http://bugs.gentoo.org/  

FILES

/usr/portage/eclass/python-r1  

SEE ALSO

ebuild(5)
http://sources.gentoo.org/eclass/python-r1?view=log


 

Index

NAME
DESCRIPTION
FUNCTIONS
ECLASS VARIABLES
AUTHORS
MAINTAINERS
REPORTING BUGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:25:07 GMT, October 22, 2014