pybuild

pybuild [options] [command [options]]

-p<python_version>, --interpreter=<python_version>
    Specify the Python interpreter version(s) to use (e.g., python3.9, python3, python2). Can be specified multiple times.

-s<buildsystem>, --buildsystem=<buildsystem>
    Force the use of a specific build system (e.g., distutils, setuptools, poetry, flit, pyproject) instead of auto-detection.

--clean
    Perform a clean operation on the source directory before building. This is often implicit with dh_auto_clean.

--dir-path=<directory>
    Specify the source directory containing the Python project to be built. Defaults to the current directory.

--dest-dir=<directory>
    Define the destination directory where built files should be installed. This is typically the package's installation root (e.g., debian/<package>/usr/lib/python3/dist-packages).

--debug
    Enable verbose debug output, showing detailed steps and commands executed by pybuild.

--no-guessing
    Disable automatic build system detection, requiring the build system to be explicitly specified with --buildsystem.

--exclude=<interpreter>
    Exclude specific Python interpreters from the build process. Can be specified multiple times.

--test-arg=<argument>
    Pass additional arguments directly to the test command when the test command is invoked.

--parallel
    Allow building in parallel. This option is passed to the underlying build system if it supports parallel builds.

pybuild is a powerful debhelper tool designed to streamline the creation of Debian Python packages. It effectively abstracts away the complexities of managing multiple Python versions (such as Python 2 and Python 3) and diverse Python build systems (including distutils, setuptools, poetry, and flit). pybuild intelligently detects the appropriate build system and orchestrates a standard sequence of operations (configure, build, install) for each Python interpreter supported by the package.

This significantly simplifies debian/rules files for maintainers, ensuring consistency and adherence to Debian policy for Python applications and libraries. It also handles essential tasks like byte-compilation and the management of .pth files, integrating seamlessly into the dh sequence.

pybuild requires a standard Python project layout with a detectable build system file (e.g., setup.py, pyproject.toml). While it simplifies packaging, highly unconventional build processes may still require custom debian/rules logic.

Incorrectly configured debian/control files (e.g., missing Build-Depends on dh-python or python3-all) can lead to build failures. Its default behavior is to build all detected Python versions unless explicitly excluded, which might not always be desired for minimal builds.

pybuild supports several standard build commands that correspond to phases of a build process: configure, build, install, test, and clean. These commands can be invoked explicitly or implicitly by debhelper sequences (e.g., dh_auto_configure will call pybuild configure).

One of pybuild's key features is its ability to automatically detect the build system of a Python project by examining files like setup.py, pyproject.toml (for poetry, flit, or standard pyproject builds), or other indicators. This reduces configuration effort for maintainers.

pybuild is designed to work seamlessly within the dh (debhelper) sequence. Commands like dh_auto_configure, dh_auto_build, dh_auto_install, dh_auto_test, and dh_auto_clean will automatically invoke pybuild with the appropriate command when a Python package is detected, simplifying debian/rules to a minimal structure.

pybuild was developed to modernize and simplify Python package building within the Debian ecosystem, addressing the challenges posed by the Python 2 to Python 3 transition and the emergence of various Python build tools. Introduced as part of the dh-python package, it aimed to provide a unified and policy-compliant approach, reducing the need for complex, hand-written debian/rules files.

It evolved to support new build systems like Poetry and Flit, adapting to the dynamic landscape of Python development practices and becoming a cornerstone for Python packaging in Debian.

dh(1), dh_auto_build(1), dh_python3(1), dpkg-buildpackage(1)