From Gentoo Wiki
Jump to: navigation, search

python-r1 is a new eclass for Python packages. The major goal is to provide a simpler (and more powerful at the same time) replacement for the old python.eclass which people have significant trouble maintaining.

The -r1 eclass branch consists of the following eclasses:

  • python-r1 — general-use Python package eclass,
  • distutils-r1 — distutils build system wrapper.

Information for users

Choice of Python implementations

The main difference for users is the way that Python implementations for packages being built are selected.

In python.eclass, the implementations to be built can be selected using custom USE_PYTHON variable in make.conf. If unset, the implementation currently selected using eselect python is used.

In python-r1 (and python-distutils-ng) the implementation is controlled using USE_EXPAND variable PYTHON_TARGETS. If unset, the Gentoo-wide default is used (currently it is Python 2.7).

The enabled implementation can be set like the following:

CodeExample PYTHON_TARGETS setup in make.conf

PYTHON_TARGETS="python2_7 python3_2"

Running installed scripts

The Python scripts are installed by distutils-r1 in the following layout:

/usr/bin/script -> python-exec

The latter scripts are actual Python scripts converted to the format suitable for the appropriate Python interpreter. They can be either run directly or through the correct Python interpreter:

user $ pypy-c1.8 /usr/bin/script-pypy-c1.8
Please note that if you use another Python interpreter for the particular script, it may not work at all or fail at a random point.

The actual script is replaced by a symlink to the python-exec wrapper. It can be only run directly, and it selects the correct variant and interpreter based on user preferences:

user $ /usr/bin/script

The wrapper will use the first of the following implementations which is supported by the script:

  1. The implementation specified by the EPYTHON environment variable,
  2. the main system Python interpreter (chosen through eselect python),
  3. the alternate system Python interpreter (if the main one was Python 2, the preferred Python 3; if the main one was Python 3, the preferred Python 2),
  4. best available Python interpreter supported by the script.

Information for ebuild developers

Uses for eclasses

The distutils-r1 eclass should be used:

  • in Python packages which use the distutils build system,
  • in Python packages which use another build system which works similarly to distutils (respects EPYTHON, installs scripts with correct shebang).

The python-r1 eclass should be used:

  • in packages with optional Python parts,
  • in Python packages which use a build system for which distutils-r1 is not suitable.

The main features of the eclasses are listed in the following table:

python-r1 distutils-r1
Python implementation USE flags IUSE & REQUIRED_USE
Python dependency on request (${PYTHON_DEPS}) always
Phase functions none src_prepare, src_configure, src_compile, src_test, src_install

Migrating distutils packages

The most common changes needing to be done when migrating distutils packages to distutils-r1 are:

  1. replace PYTHON_DEPEND & RESTRICT_PYTHON_ABIS with PYTHON_COMPAT (inclusive list),
  2. remove SUPPORT_PYTHON_ABIS (always on),
  3. replace PYTHON_USE_WITH with PYTHON_REQ_USE (which follows USE dependency syntax),
  4. remove PYTHON_MODNAME (not needed),
  5. replace manual patching with PATCHES array (if desired),
  6. remove calls to epatch_user (done in distutils-r1_prepare_all()),
  7. replace python_execute_function with appropriate pseudo-phase functions where appropriate (e.g. python_test()) or with python_foreach_impl elsewhere,
  8. replace DISTUTILS_SRC_TEST with explicit python_test() function,
  9. check package's dependencies for packages using python-r1. If any are found, append [${PYTHON_USEDEP}] to them,
  10. check package's reverse dependencies for packages using python-r1. If any are found, append [${PYTHON_USEDEP}] to their dependency on your package.

For example, the following preamble:

CodeA random distutils preamble

# python eclass cruft
PYTHON_USE_WITH="readline sqlite"
RESTRICT_PYTHON_ABIS="2.5 *-jython *-pypy-*"

would be replaced by:

CodeThe equivalent distutils-r1 preamble

PYTHON_COMPAT=( python{2_6,2_7,3_1,3_2} )