adding-packages-generic.txt 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for packages with specific build systems
  4. By 'packages with specific build systems' we mean all the packages
  5. whose build system is not one of the standard ones, such as
  6. 'autotools' or 'CMake'. This typically includes packages whose build
  7. system is based on hand-written Makefiles or shell scripts.
  8. [[generic-package-tutorial]]
  9. ==== +generic-package+ tutorial
  10. ------------------------------
  11. 01: ################################################################################
  12. 02: #
  13. 03: # libfoo
  14. 04: #
  15. 05: ################################################################################
  16. 06:
  17. 07: LIBFOO_VERSION = 1.0
  18. 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  19. 09: LIBFOO_SITE = http://www.foosoftware.org/download
  20. 10: LIBFOO_LICENSE = GPLv3+
  21. 11: LIBFOO_LICENSE_FILES = COPYING
  22. 12: LIBFOO_INSTALL_STAGING = YES
  23. 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
  24. 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
  25. 15:
  26. 16: define LIBFOO_BUILD_CMDS
  27. 17: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
  28. 18: endef
  29. 19:
  30. 20: define LIBFOO_INSTALL_STAGING_CMDS
  31. 21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
  32. 22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
  33. 23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
  34. 24: endef
  35. 25:
  36. 26: define LIBFOO_INSTALL_TARGET_CMDS
  37. 27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
  38. 28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
  39. 29: endef
  40. 30:
  41. 31: define LIBFOO_DEVICES
  42. 32: /dev/foo c 666 0 0 42 0 - - -
  43. 33: endef
  44. 34:
  45. 35: define LIBFOO_PERMISSIONS
  46. 36: /bin/foo f 4755 0 0 - - - - -
  47. 37: endef
  48. 38:
  49. 39: define LIBFOO_USERS
  50. 40: foo -1 libfoo -1 * - - - LibFoo daemon
  51. 41: endef
  52. 42:
  53. 43: $(eval $(generic-package))
  54. --------------------------------
  55. The Makefile begins on line 7 to 11 with metadata information: the
  56. version of the package (+LIBFOO_VERSION+), the name of the
  57. tarball containing the package (+LIBFOO_SOURCE+) (xz-ed tarball recommended)
  58. the Internet location at which the tarball can be downloaded from
  59. (+LIBFOO_SITE+), the license (+LIBFOO_LICENSE+) and file with the
  60. license text (+LIBFOO_LICENSE_FILES+). All variables must start with
  61. the same prefix, +LIBFOO_+ in this case. This prefix is always the
  62. uppercased version of the package name (see below to understand where
  63. the package name is defined).
  64. On line 12, we specify that this package wants to install something to
  65. the staging space. This is often needed for libraries, since they must
  66. install header files and other development files in the staging space.
  67. This will ensure that the commands listed in the
  68. +LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed.
  69. On line 13, we specify that there is some fixing to be done to some
  70. of the 'libfoo-config' files that were installed during
  71. +LIBFOO_INSTALL_STAGING_CMDS+ phase.
  72. These *-config files are executable shell script files that are
  73. located in '$(STAGING_DIR)/usr/bin' directory and are executed
  74. by other 3rd party packages to find out the location and the linking
  75. flags of this particular package.
  76. The problem is that all these *-config files by default give wrong,
  77. host system linking flags that are unsuitable for cross-compiling.
  78. For example: '-I/usr/include' instead of '-I$(STAGING_DIR)/usr/include'
  79. or: '-L/usr/lib' instead of '-L$(STAGING_DIR)/usr/lib'
  80. So some sed magic is done to these scripts to make them give correct
  81. flags.
  82. The argument to be given to +LIBFOO_CONFIG_SCRIPTS+ is the file name(s)
  83. of the shell script(s) needing fixing. All these names are relative to
  84. '$(STAGING_DIR)/usr/bin' and if needed multiple names can be given.
  85. In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
  86. from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
  87. .Config script: 'divine' package
  88. ================================
  89. Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
  90. So its fixup would be:
  91. --------------------------------
  92. DIVINE_CONFIG_SCRIPTS = divine-config
  93. --------------------------------
  94. ================================
  95. .Config script: 'imagemagick' package:
  96. ================================
  97. Package imagemagick installs the following scripts:
  98. '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
  99. So it's fixup would be:
  100. --------------------------------
  101. IMAGEMAGICK_CONFIG_SCRIPTS = \
  102. Magick-config Magick++-config \
  103. MagickCore-config MagickWand-config Wand-config
  104. --------------------------------
  105. ================================
  106. On line 14, we specify the list of dependencies this package relies
  107. on. These dependencies are listed in terms of lower-case package names,
  108. which can be packages for the target (without the +host-+
  109. prefix) or packages for the host (with the +host-+) prefix).
  110. Buildroot will ensure that all these packages are built and installed
  111. 'before' the current package starts its configuration.
  112. The rest of the Makefile, lines 16..29, defines what should be done
  113. at the different steps of the package configuration, compilation and
  114. installation.
  115. +LIBFOO_BUILD_CMDS+ tells what steps should be performed to
  116. build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what
  117. steps should be performed to install the package in the staging space.
  118. +LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be
  119. performed to install the package in the target space.
  120. All these steps rely on the +$(@D)+ variable, which
  121. contains the directory where the source code of the package has been
  122. extracted.
  123. On line 31..33, we define a device-node file used by this package
  124. (+LIBFOO_DEVICES+).
  125. On line 35..37, we define the permissions to set to specific files
  126. installed by this package (+LIBFOO_PERMISSIONS+).
  127. On lines 39..41, we define a user that is used by this package (e.g.
  128. to run a daemon as non-root) (+LIBFOO_USERS+).
  129. Finally, on line 43, we call the +generic-package+ function, which
  130. generates, according to the variables defined previously, all the
  131. Makefile code necessary to make your package working.
  132. [[generic-package-reference]]
  133. ==== +generic-package+ reference
  134. There are two variants of the generic target. The +generic-package+ macro is
  135. used for packages to be cross-compiled for the target. The
  136. +host-generic-package+ macro is used for host packages, natively compiled
  137. for the host. It is possible to call both of them in a single +.mk+
  138. file: once to create the rules to generate a target
  139. package and once to create the rules to generate a host package:
  140. ----------------------
  141. $(eval $(generic-package))
  142. $(eval $(host-generic-package))
  143. ----------------------
  144. This might be useful if the compilation of the target package requires
  145. some tools to be installed on the host. If the package name is
  146. +libfoo+, then the name of the package for the target is also
  147. +libfoo+, while the name of the package for the host is
  148. +host-libfoo+. These names should be used in the DEPENDENCIES
  149. variables of other packages, if they depend on +libfoo+ or
  150. +host-libfoo+.
  151. The call to the +generic-package+ and/or +host-generic-package+ macro *must* be
  152. at the end of the +.mk+ file, after all variable definitions.
  153. For the target package, the +generic-package+ uses the variables defined by
  154. the .mk file and prefixed by the uppercased package name:
  155. +LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
  156. 'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
  157. exist, the package infrastructure uses the corresponding variable
  158. prefixed by +LIBFOO_+. This is done for variables that are likely to
  159. have the same value for both the target and host packages. See below
  160. for details.
  161. The list of variables that can be set in a +.mk+ file to give metadata
  162. information is (assuming the package name is +libfoo+) :
  163. * +LIBFOO_VERSION+, mandatory, must contain the version of the
  164. package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
  165. assumed to be the same as +LIBFOO_VERSION+. It can also be a
  166. revision number, branch or tag for packages that are fetched
  167. directly from their revision control system. +
  168. Examples: +
  169. +LIBFOO_VERSION = 0.1.2+ +
  170. +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
  171. +LIBFOO_VERSION = stable+
  172. * +LIBFOO_SOURCE+ may contain the name of the tarball of
  173. the package. If +HOST_LIBFOO_SOURCE+ is not specified, it
  174. defaults to +LIBFOO_SOURCE+. If none are specified, then
  175. the value is assumed to be
  176. +libfoo-$(LIBFOO_VERSION).tar.gz+. +
  177. Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
  178. * +LIBFOO_PATCH+ may contain a space-separated list of patch file
  179. names, that will be downloaded from the same location as the tarball
  180. indicated in +LIBFOO_SOURCE+, and then applied to the package source
  181. code. If +HOST_LIBFOO_PATCH+ is not specified, it defaults to
  182. +LIBFOO_PATCH+. Note that patches that are included in Buildroot
  183. itself use a different mechanism: all files of the form
  184. +<packagename>-*.patch+ present in the package directory inside
  185. Buildroot will be applied to the package after extraction (see
  186. xref:patch-policy[patching a package]). Finally, patches listed in
  187. the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
  188. in the Buildroot package directory.
  189. * +LIBFOO_SITE+ provides the location of the package, which can be a
  190. URL or a local filesystem path. HTTP, FTP and SCP are supported URL
  191. types for retrieving package tarballs. Git, Subversion, Mercurial,
  192. and Bazaar are supported URL types for retrieving packages directly
  193. from source code management systems. There is a helper function to make
  194. it easier to download source tarballs from GitHub (refer to
  195. xref:github-download-url[] for details). A filesystem path may be used
  196. to specify either a tarball or a directory containing the package
  197. source code. See +LIBFOO_SITE_METHOD+ below for more details on how
  198. retrieval works. +
  199. Note that SCP URLs should be of the form
  200. +scp://[user@]host:filepath+, and that filepath is relative to the
  201. user's home directory, so you may want to prepend the path with a
  202. slash for absolute paths:
  203. +scp://[user@]host:/absolutepath+. +
  204. If +HOST_LIBFOO_SITE+ is not specified, it defaults to
  205. +LIBFOO_SITE+.
  206. Examples: +
  207. +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
  208. +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
  209. +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
  210. +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
  211. * +LIBFOO_EXTRA_DOWNLOADS+ lists a number of additional files that
  212. Buildroot should download from +LIBFOO_SITE+ in addition to the main
  213. +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do
  214. anything with those additional files, except download files: it will
  215. be up to the package recipe to use them from +$(BR2_DL_DIR)+.
  216. * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
  217. package source code. In many cases, Buildroot guesses the method
  218. from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
  219. is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
  220. defaults to the value of +LIBFOO_SITE_METHOD+. +
  221. The possible values of +LIBFOO_SITE_METHOD+ are:
  222. ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
  223. default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
  224. +ftp://+.
  225. ** +scp+ for downloads of tarballs over SSH with scp. Used by
  226. default when +LIBFOO_SITE+ begins with +scp://+.
  227. ** +svn+ for retrieving source code from a Subversion repository.
  228. Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
  229. +http://+ Subversion repository URL is specified in
  230. +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
  231. Buildroot performs a checkout which is preserved as a tarball in
  232. the download cache; subsequent builds use the tarball instead of
  233. performing another checkout.
  234. ** +cvs+ for retrieving source code from a CVS repository.
  235. Used by default when +LIBFOO_SITE+ begins with +cvs://+.
  236. The downloaded source code is cached as with the +svn+ method.
  237. Only anonymous pserver mode is supported.
  238. +LIBFOO_SITE+ 'must' contain the source URL as well as the remote
  239. repository directory. The module is the package name.
  240. +LIBFOO_VERSION+ is 'mandatory' and 'must' be a timestamp.
  241. ** +git+ for retrieving source code from a Git repository. Used by
  242. default when +LIBFOO_SITE+ begins with +git://+. The downloaded
  243. source code is cached as with the +svn+
  244. method.
  245. ** +hg+ for retrieving source code from a Mercurial repository. One
  246. 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
  247. contains a Mercurial repository URL. The downloaded source code
  248. is cached as with the +svn+ method.
  249. ** +bzr+ for retrieving source code from a Bazaar repository. Used
  250. by default when +LIBFOO_SITE+ begins with +bzr://+. The
  251. downloaded source code is cached as with the +svn+ method.
  252. ** +file+ for a local tarball. One should use this when
  253. +LIBFOO_SITE+ specifies a package tarball as a local filename.
  254. Useful for software that isn't available publicly or in version
  255. control.
  256. ** +local+ for a local source code directory. One should use this
  257. when +LIBFOO_SITE+ specifies a local directory path containing
  258. the package source code. Buildroot copies the contents of the
  259. source directory into the package's build directory.
  260. * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
  261. name) that are required for the current target package to
  262. compile. These dependencies are guaranteed to be compiled and
  263. installed before the configuration of the current package starts. In
  264. a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
  265. the current host package.
  266. * +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
  267. implementation of. See xref:virtual-package-tutorial[].
  268. * +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
  269. set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
  270. variables are executed to install the package into the staging
  271. directory.
  272. * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
  273. set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
  274. variables are executed to install the package into the target
  275. directory.
  276. * +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
  277. '$(STAGING_DIR)/usr/bin' that need some special fixing to make them
  278. cross-compiling friendly. Multiple file names separated by space can
  279. be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
  280. listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
  281. +$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
  282. * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
  283. when using the static device table. The syntax to use is the
  284. makedevs one. You can find some documentation for this syntax in the
  285. xref:makedev-syntax[]. This variable is optional.
  286. * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
  287. the end of the build process. The syntax is once again the makedevs one.
  288. You can find some documentation for this syntax in the xref:makedev-syntax[].
  289. This variable is optional.
  290. * +LIBFOO_USERS+ lists the users to create for this package, if it installs
  291. a program you want to run as a specific user (e.g. as a daemon, or as a
  292. cron-job). The syntax is similar in spirit to the makedevs one, and is
  293. described in the xref:makeuser-syntax[]. This variable is optional.
  294. * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
  295. is released.
  296. This name will appear in the manifest file produced by +make legal-info+.
  297. If the license appears in xref:legal-info-list-licenses[the following list],
  298. use the same string to make the manifest file uniform.
  299. Otherwise, describe the license in a precise and concise way, avoiding
  300. ambiguous names such as +BSD+ which actually name a family of licenses.
  301. This variable is optional. If it is not defined, +unknown+ will appear in
  302. the +license+ field of the manifest file for this package.
  303. * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
  304. tarball that contain the license(s) under which the package is released.
  305. +make legal-info+ copies all of these files in the +legal-info+ directory.
  306. See xref:legal-info[] for more information.
  307. This variable is optional. If it is not defined, a warning will be produced
  308. to let you know, and +not saved+ will appear in the +license files+ field
  309. of the manifest file for this package.
  310. * +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
  311. the package source code is allowed to be redistributed. Set it to +NO+ for
  312. non-opensource packages: Buildroot will not save the source code for this
  313. package when collecting the +legal-info+.
  314. * +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
  315. the FLAT binary format. The application stack size on the NOMMU architecture
  316. processors can't be enlarged at run time. The default stack size for the
  317. FLAT binary format is only 4k bytes. If the application consumes more stack,
  318. append the required number here.
  319. The recommended way to define these variables is to use the following
  320. syntax:
  321. ----------------------
  322. LIBFOO_VERSION = 2.32
  323. ----------------------
  324. Now, the variables that define what should be performed at the
  325. different steps of the build process.
  326. * +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
  327. the package. This is generally not needed as tarballs are
  328. automatically handled by Buildroot. However, if the package uses a
  329. non-standard archive format, such as a ZIP or RAR file, or has a
  330. tarball with a non-standard organization, this variable allows to
  331. override the package infrastructure default behavior.
  332. * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
  333. configure the package before its compilation.
  334. * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
  335. compile the package.
  336. * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
  337. to install the package, when the package is a host package. The
  338. package must install its files to the directory given by
  339. +$(HOST_DIR)+. All files, including development files such as
  340. headers should be installed, since other packages might be compiled
  341. on top of this package.
  342. * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
  343. performed to install the package to the target directory, when the
  344. package is a target package. The package must install its files to
  345. the directory given by +$(TARGET_DIR)+. Only the files required for
  346. 'execution' of the package have to be
  347. installed. Header files, static libraries and documentation will be
  348. removed again when the target filesystem is finalized.
  349. * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
  350. performed to install the package to the staging directory, when the
  351. package is a target package. The package must install its files to
  352. the directory given by +$(STAGING_DIR)+. All development files
  353. should be installed, since they might be needed to compile other
  354. packages.
  355. * +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to
  356. install the package to the images directory, when the package is a
  357. target package. The package must install its files to the directory
  358. given by +$(BINARIES_DIR)+. Only files that are binary images (aka
  359. images) that do not belong in the +TARGET_DIR+ but are necessary
  360. for booting the board should be placed here. For example, a package
  361. should utilize this step if it has binaries which would be similar
  362. to the kernel image, bootloader or root filesystem images.
  363. * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
  364. actions to install init scripts either for the systemV-like init systems
  365. (busybox, sysvinit, etc.) or for the systemd units. These commands
  366. will be run only when the relevant init system is installed (i.e. if
  367. systemd is selected as the init system in the configuration, only
  368. +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
  369. The preferred way to define these variables is:
  370. ----------------------
  371. define LIBFOO_CONFIGURE_CMDS
  372. action 1
  373. action 2
  374. action 3
  375. endef
  376. ----------------------
  377. In the action definitions, you can use the following variables:
  378. * +$(@D)+, which contains the directory in which the package source
  379. code has been uncompressed.
  380. * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
  381. cross-compilation utilities
  382. * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
  383. * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
  384. variables to install the packages properly.
  385. Finally, you can also use hooks. See xref:hooks[] for more information.