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.