adding-packages-autotools.txt 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for autotools-based packages
  4. [[autotools-package-tutorial]]
  5. ==== +autotools-package+ tutorial
  6. First, let's see how to write a +.mk+ file for an autotools-based
  7. package, with an example :
  8. ------------------------
  9. 01: ################################################################################
  10. 02: #
  11. 03: # libfoo
  12. 04: #
  13. 05: ################################################################################
  14. 06:
  15. 07: LIBFOO_VERSION = 1.0
  16. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  17. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  18. 10: LIBFOO_INSTALL_STAGING = YES
  19. 11: LIBFOO_INSTALL_TARGET = NO
  20. 12: LIBFOO_CONF_OPTS = --disable-shared
  21. 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
  22. 14:
  23. 15: $(eval $(autotools-package))
  24. ------------------------
  25. On line 7, we declare the version of the package.
  26. On line 8 and 9, we declare the name of the tarball (xz-ed tarball recommended)
  27. and the location of the tarball on the Web. Buildroot will automatically
  28. download the tarball from this location.
  29. On line 10, we tell Buildroot to install the package to the staging
  30. directory. The staging directory, located in +output/staging/+
  31. is the directory where all the packages are installed, including their
  32. development files, etc. By default, packages are not installed to the
  33. staging directory, since usually, only libraries need to be installed in
  34. the staging directory: their development files are needed to compile
  35. other libraries or applications depending on them. Also by default, when
  36. staging installation is enabled, packages are installed in this location
  37. using the +make install+ command.
  38. On line 11, we tell Buildroot to not install the package to the
  39. target directory. This directory contains what will become the root
  40. filesystem running on the target. For purely static libraries, it is
  41. not necessary to install them in the target directory because they will
  42. not be used at runtime. By default, target installation is enabled; setting
  43. this variable to NO is almost never needed. Also by default, packages are
  44. installed in this location using the +make install+ command.
  45. On line 12, we tell Buildroot to pass a custom configure option, that
  46. will be passed to the +./configure+ script before configuring
  47. and building the package.
  48. On line 13, we declare our dependencies, so that they are built
  49. before the build process of our package starts.
  50. Finally, on line line 15, we invoke the +autotools-package+
  51. macro that generates all the Makefile rules that actually allows the
  52. package to be built.
  53. [[autotools-package-reference]]
  54. ==== +autotools-package+ reference
  55. The main macro of the autotools package infrastructure is
  56. +autotools-package+. It is similar to the +generic-package+ macro. The ability to
  57. have target and host packages is also available, with the
  58. +host-autotools-package+ macro.
  59. Just like the generic infrastructure, the autotools infrastructure
  60. works by defining a number of variables before calling the
  61. +autotools-package+ macro.
  62. First, all the package metadata information variables that exist in the
  63. generic infrastructure also exist in the autotools infrastructure:
  64. +LIBFOO_VERSION+, +LIBFOO_SOURCE+,
  65. +LIBFOO_PATCH+, +LIBFOO_SITE+,
  66. +LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+,
  67. +LIBFOO_INSTALL_STAGING+, +LIBFOO_INSTALL_TARGET+.
  68. A few additional variables, specific to the autotools infrastructure,
  69. can also be defined. Many of them are only useful in very specific
  70. cases, typical packages will therefore only use a few of them.
  71. * +LIBFOO_SUBDIR+ may contain the name of a subdirectory
  72. inside the package that contains the configure script. This is useful,
  73. if for example, the main configure script is not at the root of the
  74. tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is
  75. not specified, it defaults to +LIBFOO_SUBDIR+.
  76. * +LIBFOO_CONF_ENV+, to specify additional environment
  77. variables to pass to the configure script. By default, empty.
  78. * +LIBFOO_CONF_OPTS+, to specify additional configure
  79. options to pass to the configure script. By default, empty.
  80. * +LIBFOO_MAKE+, to specify an alternate +make+
  81. command. This is typically useful when parallel make is enabled in
  82. the configuration (using +BR2_JLEVEL+) but that this
  83. feature should be disabled for the given package, for one reason or
  84. another. By default, set to +$(MAKE)+. If parallel building
  85. is not supported by the package, then it should be set to
  86. +LIBFOO_MAKE=$(MAKE1)+.
  87. * +LIBFOO_MAKE_ENV+, to specify additional environment
  88. variables to pass to make in the build step. These are passed before
  89. the +make+ command. By default, empty.
  90. * +LIBFOO_MAKE_OPTS+, to specify additional variables to
  91. pass to make in the build step. These are passed after the
  92. +make+ command. By default, empty.
  93. * +LIBFOO_AUTORECONF+, tells whether the package should
  94. be autoreconfigured or not (i.e. if the configure script and
  95. Makefile.in files should be re-generated by re-running autoconf,
  96. automake, libtool, etc.). Valid values are +YES+ and
  97. +NO+. By default, the value is +NO+
  98. * +LIBFOO_AUTORECONF_ENV+, to specify additional environment
  99. variables to pass to the 'autoreconf' program if
  100. +LIBFOO_AUTORECONF=YES+. These are passed in the environment of
  101. the 'autoreconf' command. By default, empty.
  102. * +LIBFOO_AUTORECONF_OPTS+ to specify additional options
  103. passed to the 'autoreconf' program if
  104. +LIBFOO_AUTORECONF=YES+. By default, empty.
  105. * +LIBFOO_GETTEXTIZE+, tells whether the package should be
  106. gettextized or not (i.e. if the package uses a different gettext
  107. version than Buildroot provides, and it is needed to run
  108. 'gettextize'.) Only valid when +LIBFOO_AUTORECONF=YES+. Valid
  109. values are +YES+ and +NO+. The default is +NO+.
  110. * +LIBFOO_GETTEXTIZE_OPTS+, to specify additional options passed to
  111. the 'gettextize' program, if +LIBFOO_GETTEXTIZE=YES+. You may
  112. use that if, for example, the +.po+ files are not located in the
  113. standard place (i.e. in +po/+ at the root of the package.) By
  114. default, '-f'.
  115. * +LIBFOO_LIBTOOL_PATCH+ tells whether the Buildroot
  116. patch to fix libtool cross-compilation issues should be applied or
  117. not. Valid values are +YES+ and +NO+. By
  118. default, the value is +YES+
  119. * +LIBFOO_INSTALL_STAGING_OPTS+ contains the make options
  120. used to install the package to the staging directory. By default, the
  121. value is +DESTDIR=$(STAGING_DIR) install+, which is
  122. correct for most autotools packages. It is still possible to override
  123. it.
  124. * +LIBFOO_INSTALL_TARGET_OPTS+ contains the make options
  125. used to install the package to the target directory. By default, the
  126. value is +DESTDIR=$(TARGET_DIR) install+. The default
  127. value is correct for most autotools packages, but it is still possible
  128. to override it if needed.
  129. With the autotools infrastructure, all the steps required to build
  130. and install the packages are already defined, and they generally work
  131. well for most autotools-based packages. However, when required, it is
  132. still possible to customize what is done in any particular step:
  133. * By adding a post-operation hook (after extract, patch, configure,
  134. build or install). See xref:hooks[] for details.
  135. * By overriding one of the steps. For example, even if the autotools
  136. infrastructure is used, if the package +.mk+ file defines its
  137. own +LIBFOO_CONFIGURE_CMDS+ variable, it will be used
  138. instead of the default autotools one. However, using this method
  139. should be restricted to very specific cases. Do not use it in the
  140. general case.