adding-packages-python.txt 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for Python packages
  4. This infrastructure applies to Python packages that use the standard
  5. Python setuptools mechanism as their build system, generally
  6. recognizable by the usage of a +setup.py+ script.
  7. [[python-package-tutorial]]
  8. ==== +python-package+ tutorial
  9. First, let's see how to write a +.mk+ file for a Python package,
  10. with an example :
  11. ------------------------
  12. 01: ################################################################################
  13. 02: #
  14. 03: # python-foo
  15. 04: #
  16. 05: ################################################################################
  17. 06:
  18. 07: PYTHON_FOO_VERSION = 1.0
  19. 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
  20. 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
  21. 10: PYTHON_FOO_LICENSE = BSD-3c
  22. 11: PYTHON_FOO_LICENSE_FILES = LICENSE
  23. 12: PYTHON_FOO_ENV = SOME_VAR=1
  24. 13: PYTHON_FOO_DEPENDENCIES = libmad
  25. 14: PYTHON_FOO_SETUP_TYPE = distutils
  26. 15:
  27. 16: $(eval $(python-package))
  28. ------------------------
  29. On line 7, we declare the version of the package.
  30. On line 8 and 9, we declare the name of the tarball (xz-ed tarball
  31. recommended) and the location of the tarball on the Web. Buildroot
  32. will automatically download the tarball from this location.
  33. On line 10 and 11, we give licensing details about the package (its
  34. license on line 10, and the file containing the license text on line
  35. 11).
  36. On line 12, we tell Buildroot to pass custom options to the Python
  37. +setup.py+ script when it is configuring the package.
  38. On line 13, we declare our dependencies, so that they are built
  39. before the build process of our package starts.
  40. On line 14, we declare the specific Python build system being used. In
  41. this case the +distutils+ Python build system is used. The two
  42. supported ones are +distutils+ and +setuptools+.
  43. Finally, on line 16, we invoke the +python-package+ macro that
  44. generates all the Makefile rules that actually allow the package to be
  45. built.
  46. [[python-package-reference]]
  47. ==== +python-package+ reference
  48. As a policy, packages that merely provide Python modules should all be
  49. named +python-<something>+ in Buildroot. Other packages that use the
  50. Python build system, but are not Python modules, can freely choose
  51. their name (existing examples in Buildroot are +scons+ and
  52. +supervisor+).
  53. In their +Config.in+ file, they should depend on +BR2_PACKAGE_PYTHON+
  54. so that when Buildroot will enable Python 3 usage for modules, we will
  55. be able to enable Python modules progressively on Python 3.
  56. The main macro of the Python package infrastructure is
  57. +python-package+. It is similar to the +generic-package+ macro. It is
  58. also possible to create Python host packages with the
  59. +host-python-package+ macro.
  60. Just like the generic infrastructure, the Python infrastructure works
  61. by defining a number of variables before calling the +python-package+
  62. or +host-python-package+ macros.
  63. All the package metadata information variables that exist in the
  64. xref:generic-package-reference[generic package infrastructure] also
  65. exist in the Python infrastructure: +PYTHON_FOO_VERSION+,
  66. +PYTHON_FOO_SOURCE+, +PYTHON_FOO_PATCH+, +PYTHON_FOO_SITE+,
  67. +PYTHON_FOO_SUBDIR+, +PYTHON_FOO_DEPENDENCIES+, +PYTHON_FOO_LICENSE+,
  68. +PYTHON_FOO_LICENSE_FILES+, +PYTHON_FOO_INSTALL_STAGING+, etc.
  69. Note that:
  70. * It is not necessary to add +python+ or +host-python+ in the
  71. +PYTHON_FOO_DEPENDENCIES+ variable of a package, since these basic
  72. dependencies are automatically added as needed by the Python
  73. package infrastructure.
  74. * Similarly, it is not needed to add +host-setuptools+ and/or
  75. +host-distutilscross+ dependencies to +PYTHON_FOO_DEPENDENCIES+ for
  76. setuptools-based packages, since these are automatically added by
  77. the Python infrastructure as needed.
  78. One variable specific to the Python infrastructure is mandatory:
  79. * +PYTHON_FOO_SETUP_TYPE+, to define which Python build system is used
  80. by the package. The two supported values are +distutils+ and
  81. +setuptools+. If you don't know which one is used in your package,
  82. look at the +setup.py+ file in your package source code, and see
  83. whether it imports things from the +distutils+ module or the
  84. +setuptools+ module.
  85. A few additional variables, specific to the Python infrastructure, can
  86. optionally be defined, depending on the package's needs. Many of them
  87. are only useful in very specific cases, typical packages will
  88. therefore only use a few of them, or none.
  89. * +PYTHON_FOO_ENV+, to specify additional environment variables to
  90. pass to the Python +setup.py+ script (for both the build and install
  91. steps). Note that the infrastructure is automatically passing
  92. several standard variables, defined in +PKG_PYTHON_DISTUTILS_ENV+
  93. (for distutils target packages), +HOST_PKG_PYTHON_DISTUTILS_ENV+
  94. (for distutils host packages), +PKG_PYTHON_SETUPTOOLS_ENV+ (for
  95. setuptools target packages) and +HOST_PKG_PYTHON_SETUPTOOLS_ENV+
  96. (for setuptools host packages).
  97. * +PYTHON_FOO_BUILD_OPTS+, to specify additional options to pass to the
  98. Python +setup.py+ script during the build step. For target distutils
  99. packages, the +PKG_PYTHON_DISTUTILS_BUILD_OPTS+ options are already
  100. passed automatically by the infrastructure.
  101. * +PYTHON_FOO_INSTALL_TARGET_OPTS+, +PYTHON_FOO_INSTALL_STAGING_OPTS+,
  102. +HOST_PYTHON_FOO_INSTALL_OPTS+ to specify additional options to pass
  103. to the Python +setup.py+ script during the target installation step,
  104. the staging installation step or the host installation,
  105. respectively. Note that the infrastructure is automatically passing
  106. some options, defined in +PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS+
  107. or +PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS+ (for target distutils
  108. packages), +HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS+ (for host
  109. distutils packages), +PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS+ or
  110. +PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS+ (for target setuptools
  111. packages) and +HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS+ (for host
  112. setuptools packages).
  113. * +HOST_PYTHON_FOO_NEEDS_HOST_PYTHON+, to define the host python
  114. interpreter. The usage of this variable is limited to host
  115. packages. The two supported value are +python2+ and +python3+. It
  116. will ensures the right host python package is available and will
  117. invoke it for the build. If some build steps are overloaded, the
  118. right python interpreter must be explicitly called in the commands.
  119. With the Python infrastructure, all the steps required to build and
  120. install the packages are already defined, and they generally work well
  121. for most Python-based packages. However, when required, it is still
  122. possible to customize what is done in any particular step:
  123. * By adding a post-operation hook (after extract, patch, configure,
  124. build or install). See xref:hooks[] for details.
  125. * By overriding one of the steps. For example, even if the Python
  126. infrastructure is used, if the package +.mk+ file defines its own
  127. +PYTHON_FOO_BUILD_CMDS+ variable, it will be used instead of the
  128. default Python one. However, using this method should be restricted
  129. to very specific cases. Do not use it in the general case.