Project:Python/distutils-r1

The distutils-r1 eclass is the modern eclass aimed at packages using distutils, setuptools or a compatible build system.

Description
The distutils-r1 eclass is suited for installing packages that use the distutils build system. It provides metadata, environment setup and phase functions suited for this task. The Python dependencies, REQUIRED_USE and phase functions are exported by default. If your package has only USE-conditional use for distutils, you can disable this using DISTUTILS_OPTIONAL.

distutils-r1 eclass can use either of two backends. By default, the python-r1 eclass is used as a backend, providing possibility to build the package against multiple Python implementations. However, DISTUTILS_SINGLE_IMPL may be set to enforce building for a single implementation only, and in this case python-single-r1 is used.

The ebuilds can safely assume that the eclass will inherit either of the above eclasses. To ease switching, developers are encouraged to rely only upon the common parts of their API rather than individual functions. Similarly to the both backend eclasses, one needs to set PYTHON_COMPAT and possibly PYTHON_REQ_USE.

All of ebuild's operations should be done in sub-phases as described in the phase functions section. Overriding standard phase functions is discouraged since it doesn't provide proper Python build environment and should be only used when absolutely necessary.

The default sub-phases perform a standard build and install using setup.py. By default, an out-of-source build is performed using a shared copy of sources; this can be disabled using DISTUTILS_IN_SOURCE_BUILD. Multiple builds are performed in parallel by default; this can be disabled using DISTUTILS_NO_PARALLEL_BUILD.

Phase functions
As a build system eclass, distutils-r1 provides implementations for most of phase functions. Each of the phases is split into two sub-phases as outlined in the following table:

The distutils-r1 standard phase functions just call sub-phases appropriately. The per-impl sub-phases are called first, with the call being repeated for each of the enabled Python implementations. Then, the common sub-phase is called once, with the build environment of last enabled Python implementation.

In other words, the per-impl sub-phases such as python_compile are used to perform tasks that need to be repeated for each of the enabled implementations, such as building and installing the Python modules. The common sub-phases such as python_compile_all are used to perform tasks that need being done only once such as building and installing documentation.

Each sub-phase is run with complete Python build environment, having EPYTHON, PYTHON, BUILD_DIR and PYTHONPATH set properly for distutils build, and Python executables and pkg-config files wrapped. Sub-phases are run in the source directory (S). Per-implementation sub-phases may be run in parallel.

Similarly to regular phase functions, some of the sub-phases have default implementations. The default implementations are named alike phase functions in eclasses. For example, the default for python_compile is distutils-r1_python_compile. The sub-phases which have default implementation have been highlighted and marked with an asterisk in the phase function table.

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 Python/Implementation USE flags for reference.

Example for PYTHON_REQ_USE

DISTUTILS_SINGLE_IMPL
Boolean. Enabled if non-empty, defaults to disabled. Must be set above the inherit line.

Enables the single implementation mode. If enabled, the eclass will use python-single-r1 backend. The package will be built with support for a single implementation only but it will be able to depend on libraries that do not support multiple implementations. Otherwise (the default), the eclass uses python-r1 backend and the package is built with support for multiple implementations of choice.

DISTUTILS_OPTIONAL
Boolean. Enabled if non-empty, defaults to disabled. Must be set above the inherit line.

Enables optional distutils mode. In this mode, no phase functions are exported, dependencies and REQUIRED_USE are not set by default. User is expected to define his own phase functions and call the eclass implementations properly, and to use PYTHON_DEPS and PYTHON_REQUIRED_USE.

Example snippet using DISTUTILS_OPTIONAL

DISTUTILS_IN_SOURCE_BUILD
Boolean. Enabled if non-empty, defaults to disabled.

Enables in-source builds. In this mode, a separate copy of package sources is created for each of the enabled Python implementations and the build is performed within this copy. Otherwise (the default), an out-of-source build is performed, with sources being shared by all builds and output being placed in separate build trees.

Use as last resort only. If an out-of-source build fails, it is recommended to find the underlying issue and fix it instead.

DISTUTILS_NO_PARALLEL_BUILD
Boolean. Enabled if non-empty, defaults to disabled.

Enables non-parallel build. When used, only one build will be performed at a time. Otherwise, the builds for multiple Python implementations will be done in parallel, up to the number of jobs.

This can be used if the build system itself performs the build in parallel or is particularly resource hungry.

PATCHES
Array. Defaults to unset/empty.

A list of patches that will be applied by distutils-r1_python_prepare_all. The patches need to be specified by full path. If unspecified, no ebuild-specific patches are applied.

Example PATCHES setting

DOCS
Array or scalar. Defaults to unset.

A list of documentation files that will be installed by distutils-r1_python_install_all. The files can be specified using absolute paths or paths relative to source directory (S).

If unset, the implementation will find documentation files matching standard names (as described in EAPI 4 src_install) and install them. If set to an empty list, no documentation will be installed. Setting it to any value disables the automatic search.

Example DOCS setting

HTML_DOCS
Array or scalar. Defaults to unset/empty.

A list of HTML documentation files that will be installed by distutils-r1_python_install_all. The files can be specified using absolute paths or paths relative to source directory (S). If unset or empty, no HTML documentation will be installed.

Example conditional HTML_DOCS setting

EXAMPLES
Array. Defaults to unset/empty.

A list of example files/directories that will be installed by distutils-r1_python_install_all. The files can be specified using absolute paths or paths relative to source directory (S). If unset or empty, no examples will be installed.

The examples will be installed in 'examples' subdirectory of docdir, and they will not be explicitly compressed.

Example conditional EXAMPLES setting

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

It should be used only with DISTUTILS_OPTIONAL enabled. Otherwise, the dependencies are placed in RDEPEND and DEPEND automatically.

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 should be used only with DISTUTILS_OPTIONAL enabled. Otherwise, the constraint is placed in REQUIRED_USE automatically.

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 should be used on package dependencies which are using the python-r1 eclass. If DISTUTILS_SINGLE_IMPL is enabled, it can be used against python-single-r1 packages as well.

Example use of PYTHON_USEDEP

distutils-r1_python_prepare_all
Default implementation of python_prepare_all. If you override python_prepare_all, you are required to call the default at the end of it.

The default implementation does the following, in order:


 * 1) applies patches from the PATCHES variable.
 * 2) applies user patches.
 * 3) performs Gentoo-specific cleanups on the sources/build system:
 * 4) * disables auto-downloading of setuptools.
 * 5) creates source copies for multiple implementations if DISTUTILS_IN_SOURCE_BUILD is enabled.

distutils-r1_python_compile
Default implementation of python_compile. If you override python_compile, you are advised to call it.

The default implementation does the following, in order:


 * 1) performs Gentoo-specific cleanups which need to be done per-implementation:
 * 2) * creates pydistutils.cfg file setting build directories for distutils,
 * 3) * copies bundled egg-info files to build tree (as required for out-of-source build).
 * 4) calls setup.py to build the sources.

distutils-r1_python_install
Default implementation of python_install. If you override python_install, you are advised to call it.

The default implementation does the following, in order:


 * 1) enables byte-code compilation (which is disabled by default in ebuild scope).
 * 2) calls setup.py to install the package in a dedicated fake root.
 * 3) wraps Python scripts as necessary.
 * 4) merges the package to the ebuild installation root (D).

distutils-r1_python_install_all
Default implementation of python_install_all. If you override python_install_all, you are required to call the default in it.

The default implementation does the following, in order:


 * 1) installs documentation listed in the DOCS and HTML_DOCS variables.
 * 2) installs examples listed in the EXAMPLES variable.

esetup.py
Usage: esetup.py [ ...]

Run setup.py using the current Python interpreter and standard configuration arguments. The following arguments are passed to setup.py, in order:


 * 1) mydistutilsargs,
 * 2) additional arguments passed to the command.

It should be noted that distutils-r1_python_compile influences the behavior of setup.py by setting build-dirs. esetup.py invocations preceding it will not respect build-dir.

distutils_install_for_testing
Usage: distutils_install_for_testing [ ...]

Run esetup.py to install the package to a temporary directory suitable for running tests against the installed package. The install layout will be specifically adjusted to suit packages using Python namespaces.

This function introduces TEST_DIR variable that specifies the directory where the package was installed. The Python modules are installed to ${TEST_DIR}/lib, and the Python scripts are installed to ${TEST_DIR}/scripts. The former directory is added to PYTHONPATH.

Example use of distutils_install_for_testing