DISTUTILS-R1.ECLASS

Section: eclass-manpages (5)
Updated: Jun 2024
Index Return to Main Contents

NAME

distutils-r1.eclass - A simple eclass to build Python packages using distutils.

DESCRIPTION

A simple eclass providing functions to build Python packages using the distutils build system. It exports phase functions for all the src_* phases. Each of the phases runs two pseudo-phases: python_..._all() (e.g. python_prepare_all()) once in ${S}, then python_...() (e.g. python_prepare()) for each implementation (see: python_foreach_impl() in python-r1).

In distutils-r1_src_prepare(), the 'all' function is run before per-implementation ones (because it creates the implementations), per-implementation functions are run in a random order.

In remaining phase functions, the per-implementation functions are run before the 'all' one, and they are ordered from the least to the most preferred implementation (so that 'better' files overwrite 'worse' ones).

If the ebuild doesn't specify a particular pseudo-phase function, the default one will be used (distutils-r1_...). Defaults are provided for all per-implementation pseudo-phases, python_prepare_all() and python_install_all(); whenever writing your own pseudo-phase functions, you should consider calling the defaults (and especially distutils-r1_python_prepare_all).

Please note that distutils-r1 sets RDEPEND and BDEPEND (or DEPEND in earlier EAPIs) unconditionally for you.

Also, please note that distutils-r1 will always inherit python-r1 as well. Thus, all the variables defined and documented there are relevant to the packages using distutils-r1.

For more information, please see the Python Guide: https://projects.gentoo.org/python/guide/

SUPPORTED EAPIS

7 8

TRANSITIVELY PROVIDED ECLASSES

python-r1 python-single-r1

FUNCTIONS

distutils_enable_sphinx <subdir> [--no-autodoc | <plugin-pkgs>...]

Set up IUSE, BDEPEND, python_check_deps() and python_compile_all() for building HTML docs via dev-python/sphinx. python_compile_all() will append to HTML_DOCS if docs are enabled.

This helper is meant for the most common case, that is a single Sphinx subdirectory with standard layout, building and installing HTML docs behind USE=doc. It assumes it's the only consumer of the three aforementioned functions. If you need to use a custom implementation, you can't use it.

If your package uses additional Sphinx plugins, they should be passed (without PYTHON_USEDEP) as <plugin-pkgs>. The function will take care of setting appropriate any-of dep and python_check_deps().

If no plugin packages are specified, the eclass will still utilize any-r1 API to support autodoc (documenting source code). If the package uses neither autodoc nor additional plugins, you should pass --no-autodoc to disable this API and simplify the resulting code.

This function must be called in global scope. Take care not to overwrite the variables set by it. If you need to extend python_compile_all(), you can call the original implementation as sphinx_compile_all.

distutils_enable_tests <test-runner>

Set up IUSE, RESTRICT, BDEPEND and python_test() for running tests with the specified test runner. Also copies the current value of RDEPEND to test?-BDEPEND. The test-runner argument must be one of:

- pytest: dev-python/pytest

- setup.py: setup.py test (no deps included)

- unittest: for built-in Python unittest module

This function is meant as a helper for common use cases, and it only takes care of basic setup. You still need to list additional test dependencies manually. If you have uncommon use case, you should not use it and instead enable tests manually.

This function must be called in global scope, after RDEPEND has been declared. Take care not to overwrite the variables set by it.

esetup.py [<args>...]

Run setup.py using currently selected Python interpreter (if ${EPYTHON} is set; fallback 'python' otherwise).

setup.py will be passed the following, in order:

1. ${DISTUTILS_ARGS[@]}

2. ${mydistutilsargs[@]} (deprecated)

3. additional arguments passed to the esetup.py function.

Please note that setup.py will respect defaults (unless overridden via command-line options) from setup.cfg that is created in distutils-r1_python_compile and in distutils-r1_python_install.

This command dies on failure.

distutils_install_for_testing

This function used to provide an installed package for running tests. It is no longer implemented, PEP517 mode must be used instead.

distutils_write_namespace <namespace>...

Write the __init__.py file for the requested namespace into PEP517 install tree, in order to fix running tests when legacy namespace packages are installed (dev-python/namespace-*).

This function must only be used in python_test(). The created file will automatically be removed upon leaving the test phase.

distutils-r1_python_prepare_all

The default python_prepare_all(). It applies the patches from PATCHES array, then user patches and finally calls python_copy_sources to create copies of resulting sources for each Python implementation.

At some point in the future, it may also apply eclass-specific distutils patches and/or quirks.

distutils_wheel_install <root> <wheel>

Install the specified wheel into <root>.

This function is intended for expert use only.

DISTUTILS_WHEEL_PATH

Path to the wheel created by distutils_pep517_install.

distutils_pep517_install <root>

Build the wheel for the package in the current directory using PEP517 backend and install it into <root>.

This function is intended for expert use only. It does not handle wrapping executables. The wheel path is returned in DISTUTILS_WHEEL_PATH variable.

DISTUTILS_WHEELS = ()

An associative array of wheels created as a result of distutils-r1_python_compile invocations, mapped to the source directories. Note that this includes only wheels implicitly created by the eclass, and not wheels created as a result of direct distutils_pep517_install calls in the ebuild.

distutils-r1_python_compile [additional-args...]

The default python_compile().

If DISTUTILS_USE_PEP517 is set to "no", a no-op.

If DISTUTILS_USE_PEP517 is set to any other value, builds a wheel using the PEP517 backend and installs it into ${BUILD_DIR}/install. Path to the wheel is then added to DISTUTILS_WHEELS array.

In legacy mode, runs 'esetup.py build'. Any parameters passed to this function will be appended to setup.py invocation, i.e. passed as options to the 'build' command.

distutils-r1_python_test [additional-args...]

The python_test() implementation used by distutils_enable_tests. Runs tests using the specified test runner, possibly installing them first.

This function is used only if distutils_enable_tests is called.

distutils-r1_python_install [additional-args...]

The default python_install().

In PEP517 mode, merges the files from ${BUILD_DIR}/install (if present) to the image directory.

In the legacy mode, calls `esetup.py install` to install the package. Any parameters passed to this function will be appended to the setup.py invocation (i.e. as options to the 'install' command).

distutils-r1_python_install_all

The default python_install_all(). It installs the documentation.

ECLASS VARIABLES

DISTUTILS_EXT (SET BEFORE INHERIT)

Set this variable to a non-null value if the package (possibly optionally) builds Python extensions (loadable modules written in C, Cython, Rust, etc.).

When enabled, the eclass:

- adds PYTHON_DEPS to DEPEND (for cross-compilation support), unless
DISTUTILS_OPTIONAL is used

- adds `debug` flag to IUSE that controls assertions (i.e. -DNDEBUG)

- calls `build_ext` command if setuptools build backend is used
and there is potential benefit from parallel builds

DISTUTILS_OPTIONAL

If set to a non-null value, distutils part in the ebuild will be considered optional. No dependencies will be added and no phase functions will be exported.

If you enable DISTUTILS_OPTIONAL, you have to set proper dependencies for your package (using ${PYTHON_DEPS}) and to either call distutils-r1 default phase functions or call the build system manually.

Note that if DISTUTILS_SINGLE_IMPL is used, python-single-r1 exports pkg_setup() function. In that case, it is necessary to redefine pkg_setup() to call python-single-r1_pkg_setup over correct conditions.

DISTUTILS_SINGLE_IMPL

If set to a non-null value, the ebuild will support setting a single Python implementation only. It will effectively replace the python-r1 eclass inherit with python-single-r1.

Note that inheriting python-single-r1 will cause pkg_setup() to be exported. It must be run in order for the eclass functions to function properly.

DISTUTILS_USE_PEP517 (SET BEFORE INHERIT)

Enable the PEP517 mode for the specified build system. In this mode, the complete build and install is done in python_compile(), a venv-style install tree is provided to python_test(), and python_install() just merges the temporary install tree into the real fs.

This mode is recommended for Python packages. However, some packages using custom hacks on top of distutils/setuptools may not install correctly in this mode. Please verify the list of installed files when using it.

The variable specifies the build system used. Currently, the following values are supported:

- flit - flit-core backend

- flit_scm - flit_scm backend

- hatchling - hatchling backend (from hatch)

- jupyter - jupyter_packaging backend

- maturin - maturin backend

- meson-python - meson-python (mesonpy) backend

- no - no PEP517 build system (see below)

- pbr - pbr backend

- pdm-backend - pdm.backend backend

- poetry - poetry-core backend

- scikit-build-core - scikit-build-core backend

- setuptools - distutils or setuptools (incl. legacy mode)

- sip - sipbuild backend

- standalone - standalone build systems without external deps
(used for bootstrapping).

The variable needs to be set before the inherit line. The eclass adds appropriate build-time dependencies and verifies the value.

The special value "no" indicates that the package has no build system. This is not equivalent to unset DISTUTILS_USE_PEP517 (legacy mode). It causes the eclass not to include any build system dependencies and to disable default python_compile() and python_install() implementations. Baseline Python deps and phase functions will still be set (depending on the value of DISTUTILS_OPTIONAL). Most of the other eclass functions will work. Testing venv will be provided in ${BUILD_DIR}/install after python_compile(), and if any (other) files are found in ${BUILD_DIR}/install after python_install(), they will be merged into ${D}.

DISTUTILS_USE_SETUPTOOLS (SET BEFORE INHERIT)

Controls adding dev-python/setuptools dependency. The allowed values are:

- no -- do not add the dependency (pure distutils package)

- bdepend -- add it to BDEPEND (the default)

- rdepend -- add it to BDEPEND+RDEPEND (e.g. when using pkg_resources)

- manual -- do not add the dependency and suppress the checks
(assumes you will take care of doing it correctly)

This variable is effective only if DISTUTILS_OPTIONAL is disabled. It is available only in non-PEP517 mode. It needs to be set before the inherit line.

DISTUTILS_DEPS (GENERATED BY ECLASS)

This is an eclass-generated build-time dependency string for the build system packages. This string is automatically appended to BDEPEND unless DISTUTILS_OPTIONAL is used. This variable is available only in PEP517 mode.

Example use:

DISTUTILS_OPTIONAL=1
# ...
RDEPEND="${PYTHON_DEPS}"
BDEPEND="
    ${PYTHON_DEPS}
    ${DISTUTILS_DEPS}"

DISTUTILS_ALLOW_WHEEL_REUSE (USER VARIABLE)

If set to a non-empty value, the eclass is allowed to reuse a wheel that was built for a prior Python implementation, provided that it is compatible with the current one, rather than building a new one.

This is an optimization that can avoid the overhead of calling into the build system in pure Python packages and packages using the stable Python ABI.

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

When running in multi-impl mode, the BUILD_DIR variable is set by python-r1.eclass. Otherwise, it is set by distutils-r1.eclass for consistency.

Example value:

${WORKDIR}/foo-1.3-python3_12

DISTUTILS_IN_SOURCE_BUILD

If set to a non-null value, in-source builds will be enabled. If unset, the default is to use in-source builds when python_prepare() is declared, and out-of-source builds otherwise.

If in-source builds are used, the eclass will create a copy of package sources for each Python implementation in python_prepare_all(), and work on that copy afterwards.

If out-of-source builds are used, the eclass will instead work on the sources directly, prepending setup.py arguments with 'build --build-base ${BUILD_DIR}' to enforce keeping & using built files in the specific root.

In-source builds are deprecated and no longer supported in PEP517 mode.

DISTUTILS_ALL_SUBPHASE_IMPLS

An array of patterns specifying which implementations can be used for *_all() sub-phase functions. If undefined, defaults to '*' (allowing any implementation). If multiple values are specified, implementations matching any of the patterns will be accepted.

For the pattern syntax, please see _python_impl_matches in python-utils-r1.eclass.

If the restriction needs to apply conditionally to a USE flag, the variable should be set conditionally as well (e.g. in an early phase function or other convenient location).

Please remember to add a matching || block to REQUIRED_USE, to ensure that at least one implementation matching the patterns will be enabled.

Example:

REQUIRED_USE="doc? ( || ( $(python_gen_useflags 'python2*') ) )"

pkg_setup() {
    use doc && DISTUTILS_ALL_SUBPHASE_IMPLS=( 'python2*' )
}

DISTUTILS_ARGS

An array containing options to be passed to the build system. Supported by a subset of build systems used by the eclass.

For maturin, the arguments will be passed as `maturin build` arguments.

For meson-python, the arguments will be passed as `meson setup` arguments.

For scikit-build-core, the arguments will be passed as `cmake` options (e.g. `-DFOO=BAR` form should be used).

For setuptools, the arguments will be passed as first parameters to setup.py invocations (via esetup.py), as well as to the PEP517 backend. For future compatibility, only global options should be used and specifying commands should be avoided.

For sip, the options are passed to the PEP517 backend in a form resembling sip-build calls. Options taking arguments need to be specified in the "--key=value" form, while flag options as "--key". If an option takes multiple arguments, it can be specified multiple times, same as for sip-build.

Example:

python_configure_all() {
        DISTUTILS_ARGS=( --enable-my-hidden-option )
}

AUTHORS

Author: Michał Górny <mgorny@gentoo.org>
Based on the work of: Krzysztof Pawlik <nelchael@gentoo.org>

MAINTAINERS

Python team <python@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

distutils-r1.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, June 29, 2024