docs/manual/adding-packages-python.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for Python packages
   5
   6 This infrastructure applies to Python packages that use the standard
   7 Python setuptools mechanism as their build system, generally
   8 recognizable by the usage of a +setup.py+ script.
   9
  10 [[python-package-tutorial]]
  11
  12 ==== +python-package+ tutorial
  13
  14 First, let's see how to write a +.mk+ file for a Python package,
  15 with an example :
  16
  17 ------------------------
  18 01: ################################################################################
  19 02: #
  20 03: # python-foo
  21 04: #
  22 05: ################################################################################
  23 06:
  24 07: PYTHON_FOO_VERSION = 1.0
  25 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
  26 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
  27 10: PYTHON_FOO_LICENSE = BSD-3c
  28 11: PYTHON_FOO_LICENSE_FILES = LICENSE
  29 12: PYTHON_FOO_ENV = SOME_VAR=1
  30 13: PYTHON_FOO_DEPENDENCIES = libmad
  31 14: PYTHON_FOO_SETUP_TYPE = distutils
  32 15:
  33 16: $(eval $(python-package))
  34 ------------------------
  35
  36 On line 7, we declare the version of the package.
  37
  38 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  39 recommended) and the location of the tarball on the Web. Buildroot
  40 will automatically download the tarball from this location.
  41
  42 On line 10 and 11, we give licensing details about the package (its
  43 license on line 10, and the file containing the license text on line
  44 11).
  45
  46 On line 12, we tell Buildroot to pass custom options to the Python
  47 +setup.py+ script when it is configuring the package.
  48
  49 On line 13, we declare our dependencies, so that they are built
  50 before the build process of our package starts.
  51
  52 On line 14, we declare the specific Python build system being used. In
  53 this case the +distutils+ Python build system is used. The two
  54 supported ones are +distutils+ and +setuptools+.
  55
  56 Finally, on line 16, we invoke the +python-package+ macro that
  57 generates all the Makefile rules that actually allow the package to be
  58 built.
  59
  60 [[python-package-reference]]
  61
  62 ==== +python-package+ reference
  63
  64 As a policy, packages that merely provide Python modules should all be
  65 named +python-<something>+ in Buildroot. Other packages that use the
  66 Python build system, but are not Python modules, can freely choose
  67 their name (existing examples in Buildroot are +scons+ and
  68 +supervisor+).
  69
  70 In their +Config.in+ file, they should depend on +BR2_PACKAGE_PYTHON+
  71 so that when Buildroot will enable Python 3 usage for modules, we will
  72 be able to enable Python modules progressively on Python 3.
  73
  74 The main macro of the Python package infrastructure is
  75 +python-package+. It is similar to the +generic-package+ macro. It is
  76 also possible to create Python host packages with the
  77 +host-python-package+ macro.
  78
  79 Just like the generic infrastructure, the Python infrastructure works
  80 by defining a number of variables before calling the +python-package+
  81 or +host-python-package+ macros.
  82
  83 All the package metadata information variables that exist in the
  84 xref:generic-package-reference[generic package infrastructure] also
  85 exist in the Python infrastructure: +PYTHON_FOO_VERSION+,
  86 +PYTHON_FOO_SOURCE+, +PYTHON_FOO_PATCH+, +PYTHON_FOO_SITE+,
  87 +PYTHON_FOO_SUBDIR+, +PYTHON_FOO_DEPENDENCIES+, +PYTHON_FOO_LICENSE+,
  88 +PYTHON_FOO_LICENSE_FILES+, +PYTHON_FOO_INSTALL_STAGING+, etc.
  89
  90 Note that:
  91
  92  * It is not necessary to add +python+ or +host-python+ in the
  93    +PYTHON_FOO_DEPENDENCIES+ variable of a package, since these basic
  94    dependencies are automatically added as needed by the Python
  95    package infrastructure.
  96
  97  * Similarly, it is not needed to add +host-setuptools+ and/or
  98    +host-distutilscross+ dependencies to +PYTHON_FOO_DEPENDENCIES+ for
  99    setuptools-based packages, since these are automatically added by
 100    the Python infrastructure as needed.
 101
 102 One variable specific to the Python infrastructure is mandatory:
 103
 104 * +PYTHON_FOO_SETUP_TYPE+, to define which Python build system is used
 105   by the package. The two supported values are +distutils+ and
 106   +setuptools+. If you don't know which one is used in your package,
 107   look at the +setup.py+ file in your package source code, and see
 108   whether it imports things from the +distutils+ module or the
 109   +setuptools+ module.
 110
 111 A few additional variables, specific to the Python infrastructure, can
 112 optionally be defined, depending on the package's needs. Many of them
 113 are only useful in very specific cases, typical packages will
 114 therefore only use a few of them, or none.
 115
 116 * +PYTHON_FOO_ENV+, to specify additional environment variables to
 117   pass to the Python +setup.py+ script (for both the build and install
 118   steps). Note that the infrastructure is automatically passing
 119   several standard variables, defined in +PKG_PYTHON_DISTUTILS_ENV+
 120   (for distutils target packages), +HOST_PKG_PYTHON_DISTUTILS_ENV+
 121   (for distutils host packages), +PKG_PYTHON_SETUPTOOLS_ENV+ (for
 122   setuptools target packages) and +HOST_PKG_PYTHON_SETUPTOOLS_ENV+
 123   (for setuptools host packages).
 124
 125 * +PYTHON_FOO_BUILD_OPTS+, to specify additional options to pass to the
 126   Python +setup.py+ script during the build step. For target distutils
 127   packages, the +PKG_PYTHON_DISTUTILS_BUILD_OPTS+ options are already
 128   passed automatically by the infrastructure.
 129
 130 * +PYTHON_FOO_INSTALL_TARGET_OPTS+, +PYTHON_FOO_INSTALL_STAGING_OPTS+,
 131   +HOST_PYTHON_FOO_INSTALL_OPTS+ to specify additional options to pass
 132   to the Python +setup.py+ script during the target installation step,
 133   the staging installation step or the host installation,
 134   respectively. Note that the infrastructure is automatically passing
 135   some options, defined in +PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS+
 136   or +PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS+ (for target distutils
 137   packages), +HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS+ (for host
 138   distutils packages), +PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS+ or
 139   +PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS+ (for target setuptools
 140   packages) and +HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS+ (for host
 141   setuptools packages).
 142
 143 * +HOST_PYTHON_FOO_NEEDS_HOST_PYTHON+, to define the host python
 144   interpreter. The usage of this variable is limited to host
 145   packages. The two supported value are +python2+ and +python3+. It
 146   will ensure the right host python package is available and will
 147   invoke it for the build. If some build steps are overloaded, the
 148   right python interpreter must be explicitly called in the commands.
 149
 150 With the Python infrastructure, all the steps required to build and
 151 install the packages are already defined, and they generally work well
 152 for most Python-based packages. However, when required, it is still
 153 possible to customize what is done in any particular step:
 154
 155 * By adding a post-operation hook (after extract, patch, configure,
 156   build or install). See xref:hooks[] for details.
 157
 158 * By overriding one of the steps. For example, even if the Python
 159   infrastructure is used, if the package +.mk+ file defines its own
 160   +PYTHON_FOO_BUILD_CMDS+ variable, it will be used instead of the
 161   default Python one. However, using this method should be restricted
 162   to very specific cases. Do not use it in the general case.
 163
 164 [[scanpypi]]
 165
 166 ==== Generating a +python-package+ from a PyPI repository
 167
 168 If the Python package for which you would like to create a Buildroot
 169 package is available on PyPI, you may want to use the +scanpypi+ tool
 170 located in +support/scripts+ to automate the process.
 171
 172 You can find the list of existing PyPI packages
 173 https://pypi.python.org[here].
 174
 175 +scanpypi+ requires Python's +setuptools+ package to be installed on
 176 your host.
 177
 178 When at the root of your buildroot directory just do :
 179
 180 -----------------------
 181 ./support/scripts/scanpypi foo bar -o package
 182 -----------------------
 183
 184 This will generate packages +python-foo+ and +python-bar+ in the package
 185 folder if they exist on https://pypi.python.org.
 186
 187 Find the +external python modules+ menu and insert your package inside.
 188 Keep in mind that the items inside a menu should be in alphabetical order.
 189
 190 Please keep in mind that you'll most likely have to manually check the
 191 package for any mistakes as there are things that cannot be guessed by
 192 the generator (e.g.  dependencies on any of the python core modules
 193 such as BR2_PACKAGE_PYTHON_ZLIB).  Also, please take note that the
 194 license and license files are guessed and must be checked. You also
 195 need to manually add the package to the +package/Config.in+ file.
 196
 197 If your Buildroot package is not in the official Buildroot tree but in
 198 a br2-external tree, use the -o flag as follows:
 199
 200 -----------------------
 201 ./support/scripts/scanpypi foo bar -o other_package_dir
 202 -----------------------
 203
 204 This will generate packages +python-foo+ and +python-bar+ in the
 205 +other_package_directory+ instead of +package+.
 206
 207 Option +-h+ will list the available options:
 208
 209 -----------------------
 210 ./support/scripts/scanpypi -h
 211 -----------------------
 212
 213 [[python-package-cffi-backend]]
 214
 215 ==== +python-package+ CFFI backend
 216
 217 C Foreign Function Interface for Python (CFFI) provides a convenient
 218 and reliable way to call compiled C code from Python using interface
 219 declarations written in C. Python packages relying on this backend can
 220 be identified by the appearance of a +cffi+ dependency in the
 221 +install_requires+ field of their +setup.py+ file.
 222
 223 Such a package should:
 224
 225  * add +python-cffi+ as a runtime dependency in order to install the
 226 compiled C library wrapper on the target. This is achieved by adding
 227 +select BR2_PACKAGE_PYTHON_CFFI+ to the package +Config.in+.
 228
 229 ------------------------
 230 config BR2_PACKAGE_PYTHON_FOO
 231         bool "python-foo"
 232         select BR2_PACKAGE_PYTHON_CFFI # runtime
 233 ------------------------
 234
 235  * add +host-python-cffi+ as a build-time dependency in order to
 236 cross-compile the C wrapper. This is achieved by adding
 237 +host-python-cffi+ to the +PYTHON_FOO_DEPENDENCIES+ variable.
 238
 239 ------------------------
 240 ################################################################################
 241 #
 242 # python-foo
 243 #
 244 ################################################################################
 245
 246 ...
 247
 248 PYTHON_FOO_DEPENDENCIES = host-python-cffi
 249
 250 $(eval $(python-package))
 251 ------------------------