DISTUTILS-R1.ECLASS

部分: eclass-manpages (5)
更新: 2024 年 11 月
索引返回主内容

名称

distutils-r1.eclass - 使用 distutils 构建 Python 包的简单 eclass。

描述

一个简单的 eclass，提供使用 distutils 构建系统构建 Python 包的功能。它为所有 src_* 阶段导出阶段函数。每个阶段运行两个伪阶段：python_..._all()（例如 python_prepare_all()）在 ${S} 中运行一次，然后 python_...()（例如 python_prepare()）为每个实现运行一次（参见：python-r1 中的 python_foreach_impl()）。

在 distutils-r1_src_prepare() 中，'all' 函数在每个实现函数之前运行（因为它创建了实现），每个实现函数以随机顺序运行。

在剩余的阶段函数中，每个实现函数在 'all' 函数之前运行，并且它们从最不优选的实现到最优选的实现排序（以便 '更好' 的文件覆盖 '更差' 的文件）。

如果 ebuild 没有指定特定的伪阶段函数，将使用默认函数（distutils-r1_...）。所有每个实现的伪阶段、python_prepare_all() 和 python_install_all() 都提供了默认值；在编写自己的伪阶段函数时，您应该考虑调用默认值（尤其是 distutils-r1_python_prepare_all）。

请注意，distutils-r1 为您无条件地设置了 RDEPEND 和 BDEPEND（或早期 EAP 中的 DEPEND）。

另外，请注意 distutils-r1 将始终继承 python-r1。因此，在那里定义和记录的所有变量都与使用 distutils-r1 的包相关。

有关更多信息，请参阅 Python 指南：https://projects.gentoo.org/python/guide/

支持的 EAP

7 8

可传递提供的 ECLASS

python-r1 python-single-r1

函数

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

为通过 dev-python/sphinx 构建 HTML 文档设置 IUSE、BDEPEND、python_check_deps() 和 python_compile_all()。如果启用了文档，python_compile_all() 将追加到 HTML_DOCS。

此帮助程序适用于最常见的情况，即一个具有标准布局的单个 Sphinx 子目录，在 USE=doc 后构建和安装 HTML 文档。它假设它是上述三个函数的唯一使用者。如果您需要使用自定义实现，则无法使用它。

如果您的包使用其他 Sphinx 插件，则应将它们（不使用 PYTHON_USEDEP）作为 <plugin-pkgs> 传递。该函数将负责设置适当的 any-of 依赖项和 python_check_deps()。

如果未指定插件包，eclass 仍然将使用 any-r1 API 来支持 autodoc（记录源代码）。如果包既不使用 autodoc 也不使用其他插件，您应该传递 --no-autodoc 来禁用此 API 并简化生成的结果代码。

此函数必须在全局范围内调用。注意不要覆盖它设置的变量。如果您需要扩展 python_compile_all()，您可以将原始实现调用为 sphinx_compile_all。

distutils_enable_tests <test-runner>

使用指定的测试运行器设置 IUSE、RESTRICT、BDEPEND 和 python_test() 来运行测试。还会将 RDEPEND 的当前值复制到 test?-BDEPEND。test-runner 参数必须是以下之一

- import-check: `pytest --import-check` 回退（用于没有
测试运行时）

- pytest: dev-python/pytest

- setup.py: setup.py test（不包含依赖项）

- unittest: 用于内置 Python unittest 模块

此函数旨在用作常见用例的帮助程序，它只负责基本设置。您仍然需要手动列出额外的测试依赖项。如果您有非典型用例，则不应使用它，而应手动启用测试。

此函数必须在全局范围内调用，在声明 RDEPEND 后调用。注意不要覆盖它设置的变量。

esetup.py [<args>...]

使用当前选择的 Python 解释器运行 setup.py（如果设置了 ${EPYTHON}；否则回退到 'python'）。

setup.py 将按以下顺序传递以下参数

1. ${DISTUTILS_ARGS[@]}

2. ${mydistutilsargs[@]}（已弃用）

3. 传递给 esetup.py 函数的附加参数。

请注意，setup.py 将尊重 setup.cfg 中的默认值（除非通过命令行选项覆盖），该文件是在 distutils-r1_python_compile 和 distutils-r1_python_install 中创建的。

此命令在失败时退出。

distutils_install_for_testing

此函数用于提供已安装的软件包以运行测试。它不再实现，必须使用 PEP517 模式。

distutils_write_namespace <namespace>...

将请求的命名空间的 __init__.py 文件写入 PEP517 安装树，以解决在安装旧式命名空间包（dev-python/namespace-*）时运行测试的问题。

此函数只能在 python_test() 中使用。创建的文件将在离开测试阶段时自动删除。

distutils-r1_python_prepare_all

默认的 python_prepare_all()。它应用 PATCHES 数组中的补丁，然后应用用户补丁，最后调用 python_copy_sources 为每个 Python 实现创建结果源的副本。

将来，它也可能会应用特定于 eclass 的 distutils 补丁和/或特性。

distutils_wheel_install <root> <wheel>

将指定的轮子安装到 <root> 中。

此函数仅供专家使用。

DISTUTILS_WHEEL_PATH

由 distutils_pep517_install 创建的轮子的路径。

distutils_pep517_install <root>

使用 PEP517 后端构建当前目录中包的轮子，并将其安装到 <root> 中。

此函数仅供专家使用。它不处理包装可执行文件。轮子路径在 DISTUTILS_WHEEL_PATH 变量中返回。

DISTUTILS_WHEELS = ()

作为 distutils-r1_python_compile 调用结果创建的轮子的关联数组，映射到源目录。注意，这仅包括由 eclass 隐式创建的轮子，不包括作为 distutils_pep517_install 在 ebuild 中的直接调用结果创建的轮子。

distutils-r1_python_compile [additional-args...]

默认的 python_compile()。

如果 DISTUTILS_USE_PEP517 设置为 "no"，则为无操作。

如果 DISTUTILS_USE_PEP517 设置为任何其他值，则使用 PEP517 后端构建轮子并将其安装到 ${BUILD_DIR}/install 中。轮子的路径随后将添加到 DISTUTILS_WHEELS 数组中。

在旧式模式下，运行 'esetup.py build'。传递给此函数的任何参数都将附加到 setup.py 调用中，即作为 'build' 命令的选项传递。

distutils-r1_python_test [additional-args...]

distutils_enable_tests 使用的 python_test() 实现。使用指定的测试运行器运行测试，可能首先安装它们。

此函数仅在调用 distutils_enable_tests 时使用。

distutils-r1_python_install [additional-args...]

默认的 python_install()。

在 PEP517 模式下，将 ${BUILD_DIR}/install（如果存在）中的文件合并到映像目录中。

在旧式模式下，调用 `esetup.py install` 来安装包。传递给此函数的任何参数都将附加到 setup.py 调用中（即作为 'install' 命令的选项）。

distutils-r1_python_install_all

默认的 python_install_all()。它安装文档。

ECLASS 变量

DISTUTILS_EXT（在 INHERIT 之前设置）

如果包（可能可选地）构建 Python 扩展（用 C、Cython、Rust 等编写的可加载模块），则将此变量设置为非空值。

启用后，eclass 将

- 将 PYTHON_DEPS 添加到 DEPEND（用于交叉编译支持），除非
DISTUTILS_OPTIONAL 使用

- 将 `debug` 标志添加到 IUSE，以控制断言（即 -DNDEBUG）

- 如果使用 setuptools 构建后端，则调用 `build_ext` 命令
并且存在来自并行构建的潜在好处

DISTUTILS_OPTIONAL

如果设置为非空值，则 ebuild 中的 distutils 部分将被视为可选。不会添加任何依赖项，也不会导出任何阶段函数。

如果您启用了 DISTUTILS_OPTIONAL，您必须为您的包设置适当的依赖项（使用 ${PYTHON_DEPS}），并且要么调用 distutils-r1 默认阶段函数，要么手动调用构建系统。

注意，如果使用 DISTUTILS_SINGLE_IMPL，python-single-r1 将导出 pkg_setup() 函数。在这种情况下，有必要重新定义 pkg_setup() 以在正确条件下调用 python-single-r1_pkg_setup。

DISTUTILS_SINGLE_IMPL

如果设置为非空值，则 ebuild 将仅支持设置单个 Python 实现。它将有效地用 python-single-r1 替换 python-r1 eclass 继承。

注意，继承 python-single-r1 将导致导出 pkg_setup()。必须运行它才能使 eclass 函数正常运行。

DISTUTILS_USE_PEP517（在 INHERIT 之前设置）

为指定的构建系统启用 PEP517 模式。在此模式下，完整的构建和安装在 python_compile() 中完成，一个 venv 样式的安装树提供给 python_test()，python_install() 只是将临时安装树合并到实际文件系统中。

此模式推荐用于 Python 包。但是，某些在 distutils/setuptools 之上使用自定义技巧的包可能无法在此模式下正确安装。使用时请验证已安装文件的列表。

该变量指定使用的构建系统。目前，支持以下值

- flit - flit-core 后端

- flit_scm - flit_scm 后端

- hatchling - hatchling 后端（来自 hatch）

- jupyter - jupyter_packaging 后端

- maturin - maturin 后端

- meson-python - meson-python (mesonpy) 后端

- no - 无 PEP517 构建系统（见下文）

- pbr - pbr 后端

- pdm-backend - pdm.backend 后端

- poetry - poetry-core 后端

- scikit-build-core - scikit-build-core 后端

- setuptools - distutils 或 setuptools（包括旧式模式）

- sip - sipbuild 后端

- standalone - 无外部依赖项的独立构建系统
(用于引导)。

该变量需要在 inherit 行之前设置。eclass 将添加适当的构建时依赖项并验证该值。

特殊值 "no" 表示该软件包没有构建系统。这与未设置 DISTUTILS_USE_PEP517（传统模式）不同。它会导致 eclass 不包含任何构建系统依赖项，并禁用默认的 python_compile() 和 python_install() 实现。基础 Python 依赖项和阶段函数仍然会设置（取决于 DISTUTILS_OPTIONAL 的值）。大多数其他 eclass 函数将正常工作。测试 venv 将在 python_compile() 后提供在 ${BUILD_DIR}/install 中，如果 python_install() 后在 ${BUILD_DIR}/install 中找到任何（其他）文件，它们将被合并到 ${D} 中。

DISTUTILS_USE_SETUPTOOLS（在继承之前设置）

控制添加 dev-python/setuptools 依赖项。允许的值为

- no -- 不添加依赖项（纯 distutils 软件包）

- bdepend -- 将其添加到 BDEPEND（默认值）

- rdepend -- 将其添加到 BDEPEND+RDEPEND（例如，当使用 pkg_resources 时）

- manual -- 不添加依赖项并抑制检查
(假设您会正确地处理它)

此变量仅在 DISTUTILS_OPTIONAL 被禁用时有效。它仅在非 PEP517 模式下可用。它需要在 inherit 行之前设置。

DISTUTILS_DEPS（由 ECLASS 生成）

这是一个由 eclass 生成的构建系统包的构建时依赖项字符串。除非使用 DISTUTILS_OPTIONAL，否则此字符串将自动附加到 BDEPEND。此变量仅在 PEP517 模式下可用。

示例用法

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

DISTUTILS_ALLOW_WHEEL_REUSE = 1}（用户变量）

如果设置为非空值，eclass 允许重用为先前 Python 实现构建的轮子，前提是它与当前实现兼容，而不是构建新的轮子。

这是一种优化，可以避免在纯 Python 软件包和使用稳定 Python ABI 的软件包中调用构建系统的开销。

BUILD_DIR（由 ECLASS 生成）

当前构建目录。在全局范围内，它应该包含一个初始构建目录；如果未设置，则默认为 ${S}。

在多实现模式下运行时，BUILD_DIR 变量由 python-r1.eclass 设置。否则，它由 distutils-r1.eclass 设置以保持一致性。

示例值

${WORKDIR}/foo-1.3-python3_12

DISTUTILS_IN_SOURCE_BUILD

如果设置为非空值，将启用源代码内构建。如果未设置，则默认情况下，如果声明了 python_prepare()，则使用源代码内构建，否则使用源代码外构建。

如果使用源代码内构建，eclass 将在 python_prepare_all() 中为每个 Python 实现创建软件包源的副本，并在之后处理该副本。

如果使用源代码外构建，eclass 将直接处理源代码，在 setup.py 参数前添加 'build --build-base ${BUILD_DIR}' 以强制在特定根目录中保留和使用构建文件。

源代码内构建已弃用，在 PEP517 模式下不再受支持。

DISTUTILS_ALL_SUBPHASE_IMPLS

一个包含模式的数组，指定哪些实现可用于 *_all() 子阶段函数。如果未定义，则默认为 '*'（允许任何实现）。如果指定了多个值，则与任何模式匹配的实现都将被接受。

有关模式语法的详细信息，请参阅 python-utils-r1.eclass 中的 _python_impl_matches。

如果限制需要有条件地应用于 USE 标志，则变量也应有条件地设置（例如，在早期阶段函数或其他方便的位置）。

请记住向 REQUIRED_USE 添加一个匹配的 || 块，以确保至少启用一个与模式匹配的实现。

示例

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

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

DISTUTILS_ARGS

一个包含要传递给构建系统的选项的数组。由 eclass 使用的构建系统子集支持。

对于 maturin，这些参数将作为 `maturin build` 参数传递。

对于 meson-python，这些参数将作为 `meson setup` 参数传递。

对于 scikit-build-core，这些参数将作为 `cmake` 选项传递（例如，应使用 `-DFOO=BAR` 形式）。

对于 setuptools，这些参数将作为 setup.py 调用的第一个参数（通过 esetup.py）以及 PEP517 后端传递。为了保持未来兼容性，应该只使用全局选项，避免指定命令。

对于 sip，这些选项以类似于 sip-build 调用的形式传递给 PEP517 后端。带有参数的选项需要以 “--key=value” 形式指定，而标志选项则以 “--key” 形式指定。如果一个选项接受多个参数，则可以多次指定它，与 sip-build 相同。

示例

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

作者

作者：Michał Górny <[email protected]>
基于以下人员的工作：Krzysztof Pawlik <[email protected]>

维护者

Python 团队 <[email protected]>

报告错误

请通过 https://bugs.gentoo.org/ 报告错误。

文件

distutils-r1.eclass

另请参阅

ebuild(5)
https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/distutils-r1.eclass

此文档由 man2html 使用手册页创建。
时间：2024 年 11 月 12 日，格林威治标准时间 03:27:01