adding-packages-generic.txt 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626
  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 = GPL-3.0+
  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) $(TARGET_CONFIGURE_OPTS) -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_USERS
  42. 32: foo -1 libfoo -1 * - - - LibFoo daemon
  43. 33: endef
  44. 34:
  45. 35: define LIBFOO_DEVICES
  46. 36: /dev/foo c 666 0 0 42 0 - - -
  47. 37: endef
  48. 38:
  49. 39: define LIBFOO_PERMISSIONS
  50. 40: /bin/foo f 4755 foo libfoo - - - - -
  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 lines 31..33, we define a user that is used by this package (e.g.
  124. to run a daemon as non-root) (+LIBFOO_USERS+).
  125. On line 35..37, we define a device-node file used by this package
  126. (+LIBFOO_DEVICES+).
  127. On line 39..41, we define the permissions to set to specific files
  128. installed by this package (+LIBFOO_PERMISSIONS+).
  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
  152. *must* be at the end of the +.mk+ file, after all variable definitions.
  153. The call to +host-generic-package+ *must* be after the call to
  154. +generic-package+, if any.
  155. For the target package, the +generic-package+ uses the variables defined by
  156. the .mk file and prefixed by the uppercased package name:
  157. +LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
  158. 'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
  159. exist, the package infrastructure uses the corresponding variable
  160. prefixed by +LIBFOO_+. This is done for variables that are likely to
  161. have the same value for both the target and host packages. See below
  162. for details.
  163. The list of variables that can be set in a +.mk+ file to give metadata
  164. information is (assuming the package name is +libfoo+) :
  165. * +LIBFOO_VERSION+, mandatory, must contain the version of the
  166. package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
  167. assumed to be the same as +LIBFOO_VERSION+. It can also be a
  168. revision number or a tag for packages that are fetched directly
  169. from their version control system. Examples:
  170. ** a version for a release tarball: +LIBFOO_VERSION = 0.1.2+
  171. ** a sha1 for a git tree: +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+
  172. ** a tag for a git tree +LIBFOO_VERSION = v0.1.2+
  173. +
  174. .Note:
  175. Using a branch name as +FOO_VERSION+ is not supported, because it does
  176. not and can not work as people would expect it should:
  177. +
  178. 1. due to local caching, Buildroot will not re-fetch the repository,
  179. so people who expect to be able to follow the remote repository
  180. would be quite surprised and disappointed;
  181. 2. because two builds can never be perfectly simultaneous, and because
  182. the remote repository may get new commits on the branch anytime,
  183. two users, using the same Buildroot tree and building the same
  184. configuration, may get different source, thus rendering the build
  185. non reproducible, and people would be quite surprised and
  186. disappointed.
  187. * +LIBFOO_SOURCE+ may contain the name of the tarball of the package,
  188. which Buildroot will use to download the tarball from
  189. +LIBFOO_SITE+. If +HOST_LIBFOO_SOURCE+ is not specified, it defaults
  190. to +LIBFOO_SOURCE+. If none are specified, then the value is assumed
  191. to be +libfoo-$(LIBFOO_VERSION).tar.gz+. +
  192. Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
  193. * +LIBFOO_PATCH+ may contain a space-separated list of patch file
  194. names, that Buildroot will download and apply to the package source
  195. code. If an entry contains +://+, then Buildroot will assume it is a
  196. full URL and download the patch from this location. Otherwise,
  197. Buildroot will assume that the patch should be downloaded from
  198. +LIBFOO_SITE+. If +HOST_LIBFOO_PATCH+ is not specified, it defaults
  199. to +LIBFOO_PATCH+. Note that patches that are included in Buildroot
  200. itself use a different mechanism: all files of the form
  201. +*.patch+ present in the package directory inside
  202. Buildroot will be applied to the package after extraction (see
  203. xref:patch-policy[patching a package]). Finally, patches listed in
  204. the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
  205. in the Buildroot package directory.
  206. * +LIBFOO_SITE+ provides the location of the package, which can be a
  207. URL or a local filesystem path. HTTP, FTP and SCP are supported URL
  208. types for retrieving package tarballs. In these cases don't include a
  209. trailing slash: it will be added by Buildroot between the directory
  210. and the filename as appropriate. Git, Subversion, Mercurial,
  211. and Bazaar are supported URL types for retrieving packages directly
  212. from source code management systems. There is a helper function to make
  213. it easier to download source tarballs from GitHub (refer to
  214. xref:github-download-url[] for details). A filesystem path may be used
  215. to specify either a tarball or a directory containing the package
  216. source code. See +LIBFOO_SITE_METHOD+ below for more details on how
  217. retrieval works. +
  218. Note that SCP URLs should be of the form
  219. +scp://[user@]host:filepath+, and that filepath is relative to the
  220. user's home directory, so you may want to prepend the path with a
  221. slash for absolute paths:
  222. +scp://[user@]host:/absolutepath+. +
  223. If +HOST_LIBFOO_SITE+ is not specified, it defaults to
  224. +LIBFOO_SITE+.
  225. Examples: +
  226. +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
  227. +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ +
  228. +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
  229. +LIBFOO_SITE=$(TOPDIR)/../src/libfoo+
  230. * +LIBFOO_DL_OPTS+ is a space-separated list of additional options to
  231. pass to the downloader. Useful for retrieving documents with
  232. server-side checking for user logins and passwords, or to use a proxy.
  233. All download methods valid for +LIBFOO_SITE_METHOD+ are supported;
  234. valid options depend on the download method (consult the man page
  235. for the respective download utilities).
  236. * +LIBFOO_EXTRA_DOWNLOADS+ is a space-separated list of additional
  237. files that Buildroot should download. If an entry contains +://+
  238. then Buildroot will assume it is a complete URL and will download
  239. the file using this URL. Otherwise, Buildroot will assume the file
  240. to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do
  241. anything with those additional files, except download them: it will
  242. be up to the package recipe to use them from +$(LIBFOO_DL_DIR)+.
  243. * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
  244. package source code. In many cases, Buildroot guesses the method
  245. from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
  246. is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
  247. defaults to the value of +LIBFOO_SITE_METHOD+. +
  248. The possible values of +LIBFOO_SITE_METHOD+ are:
  249. ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
  250. default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
  251. +ftp://+.
  252. ** +scp+ for downloads of tarballs over SSH with scp. Used by
  253. default when +LIBFOO_SITE+ begins with +scp://+.
  254. ** +svn+ for retrieving source code from a Subversion repository.
  255. Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
  256. +http://+ Subversion repository URL is specified in
  257. +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
  258. Buildroot performs a checkout which is preserved as a tarball in
  259. the download cache; subsequent builds use the tarball instead of
  260. performing another checkout.
  261. ** +cvs+ for retrieving source code from a CVS repository.
  262. Used by default when +LIBFOO_SITE+ begins with +cvs://+.
  263. The downloaded source code is cached as with the +svn+ method.
  264. Anonymous pserver mode is assumed otherwise explicitly defined
  265. on +LIBFOO_SITE+. Both
  266. +LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and
  267. +LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+
  268. are accepted, on the former anonymous pserver access mode is
  269. assumed.
  270. +LIBFOO_SITE+ 'must' contain the source URL as well as the remote
  271. repository directory. The module is the package name.
  272. +LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or
  273. a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
  274. 13:45+01" see "man cvs" for further details).
  275. ** +git+ for retrieving source code from a Git repository. Used by
  276. default when +LIBFOO_SITE+ begins with +git://+. The downloaded
  277. source code is cached as with the +svn+
  278. method.
  279. ** +hg+ for retrieving source code from a Mercurial repository. One
  280. 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
  281. contains a Mercurial repository URL. The downloaded source code
  282. is cached as with the +svn+ method.
  283. ** +bzr+ for retrieving source code from a Bazaar repository. Used
  284. by default when +LIBFOO_SITE+ begins with +bzr://+. The
  285. downloaded source code is cached as with the +svn+ method.
  286. ** +file+ for a local tarball. One should use this when
  287. +LIBFOO_SITE+ specifies a package tarball as a local filename.
  288. Useful for software that isn't available publicly or in version
  289. control.
  290. ** +local+ for a local source code directory. One should use this
  291. when +LIBFOO_SITE+ specifies a local directory path containing
  292. the package source code. Buildroot copies the contents of the
  293. source directory into the package's build directory. Note that
  294. for +local+ packages, no patches are applied. If you need to
  295. still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see
  296. xref:hooks-rsync[].
  297. * +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive
  298. with the git submodules in the repository. This is only available
  299. for packages downloaded with git (i.e. when
  300. +LIBFOO_SITE_METHOD=git+). Note that we try not to use such git
  301. submodules when they contain bundled libraries, in which case we
  302. prefer to use those libraries from their own package.
  303. * +LIBFOO_STRIP_COMPONENTS+ is the number of leading components
  304. (directories) that tar must strip from file names on extraction.
  305. The tarball for most packages has one leading component named
  306. "<pkg-name>-<pkg-version>", thus Buildroot passes
  307. --strip-components=1 to tar to remove it.
  308. For non-standard packages that don't have this component, or
  309. that have more than one leading component to strip, set this
  310. variable with the value to be passed to tar. Default: 1.
  311. * +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude
  312. when extracting the archive. Each item from that list is passed as
  313. a tar's +--exclude+ option. By default, empty.
  314. * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
  315. name) that are required for the current target package to
  316. compile. These dependencies are guaranteed to be compiled and
  317. installed before the configuration of the current package starts.
  318. However, modifications to configuration of these dependencies will
  319. not force a rebuild of the current package. In a similar way,
  320. +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for the current
  321. host package.
  322. * +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of
  323. package name) that are required for the current target package to be
  324. extracted. These dependencies are guaranteed to be compiled and
  325. installed before the extract step of the current package
  326. starts. This is only used internally by the package infrastructure,
  327. and should typically not be used directly by packages.
  328. * +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of
  329. package name) that are required for the current package to be
  330. patched. These dependencies are guaranteed to be extracted and
  331. patched (but not necessarily built) before the current package is
  332. patched. In a similar way, +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists
  333. the dependencies for the current host package.
  334. This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you
  335. really want to use.
  336. * +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
  337. implementation of. See xref:virtual-package-tutorial[].
  338. * +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
  339. set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
  340. variables are executed to install the package into the staging
  341. directory.
  342. * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
  343. set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
  344. variables are executed to install the package into the target
  345. directory.
  346. * +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If
  347. set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+
  348. variable are executed to install the package into the images
  349. directory.
  350. * +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
  351. '$(STAGING_DIR)/usr/bin' that need some special fixing to make them
  352. cross-compiling friendly. Multiple file names separated by space can
  353. be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
  354. listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
  355. +$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
  356. * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
  357. when using the static device table. The syntax to use is the
  358. makedevs one. You can find some documentation for this syntax in the
  359. xref:makedev-syntax[]. This variable is optional.
  360. * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
  361. the end of the build process. The syntax is once again the makedevs one.
  362. You can find some documentation for this syntax in the xref:makedev-syntax[].
  363. This variable is optional.
  364. * +LIBFOO_USERS+ lists the users to create for this package, if it installs
  365. a program you want to run as a specific user (e.g. as a daemon, or as a
  366. cron-job). The syntax is similar in spirit to the makedevs one, and is
  367. described in the xref:makeuser-syntax[]. This variable is optional.
  368. * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
  369. is released.
  370. This name will appear in the manifest file produced by +make legal-info+.
  371. If the license appears in https://spdx.org/licenses/[the SPDX License List],
  372. use the SPDX short identifier to make the manifest file uniform.
  373. Otherwise, describe the license in a precise and concise way, avoiding
  374. ambiguous names such as +BSD+ which actually name a family of licenses.
  375. This variable is optional. If it is not defined, +unknown+ will appear in
  376. the +license+ field of the manifest file for this package. +
  377. The expected format for this variable must comply with the following rules:
  378. ** If different parts of the package are released under different
  379. licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE =
  380. GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which
  381. component is licensed under what license, then annotate the license
  382. with that component, between parenthesis (e.g. +`LIBFOO_LICENSE =
  383. GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+).
  384. ** If some licenses are conditioned on a sub-option being enabled, append
  385. the conditional licenses with a comma (e.g.: `FOO_LICENSE += , GPL-2.0+
  386. (programs)`); the infrastructure will internally remove the space before
  387. the comma.
  388. ** If the package is dual licensed, then separate licenses with the
  389. +or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+).
  390. * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
  391. tarball that contain the license(s) under which the package is released.
  392. +make legal-info+ copies all of these files in the +legal-info+ directory.
  393. See xref:legal-info[] for more information.
  394. This variable is optional. If it is not defined, a warning will be produced
  395. to let you know, and +not saved+ will appear in the +license files+ field
  396. of the manifest file for this package.
  397. * +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose
  398. +LIBFOO_SITE+ / +LIBFOO_SOURCE+ pair points to an archive that does
  399. not actually contain source code, but binary code. This a very
  400. uncommon case, only known to apply to external toolchains which come
  401. already compiled, although theoretically it might apply to other
  402. packages. In such cases a separate tarball is usually available with
  403. the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the
  404. name of the actual source code archive and Buildroot will download
  405. it and use it when you run +make legal-info+ to collect
  406. legally-relevant material. Note this file will not be downloaded
  407. during regular builds nor by +make source+.
  408. * +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual
  409. source tarball. The default value is +LIBFOO_SITE+, so you don't
  410. need to set this variable if the binary and source archives are
  411. hosted on the same directory. If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is
  412. not set, it doesn't make sense to define
  413. +LIBFOO_ACTUAL_SOURCE_SITE+.
  414. * +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
  415. the package source code is allowed to be redistributed. Set it to +NO+ for
  416. non-opensource packages: Buildroot will not save the source code for this
  417. package when collecting the +legal-info+.
  418. * +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
  419. the FLAT binary format. The application stack size on the NOMMU architecture
  420. processors can't be enlarged at run time. The default stack size for the
  421. FLAT binary format is only 4k bytes. If the application consumes more stack,
  422. append the required number here.
  423. * +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative
  424. to the target directory) to ignore when checking that the package
  425. installs correctly cross-compiled binaries. You seldom need to set this
  426. variable, unless the package installs binary blobs outside the default
  427. locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`,
  428. `/usr/lib/modules`, and `/usr/share`, which are automatically excluded.
  429. * +LIBFOO_IGNORE_CVES+ is a space-separated list of CVEs that tells
  430. Buildroot CVE tracking tools which CVEs should be ignored for this
  431. package. This is typically used when the CVE is fixed by a patch in
  432. the package, or when the CVE for some reason does not affect the
  433. Buildroot package. A Makefile comment must always precede the
  434. addition of a CVE to this variable. Example:
  435. ----------------------
  436. # 0001-fix-cve-2020-12345.patch
  437. LIBFOO_IGNORE_CVES += CVE-2020-12345
  438. # only when built with libbaz, which Buildroot doesn't support
  439. LIBFOO_IGNORE_CVES += CVE-2020-54321
  440. ----------------------
  441. The recommended way to define these variables is to use the following
  442. syntax:
  443. ----------------------
  444. LIBFOO_VERSION = 2.32
  445. ----------------------
  446. Now, the variables that define what should be performed at the
  447. different steps of the build process.
  448. * +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
  449. the package. This is generally not needed as tarballs are
  450. automatically handled by Buildroot. However, if the package uses a
  451. non-standard archive format, such as a ZIP or RAR file, or has a
  452. tarball with a non-standard organization, this variable allows to
  453. override the package infrastructure default behavior.
  454. * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
  455. configure the package before its compilation.
  456. * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
  457. compile the package.
  458. * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
  459. to install the package, when the package is a host package. The
  460. package must install its files to the directory given by
  461. +$(HOST_DIR)+. All files, including development files such as
  462. headers should be installed, since other packages might be compiled
  463. on top of this package.
  464. * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
  465. performed to install the package to the target directory, when the
  466. package is a target package. The package must install its files to
  467. the directory given by +$(TARGET_DIR)+. Only the files required for
  468. 'execution' of the package have to be
  469. installed. Header files, static libraries and documentation will be
  470. removed again when the target filesystem is finalized.
  471. * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
  472. performed to install the package to the staging directory, when the
  473. package is a target package. The package must install its files to
  474. the directory given by +$(STAGING_DIR)+. All development files
  475. should be installed, since they might be needed to compile other
  476. packages.
  477. * +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to
  478. install the package to the images directory, when the package is a
  479. target package. The package must install its files to the directory
  480. given by +$(BINARIES_DIR)+. Only files that are binary images (aka
  481. images) that do not belong in the +TARGET_DIR+ but are necessary
  482. for booting the board should be placed here. For example, a package
  483. should utilize this step if it has binaries which would be similar
  484. to the kernel image, bootloader or root filesystem images.
  485. * +LIBFOO_INSTALL_INIT_SYSV+, +LIBFOO_INSTALL_INIT_OPENRC+ and
  486. +LIBFOO_INSTALL_INIT_SYSTEMD+ list the actions to install init
  487. scripts either for the systemV-like init systems (busybox,
  488. sysvinit, etc.), openrc or for the systemd units. These commands
  489. will be run only when the relevant init system is installed (i.e.
  490. if systemd is selected as the init system in the configuration,
  491. only +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). The only exception
  492. is when openrc is chosen as init system and +LIBFOO_INSTALL_INIT_OPENRC+
  493. has not been set, in such situation +LIBFOO_INSTALL_INIT_SYSV+ will
  494. be called, since openrc supports sysv init scripts.
  495. When systemd is used as the init system, buildroot will automatically enable
  496. all services using the +systemctl preset-all+ command in the final phase of
  497. image building. You can add preset files to prevent a particular unit from
  498. being automatically enabled by buildroot.
  499. * +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
  500. is included to the main +make help+ output. These commands can print
  501. anything in any format.
  502. This is seldom used, as packages rarely have custom rules. *Do not use
  503. this variable*, unless you really know that you need to print help.
  504. * +LIBFOO_LINUX_CONFIG_FIXUPS+ lists the Linux kernel configuration
  505. options that are needed to build and use this package, and without
  506. which the package is fundamentally broken. This shall be a set of
  507. calls to one of the kconfig tweaking option: `KCONFIG_ENABLE_OPT`,
  508. `KCONFIG_DISABLE_OPT`, or `KCONFIG_SET_OPT`.
  509. This is seldom used, as package usually have no strict requirements on
  510. the kernel options.
  511. The preferred way to define these variables is:
  512. ----------------------
  513. define LIBFOO_CONFIGURE_CMDS
  514. action 1
  515. action 2
  516. action 3
  517. endef
  518. ----------------------
  519. In the action definitions, you can use the following variables:
  520. * +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the
  521. +libfoo.mk+ and +Config.in+ files. This variable is useful when it is
  522. necessary to install a file bundled in Buildroot, like a runtime
  523. configuration file, a splashscreen image...
  524. * +$(@D)+, which contains the directory in which the package source
  525. code has been uncompressed.
  526. * +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads
  527. made by Buildroot for +libfoo+ are stored in.
  528. * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
  529. cross-compilation utilities
  530. * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
  531. * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
  532. variables to install the packages properly. Those variables point to
  533. the global _host_, _staging_ and _target_ directories, unless
  534. _per-package directory_ support is used, in which case they point to
  535. the current package _host_, _staging_ and _target_ directories. In
  536. both cases, it doesn't make any difference from the package point of
  537. view: it should simply use +HOST_DIR+, +STAGING_DIR+ and
  538. +TARGET_DIR+. See xref:top-level-parallel-build[] for more details
  539. about _per-package directory_ support.
  540. Finally, you can also use hooks. See xref:hooks[] for more information.