.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PYBUILD" 1 "" ""
.SH NAME
pybuild \- invokes various build systems for requested Python versions in order to build modules and extensions
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
pybuild [ACTION] [BUILD SYSTEM ARGUMENTS] [DIRECTORIES] [OPTIONS]
.UNINDENT
.UNINDENT
.SH DEBHELPER COMMAND SEQUENCER INTEGRATION
.INDENT 0.0
.IP \(bu 2
build depend on \fIdh\-python\fP,
.IP \(bu 2
build depend on all supported Python interpreters, pybuild will use it to create
a list of interpreters to build for.
Recognized dependencies:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIpython3\-all\-dev\fP \- for Python extensions that work with Python 3.X interpreters,
.IP \(bu 2
\fIpython3\-all\-dbg\fP \- as above, add this one if you\(aqre building \-dbg packages,
.IP \(bu 2
\fIpython3\-all\fP \- for Python modules that work with Python 3.X interpreters,
.IP \(bu 2
\fIpython3\-dev\fP \- builds an extension for default Python 3.X interpreter
(useful for private extensions, use python3\-all\-dev for public ones),
.IP \(bu 2
\fIpython3\fP \- as above, used if headers files are not needed to build private module,
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
add \fI\-\-buildsystem=pybuild\fP to dh\(aqs arguments in debian/rules,
.IP \(bu 2
if more than one binary package is build:
add debian/python3\-foo.install files, or
\fIexport PYBUILD_NAME=modulename\fP (modulename will be used to guess binary
package prefixes), or
\fIexport PYBUILD_DESTDIR\fP env. variables in debian/rules
.IP \(bu 2
add \fI\-\-with=python3\fP to dh\(aqs arguments in debian/rules
(see proper helper\(aqs manpage for more details) or add \fIdh\-sequence\-python3\fP
to Build\-Depends
.UNINDENT
.sp
debian/rules file example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#! /usr/bin/make \-f
export PYBUILD_NAME=foo
%:
       dh $@ \-\-with python3 \-\-buildsystem=pybuild
.EE
.UNINDENT
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.INDENT 3.5
Most options can be set (in addition to command line) via environment
variables. PyBuild will check:
.INDENT 0.0
.IP \(bu 2
PYBUILD_OPTION_VERSIONED_INTERPRETER (f.e. PYBUILD_CLEAN_ARGS_python3.2)
.IP \(bu 2
PYBUILD_OPTION_INTERPRETER (f.e. PYBUILD_CONFIGURE_ARGS_python3\-dbg)
.IP \(bu 2
PYBUILD_OPTION (f.e. PYBUILD_INSTALL_ARGS)
.UNINDENT
.UNINDENT
.UNINDENT
.SS optional arguments
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-v\fP,\fB  \-\-verbose
turn verbose mode on
.TP
.B  \-q\fP,\fB  \-\-quiet
doesn\(aqt show external command\(aqs output
.TP
.BI \-q\fB q\fR,\fB \ \-\-really\-quiet
be quiet
.TP
.B  \-\-version
show program\(aqs version number and exit
.UNINDENT
.UNINDENT
.UNINDENT
.SS ACTION
.INDENT 0.0
.INDENT 3.5
The default is to build, install and test the library using detected build
system version by version. Selecting one of following actions, will invoke
given action for all versions \- one by one \- which (contrary to the default
action) in some build systems can overwrite previous results.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B  \-\-detect
return the name of detected build system
.TP
.B  \-\-clean
clean files using auto\-detected build system specific methods
.TP
.B  \-\-configure
invoke configure step for all requested Python versions
.TP
.B  \-\-build
invoke build step for all requested Python versions
.TP
.B  \-\-install
invoke install step for all requested Python versions
.TP
.B  \-\-test
invoke tests for auto\-detected build system
.TP
.B  \-\-list\-systems
list available build systems and exit
.TP
.B  \-\-print
print pybuild\(aqs internal parameters
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS TESTS
.INDENT 0.0
.INDENT 3.5
unittest\(aqs discover from standard library is used in test step by default.
.INDENT 0.0
.TP
.B  \-\-test\-nose
use nose module in test step, remember to add python3\-nose to
Build\-Depends.
.TP
.B  \-\-test\-nose2
use nose2 module in test step, remember to add python3\-nose2 to
Build\-Depends.
.TP
.B  \-\-test\-pytest
use pytest module in test step, remember to add python3\-pytest
to Build\-Depends.
.TP
.B  \-\-test\-tox
use tox command in test step, remember to add tox to
Build\-Depends.
.TP
.B  \-\-test\-stestr
use stestr command in test step, remember to add python3\-stestr
to Build\-Depends.
.TP
.B  \-\-test\-custom
use a custom command in the test step. The full test command is
then specified with \fI\-\-test\-args\fP or by setting the
\fIPYBUILD_TEST_ARGS\fP environment variable. Remember to add any
needed packages to run the tests to Build\-Depends.
.UNINDENT
.UNINDENT
.UNINDENT
.SS testfiles
.INDENT 0.0
.INDENT 3.5
Tests are invoked from within build directory to make sure newly built
files are tested instead of source files. If test suite requires other files
in this directory, you can list them in \fIdebian/pybuild.testfiles\fP file
(you can also use \fIdebian/pybuild_pythonX.testfiles\fP or
\fIdebian/pybuild_pythonX.Y.testfiles\fP) and files listed there will be copied
before test step and removed before install step.
By default only \fIpyproject.toml\fP and \fIpytest.ini\fP files, and \fItest\fP
and \fItests\fP directories are copied to build directory.
If \fItestfiles\fP are provided, it overrides these defaults, if
still required they need to be explicitly specified.
.UNINDENT
.UNINDENT
.SS BUILD SYSTEM ARGUMENTS
.INDENT 0.0
.INDENT 3.5
Additional arguments passed to the build system.
\-\-system=custom requires complete command in \-\-foo\-args parameters.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-\-before\-clean \ COMMAND
invoked before the clean command
.TP
.BI \-\-clean\-args \ ARGUMENTS
arguments added to clean command generated by build system plugin
.TP
.BI \-\-after\-clean \ COMMAND
invoked after the clean command
.TP
.BI \-\-before\-configure \ COMMAND
invoked before the configure command
.TP
.BI \-\-configure\-args \ ARGUMENTS
arguments added to configure command generated by build system plugin
.TP
.BI \-\-after\-configure \ COMMAND
invoked after the configure command
.TP
.BI \-\-before\-build \ COMMAND
invoked before the build command
.TP
.BI \-\-build\-args \ ARGUMENTS
arguments added to build command generated by build system plugin
.TP
.BI \-\-after\-build \ COMMAND
invoked after the build command
.TP
.BI \-\-before\-install \ COMMAND
invoked before the install command
.TP
.BI \-\-install\-args \ ARGUMENTS
arguments added to install command generated by build system plugin
.TP
.BI \-\-after\-install \ COMMAND
invoked after the install command
.TP
.BI \-\-before\-test \ COMMAND
invoked before the test command
.TP
.BI \-\-test\-args \ ARGUMENTS
arguments added to test command generated by build system plugin
.TP
.BI \-\-after\-test \ COMMAND
invoked after the test command
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS variables that can be used in \fIARGUMENTS\fP and \fICOMMAND\fP
.INDENT 0.0
.IP \(bu 2
\fI{version}\fP will be replaced with current Python version,
you can also use \fI{version.major}\fP, \fI{version.minor}\fP, etc.
.IP \(bu 2
\fI{interpreter}\fP will be replaced with current interpreter,
you can also use \fI{interpreter.include_dir}\fP
.IP \(bu 2
\fI{dir}\fP will be replaced with sources directory,
.IP \(bu 2
\fI{destdir}\fP will be replaced with destination directory,
.IP \(bu 2
\fI{home_dir}\fP will be replaced with temporary HOME directory,
where plugins can keep their data
(.pybuild/interpreter_version/ by default),
.IP \(bu 2
\fI{build_dir}\fP will be replaced with build directory
.IP \(bu 2
\fI{install_dir}\fP will be replaced with install directory.
.IP \(bu 2
\fI{package}\fP will be replaced with suggested package name,
if \-\-name (or PYBUILD_NAME) is set to \fIfoo\fP, this variable
will be replaced with \fIpython3\-foo\fP\&.
.UNINDENT
.SS DIRECTORIES
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-d \ DIR\fR,\fB \ \-\-dir \ DIR
set source files directory \- base for other relative dirs
[by default: current working directory]
.TP
.BI \-\-dest\-dir \ DIR
set destination directory [default: debian/tmp]
.TP
.BI \-\-ext\-dest\-dir \ DIR
set destination directory for .so files
.TP
.BI \-\-ext\-pattern \ PATTERN
regular expression for files that should be moved if \-\-ext\-dest\-dir is set
[default: \fI\&.so(.[^/]*)?$\fP]
.TP
.BI \-\-ext\-sub\-pattern \ PATTERN
regular expression for part of path/filename matched in \-\-ext\-pattern
that should be removed or replaced with \-\-ext\-sub\-repl
.TP
.BI \-\-ext\-sub\-repl \ PATTERN
replacement for matches in \-\-ext\-sub\-pattern
.TP
.BI \-\-install\-dir \ DIR
set installation directory [default: .../dist\-packages]
.TP
.BI \-\-name \ NAME
use this name to guess destination directories
(\(dqfoo\(dq sets debian/python3\-foo)
This overrides \-\-dest\-dir.
.UNINDENT
.UNINDENT
.UNINDENT
.SS variables that can be used in \fIDIR\fP
.INDENT 0.0
.IP \(bu 2
\fI{version}\fP will be replaced with current Python version,
.IP \(bu 2
\fI{interpreter}\fP will be replaced with selected interpreter.
.UNINDENT
.SS LIMITATIONS
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-s \ SYSTEM\fR,\fB \ \-\-system \ SYSTEM
select a build system [default: auto\-detection]
.TP
.BI \-p \ VERSIONS\fR,\fB \ \-\-pyver \ VERSIONS
build for Python VERSIONS. This option can be used multiple times.
Versions can be separated by space character.
The default is all Python 3.X supported versions.
.TP
.BI \-i \ INTERPRETER\fR,\fB \ \-\-interpreter \ INTERPRETER
change interpreter [default: python{version}]
.TP
.BI \-\-disable \ ITEMS
disable action, interpreter, version or any mix of them.
Note that f.e. python3 and python3\-dbg are two different interpreters,
\-\-disable test/python3 doesn\(aqt disable python3\-dbg\(aqs tests.
.UNINDENT
.UNINDENT
.UNINDENT
.SS disable examples
.INDENT 0.0
.IP \(bu 2
\fI\-\-disable test/python3.9\-dbg\fP \- disables tests for python3.9\-dbg
.IP \(bu 2
\fI\-\-disable \(aq3.8 3.9\(aq\fP \- disables all actions for version 3.8 and 3.9
.IP \(bu 2
\fIPYBUILD_DISABLE=python3.9\fP \- disables all actions for Python 3.9
.IP \(bu 2
\fIPYBUILD_DISABLE_python3.3=test\fP \- disables tests for Python 3.3
.IP \(bu 2
\fIPYBUILD_DISABLE=test/python3.3\fP \- same as above
.IP \(bu 2
\fIPYBUILD_DISABLE=configure/python3 3.2\fP \- disables configure
action for all python3 interpreters, and all actions for version 3.2
.UNINDENT
.SS PLUGINS
.sp
pybuild supports multiple build system plugins.  By default it is
automatically selected.  These systems are currently supported:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
* distutils (most commonly used)
* cmake
* flit (deprecated)
* pyproject
* custom
.EE
.UNINDENT
.UNINDENT
.SS flit plugin
.sp
The flit plugin is deprecated, please use the pyproject plugin instead.
.sp
The flit plugin can be used to build Debian packages based on PEP 517
metadata in \fIpyproject.toml\fP when flit is the upstream build system.  These
can be identified by the presence of a \fIbuild\-backend = \(dqflit_core.buildapi\(dq\fP
element in \fIpyproject.toml\fP\&.  The flit plugin only supports python3.  To use
this plugin:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
* build depend on \(gaflit\(ga, and
* add \(gaexport PYBUILD_SYSTEM=flit\(ga to debian/rules to manually select
.EE
.UNINDENT
.UNINDENT
.sp
debian/rules file example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#! /usr/bin/make \-f
export PYBUILD_NAME=foo
export PYBUILD_SYSTEM=flit
%:
    dh $@ \-\-with python3 \-\-buildsystem=pybuild
.EE
.UNINDENT
.UNINDENT
.SS pyproject
.sp
The pyproject plugin drives the new PEP\-517 standard interface for
building Python packages, upstream. This is configured via
\fIpyproject.toml\fP\&.
This plugin is expected to replace the distutils and flit plugins in the
future.
The entry points generated by the package are created during the build step
(other plugins make the entry points during the install step); the entry
points are available in PATH during the test step, permitting them to be
called from tests.
.sp
To use this plugin:
.INDENT 0.0
.IP \(bu 2
build depend on \fIpybuild\-plugin\-pyproject\fP as well as any build tools
specified by upstream in \fIpyproject.toml\fP\&.
.UNINDENT
.SH ENVIRONMENT
.sp
As described above in OPTIONS, pybuild can be configured by \fIPYBUILD_\fP
prefixed environment variables.
.sp
Tests are skipped if \fInocheck\fP is in the \fIDEB_BUILD_OPTIONS\fP or
\fIDEB_BUILD_PROFILES\fP environment variables.
.sp
\fIDESTDIR\fP provides a default a default value to the \fI\-\-dest\-dir\fP option.
.sp
Pybuild will export \fIhttp_proxy=http://127.0.0.1:9/\fP,
\fIhttps_proxy=https://127.0.0.1:9/\fP, and \fIno_proxy=localhost\fP to
hopefully block attempts by the package\(aqs build\-system to access the
Internet.
If network access to a loopback interface is needed and blocked by this,
export empty \fIhttp_proxy\fP and \fIhttps_proxy\fP variables before calling
pybuild.
.sp
If not set, \fILC_ALL\fP, \fICCACHE_DIR\fP, \fIDEB_PYTHON_INSTALL_LAYOUT\fP,
\fI_PYTHON_HOST_PLATFORM\fP, \fI_PYTHON_SYSCONFIGDATA_NAME\fP, will all be set
to appropriate values, before calling the package\(aqs build script.
.SH SEE ALSO
.INDENT 0.0
.IP \(bu 2
dh_python3(1)
.IP \(bu 2
\fI\%https://wiki.debian.org/Python/Pybuild\fP
.IP \(bu 2
\fI\%http://deb.li/pybuild\fP \- most recent version of this document
.UNINDENT
.SH AUTHOR
Piotr Ożarowski, 2012-2019
.\" Generated by docutils manpage writer.
.