Project:Python/distutils-r1

The distutils-r1 eclass is Article description::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 eclass is used.

The ebuilds can safely assume that distutils-r1 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. By default, an out-of-source build is performed using a shared copy of sources; this can be disabled using DISTUTILS_IN_SOURCE_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-implementation 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-implementation 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 values set properly for distutils build, and Python executables and pkg-config files wrapped. Sub-phases are run in the source directory (${S}).

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 the PYTHON_COMPAT article.

PYTHON_REQ_USE
Optional, defaults to none. Must be set above the  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.

DISTUTILS_SINGLE_IMPL
Boolean. Enabled if non-empty, defaults to disabled. Must be set above the  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  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 the PYTHON_DEPS and PYTHON_REQUIRED_USE variables.

DISTUTILS_ALL_SUBPHASE_IMPLS
Array. Defaults to unset/empty.

A list of wildcards restricting allowed implementations in *_all sub-phases. If unset, all implementations are allowed. Otherwise, the *_all phases will be run using one of the enabled implementations matching one of the patterns.

The value of this variable usually needs to be set in a regular phase function, preferably before any of the *_all implementations are called (e.g. in pkg_setup). If the value changes at run-time, the following *_all sub-phases may be called with a different Python interpreter.

Please remember to set appropriate REQUIRED_USE constraints before using DISTUTILS_ALL_SUBPHASE_IMPLS. Otherwise, the build may fail being unable to find a matching Python implementation.

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.

PATCHES
Array. Defaults to unset/empty.

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

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.

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.

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.

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.

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.

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.

distutils_enable_tests
Usage: distutils_enable_sphinx [--no-autodoc | ...]

Sets global variables, declares python_check_deps function and python_compile_all sub-phase to build documentation using.

subdir specifies the directory containing documentation to build. plugin-pkgs may be used to specify additional plugin packages that your package needs. --no-autodoc should be used if the package does not use any external plugins and does not use autodoc. The function automatically detects if it's missing or specified extraneously.

Note that the function appends to IUSE and BDEPEND. If you modify those variables after calling it, you need to append as well to avoid overwriting the values.

In the no-autodoc mode, a simple dependency on Sphinx as external package is generated. Otherwise, full python_gen_any_dep + python_check_deps logic is used. If you need to use this kind of logic for other dependencies, you need to reimplement it manually.

Please note that this function does not work if package must be explicitly built for given implementation before using Sphinx. For this use case, you need to explicitly depend on Sphinx with PYTHON_USEDEP, and manually call it from python_compile_all. In both cases, you can call sphinx_compile_all.

distutils_enable_tests
Usage: distutils_enable_tests 

Sets global variables and declares python_test sub-phase to run tests using specified runner.

The test runners supported at the moment are:
 * nose
 * pytest
 * unittest (built-in Python unittest module)

Note that the function appends to IUSE, RESTRICT and BDEPEND. If you modify those variables after calling it, you need to append as well to avoid overwriting the values.

The function also takes care of adding RDEPEND to test- BDEPEND. This works only if it is called after setting RDEPEND.

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 file setting build directories for distutils,
 * 3) * Copies bundled egg-info files to build tree (as required for out-of-source build).
 * 4) Calls  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  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 using the current Python interpreter and standard configuration arguments. The following arguments are passed to, in order:


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

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

distutils_install_for_testing
Usage: distutils_install_for_testing [ ...]

Run 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.