summaryrefslogtreecommitdiff
path: root/pybuild.rst
blob: 0f51a0a329a1ddf99a41d5f5f7a542c3425b659a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
=========
 pybuild
=========

----------------------------------------------------------------------------------------------------
invokes various build systems for requested Python versions in order to build modules and extensions
----------------------------------------------------------------------------------------------------

:Manual section: 1
:Author: Piotr O┼╝arowski, 2012-2013

SYNOPSIS
========
  pybuild [ACTION] [BUILD SYSTEM ARGUMENTS] [DIRECTORIES] [OPTIONS]

DEBHELPER COMMAND SEQUENCER INTEGRATION
=======================================
* build depend on `dh-python`,
* build depend on `python3-all`, `python-all-dbg`, `pypy`, etc.
  (for all supported Python interpreters, pybuild will use it to create
  a list of interpreters to build for),
* add `--buildsystem=pybuild` to dh's arguments in debian/rules,
* if more than one binary package is build:
  add debian/python-foo.install files, or
  `export PYBUILD_NAME=modulename` (modulename will be used to guess binary
  package prefixes), or
  `export PYBUILD_DESTDIR` env. variables in debian/rules

debian/rules file example::

 #! /usr/bin/make -f
 export PYBUILD_NAME=foo
 %:
  	dh $@ --with python2,python3 --buildsystem=pybuild

OPTIONS
=======
  Most options can be set (in addition to command line) via environment
  variables. PyBuild will check:

  * PYBUILD_OPTION_VERSIONED_INTERPRETER (f.e. PYBUILD_CLEAN_ARGS_python3.2)
  * PYBUILD_OPTION_INTERPRETER (f.e. PYBUILD_CONFIGURE_ARGS_python3-dbg)
  * PYBUILD_OPTION (f.e. PYBUILD_INSTALL_ARGS)

optional arguments
------------------
  -h, --help            show this help message and exit
  -v, --verbose         turn verbose mode on
  -q, --quiet           doesn't show external command's output
  -qq, --really-quiet   be quiet
  --version             show program's version number and exit

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

    --detect
        return the name of detected build system
    --clean
        clean files using auto-detected build system specific methods
    --configure
        invoke configure step for all requested Python versions
    --build
        invoke build step for all requested Python versions
    --install
        invoke install step for all requested Python versions
    --test
        invoke tests for auto-detected build system
    --list-systems
        list available build systems and exit

TESTS
-----
    unittest's discover from standard library (available in Python 2.7 and
    >= 3.2) is used in test step by default.

    --test-nose
        use nose module in test step, remember to add python-nose and/or
        python3-nose to Build-Depends
    --test-pytest
        use pytest module in test step, remember to add python-pytest and/or
        python3-pytest to Build-Depends
    --test-tox
        use tox command in test step, remember to add python-tox
        to Build-Depends. Requires tox.ini file

BUILD SYSTEM ARGUMENTS
----------------------
  Additional arguments passed to the build system.
  --system=custom requires complete command.

    --before-clean COMMAND
        invoked before the clean command
    --clean-args ARGUMENTS
        arguments added to clean command generated by build system plugin
    --after-clean COMMAND
        invoked after the clean command
    --before-configure COMMAND
        invoked before the configure command
    --configure-args ARGUMENTS
        arguments added to configure command generated by build system plugin
    --after-configure COMMAND
        invoked after the configure command
    --before-build COMMAND
        invoked before the build command
    --build-args ARGUMENTS
        arguments added to build command generated by build system plugin
    --after-build COMMAND
        invoked after the build command
    --before-install COMMAND
        invoked before the install command
    --install-args ARGUMENTS
        arguments added to install command generated by build system plugin
    --after-install COMMAND
        invoked after the install command
    --before-test COMMAND
        invoked before the test command
    --test-args ARGUMENTS
        arguments added to test command generated by build system plugin
    --after-test COMMAND
        invoked after the test command

variables that can be used in `ARGUMENTS` and `COMMAND`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* `{version}` will be replaced with current Python version,
  you can also use `{version.major}`, `{version.minor}`, etc.
* `{interpreter}` will be replaced with current interpreter,
  you can also use `{interpreter.include_dir}`
* `{dir}` will be replaced with sources directory,
* `{destdir}` will be replaced with destination directory,
* `{home_dir}` will be replaced with temporary HOME directory,
  where plugins can keep their data
  (.pybuild/interpreter_version/ by default),
* `{build_dir}` will be replaced with build directory
* `{install_dir}` will be replaced with install directory.
* `{package}` will be replaced with suggested package name,
  if --name (or PYBUILD_NAME) is set to `foo`, this variable
  will be replaced to `python-foo`, `python3-foo` or `pypy-foo`
  depending on interpreter which is used in given iteration.

DIRECTORIES
-----------
  -d DIR, --dir DIR
      set source files directory - base for other relative dirs
      [by default: current working directory]
  --dest-dir DIR
      set destination directory [default: debian/tmp]
  --ext-dest-dir DIR
      set destination directory for .so files
  --ext-pattern PATTERN
      regular expression for files that should be moved if --ext-destdir is set
      [default: `\.so(\.[^/]*)?$`]
  --install-dir DIR
      set installation directory [default: .../dist-packages]
  --name NAME
      use this name to guess destination directories
      (depending on interpreter, "foo" sets debian/python-foo,
      debian/python3-foo, debian/python3-foo-dbg, etc.)

variables that can be used in `DIR`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* `{version}` will be replaced with current Python version,
* `{interpreter}` will be replaced with selected interpreter.

LIMITATIONS
-----------
  -s SYSTEM, --system SYSTEM
	select a build system [default: auto-detection]
  -p VERSIONS, --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.
  -i INTERPRETER, --interpreter INTERPRETER
	change interpreter [default: python{version}]
  --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't disable python3-dbg's tests.

disable examples
~~~~~~~~~~~~~~~~
* `--disable test/python2.5-dbg` - disables tests for python2.5-dbg
* `--disable '2.4 2.7'` - disables all actions for version 2.4 and 2.7
* `PYBUILD_DISABLE_python2=1` - disables all actions for Python 2.X
* `PYBUILD_DISABLE_python3.3=test` - disables tests for Python 3.3
* `PYBUILD_DISABLE=test/python3.3` - same as above
* `PYBUILD_DISABLE=configure/python3 2.4 pypy` - disables configure
  action for all python3 interpreters, all actions for version 2.4, and
  all actions for pypy

SEE ALSO
========
* dh_python2(1)
* dh_python3(1)
* https://wiki.debian.org/Python/Pybuild
* http://deb.li/pybuild - most recent version of this document