summaryrefslogtreecommitdiffabout
path: root/docs/manual/adding-packages-python.txt
blob: f878c382ea635ac2f790d934a36d91642e6e96c5 (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
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

Infrastructure for Python packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This infrastructure applies to Python packages that use the standard
Python setuptools mechanism as their build system, generally
recognizable as the usage of a +setup.py+ script.

[[python-package-tutorial]]

+python-package+ tutorial
^^^^^^^^^^^^^^^^^^^^^^^^^

First, let's see how to write a +.mk+ file for a Python package,
with an example :

------------------------
01: ################################################################################
02: #
03: # python-foo
04: #
05: ################################################################################
06:
07: PYTHON_FOO_VERSION = 1.0
08: PYTHON_FOO_SOURCE = python-foo-$(LIBFOO_VERSION).tar.xz
09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
10: LIBFOO_BUILD_ENV = SOME_VAR=1
11: LIBFOO_DEPENDENCIES = libmad
12:
13: $(eval $(python-package))
------------------------

On line 7, we declare the version of the package.

On line 8 and 9, we declare the name of the tarball (xz-ed tarball
recommended) and the location of the tarball on the Web. Buildroot
will automatically download the tarball from this location.

On line 10, we tell Buildroot to pass custom options to the Python
+setup.py+ script when it is configuring the package.

On line 11, we declare our dependencies, so that they are built
before the build process of our package starts.

Finally, on line line 13, we invoke the +python-package+ macro that
generates all the Makefile rules that actually allows the package to
be built.

[[python-package-reference]]

+python-package+ reference
^^^^^^^^^^^^^^^^^^^^^^^^^

The main macro of the Python package infrastructure is
+python-package+. It is similar to the +generic-package+ macro. The
ability to have target and host packages is also available, with the
+host-python-package+ macro.

Just like the generic infrastructure, the Python infrastructure works
by defining a number of variables before calling the +python-package+
macro.

First, all the package metadata information variables that exist in
the generic infrastructure also exist in the Python infrastructure:
+PYTHON_FOO_VERSION+, +PYTHON_FOO_SOURCE+, +PYTHON_FOO_PATCH+,
+PYTHON_FOO_SITE+, +PYTHON_FOO_SUBDIR+, +PYTHON_FOO_DEPENDENCIES+,
+PYTHON_FOO_INSTALL_STAGING+, +PYTHON_FOO_INSTALL_TARGET+.

Note however that setting +PYTHON_FOO_INSTALL_STAGING+ to +YES+ has no
effect, since Python modules generally don't need to be installed to
the staging directory.

A few additional variables, specific to the Python infrastructure, can
also be defined. Many of them are only useful in very specific cases,
typical packages will therefore only use a few of them.

* +PYTHON_FOO_BUILD_ENV+, to specify additional environment variables
  to pass to the Python +setup.py+ script (for both the build and
  install steps). Note that the infrastructure is already passing
  several standard variables: defined in +PKG_PYTHON_BUILD_ENV+ for
  target packages, and in +HOST_PKG_PYTHON_BUILD_ENV+ for host
  packages.

* +PYTHON_FOO_BUILD_OPT+, to specify additional options to pass to the
  Python +setup.py+ script during the build step. Note that when
  building Python packages for the target, the infrastructure is
  already passing several standard variables, defined in the
  +PKG_PYTHON_BUILD_OPT+ variable.

* +PYTHON_FOO_INSTALL_OPT+, to specify additional options to pass to
  the Python +setup.py+ script during the installation step. Note that
  when building Python packages for the target, the infrastructure is
  already passing several standard variables, defined in the
  +PKG_PYTHON_INSTALL_OPT+ variable.

With the Python infrastructure, all the steps required to build and
install the packages are already defined, and they generally work well
for most Python-based packages. However, when required, it is still
possible to customize what is done in any particular step:

* By adding a post-operation hook (after extract, patch, configure,
  build or install). See xref:hooks[] for details.

* By overriding one of the steps. For example, even if the Python
  infrastructure is used, if the package +.mk+ file defines its own
  +PYTHON_FOO_BUILD_CMDS+ variable, it will be used instead of the
  default Python one. However, using this method should be restricted
  to very specific cases. Do not use it in the general case.