adding-packages-directory.txt 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Package directory
  4. First of all, create a directory under the +package+ directory for
  5. your software, for example +libfoo+.
  6. Some packages have been grouped by topic in a sub-directory:
  7. +x11r7+, +qt5+ and +gstreamer+. If your package fits in
  8. one of these categories, then create your package directory in these.
  9. New subdirectories are discouraged, however.
  10. === Config files
  11. For the package to be displayed in the configuration tool, you need to
  12. create a Config file in your package directory. There are two types:
  13. +Config.in+ and +Config.in.host+.
  14. ==== +Config.in+ file
  15. For packages used on the target, create a file named +Config.in+. This
  16. file will contain the option descriptions related to our +libfoo+ software
  17. that will be used and displayed in the configuration tool. It should basically
  18. contain:
  19. ---------------------------
  20. config BR2_PACKAGE_LIBFOO
  21. bool "libfoo"
  22. help
  23. This is a comment that explains what libfoo is. The help text
  24. should be wrapped.
  25. http://foosoftware.org/libfoo/
  26. ---------------------------
  27. The +bool+ line, +help+ line and other metadata information about the
  28. configuration option must be indented with one tab. The help text
  29. itself should be indented with one tab and two spaces, lines should
  30. be wrapped to fit 72 columns, where tab counts for 8, so 62 characters
  31. in the text itself. The help text must mention the upstream URL of the
  32. project after an empty line.
  33. As a convention specific to Buildroot, the ordering of the attributes
  34. is as follows:
  35. 1. The type of option: +bool+, +string+... with the prompt
  36. 2. If needed, the +default+ value(s)
  37. 3. Any dependencies on the target in +depends on+ form
  38. 4. Any dependencies on the toolchain in +depends on+ form
  39. 5. Any dependencies on other packages in +depends on+ form
  40. 6. Any dependency of the +select+ form
  41. 7. The help keyword and help text.
  42. You can add other sub-options into a +if BR2_PACKAGE_LIBFOO...endif+
  43. statement to configure particular things in your software. You can look at
  44. examples in other packages. The syntax of the +Config.in+ file is the same
  45. as the one for the kernel Kconfig file. The documentation for this syntax is
  46. available at http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]
  47. Finally you have to add your new +libfoo/Config.in+ to
  48. +package/Config.in+ (or in a category subdirectory if you decided to
  49. put your package in one of the existing categories). The files
  50. included there are 'sorted alphabetically' per category and are 'NOT'
  51. supposed to contain anything but the 'bare' name of the package.
  52. --------------------------
  53. source "package/libfoo/Config.in"
  54. --------------------------
  55. ==== +Config.in.host+ file
  56. Some packages also need to be built for the host system. There are two
  57. options here:
  58. * The host package is only required to satisfy build-time
  59. dependencies of one or more target packages. In this case, add
  60. +host-foo+ to the target package's +BAR_DEPENDENCIES+ variable. No
  61. +Config.in.host+ file should be created.
  62. * The host package should be explicitly selectable by the user from
  63. the configuration menu. In this case, create a +Config.in.host+ file
  64. for that host package:
  65. +
  66. ---------------------------
  67. config BR2_PACKAGE_HOST_FOO
  68. bool "host foo"
  69. help
  70. This is a comment that explains what foo for the host is.
  71. http://foosoftware.org/foo/
  72. ---------------------------
  73. +
  74. The same coding style and options as for the +Config.in+ file are valid.
  75. +
  76. Finally you have to add your new +libfoo/Config.in.host+ to
  77. +package/Config.in.host+. The files included there are 'sorted alphabetically'
  78. and are 'NOT' supposed to contain anything but the 'bare' name of the package.
  79. +
  80. --------------------------
  81. source "package/foo/Config.in.host"
  82. --------------------------
  83. +
  84. The host package will then be available from the +Host utilities+ menu.
  85. [[depends-on-vs-select]]
  86. ==== Choosing +depends on+ or +select+
  87. The +Config.in+ file of your package must also ensure that
  88. dependencies are enabled. Typically, Buildroot uses the following
  89. rules:
  90. * Use a +select+ type of dependency for dependencies on
  91. libraries. These dependencies are generally not obvious and it
  92. therefore make sense to have the kconfig system ensure that the
  93. dependencies are selected. For example, the _libgtk2_ package uses
  94. +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
  95. enabled.
  96. The +select+ keyword expresses the dependency with a backward
  97. semantic.
  98. * Use a +depends on+ type of dependency when the user really needs to
  99. be aware of the dependency. Typically, Buildroot uses this type of
  100. dependency for dependencies on target architecture, MMU support and
  101. toolchain options (see xref:dependencies-target-toolchain-options[]),
  102. or for dependencies on "big" things, such as the X.org system.
  103. The +depends on+ keyword expresses the dependency with a forward
  104. semantic.
  105. .Note
  106. The current problem with the _kconfig_ language is that these two
  107. dependency semantics are not internally linked. Therefore, it may be
  108. possible to select a package, whom one of its dependencies/requirement
  109. is not met.
  110. An example illustrates both the usage of +select+ and +depends on+.
  111. --------------------------
  112. config BR2_PACKAGE_RRDTOOL
  113. bool "rrdtool"
  114. depends on BR2_USE_WCHAR
  115. select BR2_PACKAGE_FREETYPE
  116. select BR2_PACKAGE_LIBART
  117. select BR2_PACKAGE_LIBPNG
  118. select BR2_PACKAGE_ZLIB
  119. help
  120. RRDtool is the OpenSource industry standard, high performance
  121. data logging and graphing system for time series data.
  122. http://oss.oetiker.ch/rrdtool/
  123. comment "rrdtool needs a toolchain w/ wchar"
  124. depends on !BR2_USE_WCHAR
  125. --------------------------
  126. Note that these two dependency types are only transitive with the
  127. dependencies of the same kind.
  128. This means, in the following example:
  129. --------------------------
  130. config BR2_PACKAGE_A
  131. bool "Package A"
  132. config BR2_PACKAGE_B
  133. bool "Package B"
  134. depends on BR2_PACKAGE_A
  135. config BR2_PACKAGE_C
  136. bool "Package C"
  137. depends on BR2_PACKAGE_B
  138. config BR2_PACKAGE_D
  139. bool "Package D"
  140. select BR2_PACKAGE_B
  141. config BR2_PACKAGE_E
  142. bool "Package E"
  143. select BR2_PACKAGE_D
  144. --------------------------
  145. * Selecting +Package C+ will be visible if +Package B+ has been
  146. selected, which in turn is only visible if +Package A+ has been
  147. selected.
  148. * Selecting +Package E+ will select +Package D+, which will select
  149. +Package B+, it will not check for the dependencies of +Package B+,
  150. so it will not select +Package A+.
  151. * Since +Package B+ is selected but +Package A+ is not, this violates
  152. the dependency of +Package B+ on +Package A+. Therefore, in such a
  153. situation, the transitive dependency has to be added explicitly:
  154. --------------------------
  155. config BR2_PACKAGE_D
  156. bool "Package D"
  157. select BR2_PACKAGE_B
  158. depends on BR2_PACKAGE_A
  159. config BR2_PACKAGE_E
  160. bool "Package E"
  161. select BR2_PACKAGE_D
  162. depends on BR2_PACKAGE_A
  163. --------------------------
  164. Overall, for package library dependencies, +select+ should be
  165. preferred.
  166. Note that such dependencies will ensure that the dependency option
  167. is also enabled, but not necessarily built before your package. To do
  168. so, the dependency also needs to be expressed in the +.mk+ file of the
  169. package.
  170. Further formatting details: see xref:writing-rules-config-in[the
  171. coding style].
  172. [[dependencies-target-toolchain-options]]
  173. ==== Dependencies on target and toolchain options
  174. Many packages depend on certain options of the toolchain: the choice of
  175. C library, C++ support, thread support, RPC support, wchar support,
  176. or dynamic library support. Some packages can only be built on certain
  177. target architectures, or if an MMU is available in the processor.
  178. These dependencies have to be expressed with the appropriate 'depends
  179. on' statements in the Config.in file. Additionally, for dependencies on
  180. toolchain options, a +comment+ should be displayed when the option is
  181. not enabled, so that the user knows why the package is not available.
  182. Dependencies on target architecture or MMU support should not be
  183. made visible in a comment: since it is unlikely that the user can
  184. freely choose another target, it makes little sense to show these
  185. dependencies explicitly.
  186. The +comment+ should only be visible if the +config+ option itself would
  187. be visible when the toolchain option dependencies are met. This means
  188. that all other dependencies of the package (including dependencies on
  189. target architecture and MMU support) have to be repeated on the
  190. +comment+ definition. To keep it clear, the +depends on+ statement for
  191. these non-toolchain option should be kept separate from the +depends on+
  192. statement for the toolchain options.
  193. If there is a dependency on a config option in that same file (typically
  194. the main package) it is preferable to have a global +if ... endif+
  195. construct rather than repeating the +depends on+ statement on the
  196. comment and other config options.
  197. The general format of a dependency +comment+ for package foo is:
  198. --------------------------
  199. foo needs a toolchain w/ featA, featB, featC
  200. --------------------------
  201. for example:
  202. --------------------------
  203. mpd needs a toolchain w/ C++, threads, wchar
  204. --------------------------
  205. or
  206. --------------------------
  207. crda needs a toolchain w/ threads
  208. --------------------------
  209. Note that this text is kept brief on purpose, so that it will fit on a
  210. 80-character terminal.
  211. The rest of this section enumerates the different target and toolchain
  212. options, the corresponding config symbols to depend on, and the text to
  213. use in the comment.
  214. * Target architecture
  215. ** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+)
  216. ** Comment string: no comment to be added
  217. * MMU support
  218. ** Dependency symbol: +BR2_USE_MMU+
  219. ** Comment string: no comment to be added
  220. * Gcc +__sync_*+ built-ins used for atomic operations. They are
  221. available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
  222. bytes. Since different architectures support atomic operations on
  223. different sizes, one dependency symbol is available for each size:
  224. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_SYNC_1+ for 1 byte,
  225. +BR2_TOOLCHAIN_HAS_SYNC_2+ for 2 bytes,
  226. +BR2_TOOLCHAIN_HAS_SYNC_4+ for 4 bytes, +BR2_TOOLCHAIN_HAS_SYNC_8+
  227. for 8 bytes.
  228. ** Comment string: no comment to be added
  229. * Gcc +__atomic_*+ built-ins used for atomic operations.
  230. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_ATOMIC+.
  231. ** Comment string: no comment to be added
  232. * Kernel headers
  233. ** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
  234. +X_Y+ with the proper version, see +toolchain/Config.in+)
  235. ** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
  236. +X.Y+ with the proper version)
  237. * GCC version
  238. ** Dependency symbol: +BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y+, (replace
  239. +X_Y+ with the proper version, see +toolchain/Config.in+)
  240. ** Comment string: +gcc >= X.Y+ and/or `gcc <= X.Y` (replace
  241. +X.Y+ with the proper version)
  242. * Host GCC version
  243. ** Dependency symbol: +BR2_HOST_GCC_AT_LEAST_X_Y+, (replace
  244. +X_Y+ with the proper version, see +Config.in+)
  245. ** Comment string: no comment to be added
  246. ** Note that it is usually not the package itself that has a minimum
  247. host GCC version, but rather a host-package on which it depends.
  248. * C library
  249. ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,
  250. +BR2_TOOLCHAIN_USES_MUSL+, +BR2_TOOLCHAIN_USES_UCLIBC+
  251. ** Comment string: for the C library, a slightly different comment text
  252. is used: +foo needs a glibc toolchain+, or `foo needs a glibc
  253. toolchain w/ C++`
  254. * C++ support
  255. ** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+
  256. ** Comment string: `C++`
  257. * D support
  258. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_DLANG+
  259. ** Comment string: `Dlang`
  260. * Fortran support
  261. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_FORTRAN+
  262. ** Comment string: `fortran`
  263. * thread support
  264. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+
  265. ** Comment string: +threads+ (unless +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
  266. is also needed, in which case, specifying only +NPTL+ is sufficient)
  267. * NPTL thread support
  268. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
  269. ** Comment string: +NPTL+
  270. * RPC support
  271. ** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+
  272. ** Comment string: +RPC+
  273. * wchar support
  274. ** Dependency symbol: +BR2_USE_WCHAR+
  275. ** Comment string: +wchar+
  276. * dynamic library
  277. ** Dependency symbol: +!BR2_STATIC_LIBS+
  278. ** Comment string: +dynamic library+
  279. ==== Dependencies on a Linux kernel built by buildroot
  280. Some packages need a Linux kernel to be built by buildroot. These are
  281. typically kernel modules or firmware. A comment should be added in the
  282. Config.in file to express this dependency, similar to dependencies on
  283. toolchain options. The general format is:
  284. --------------------------
  285. foo needs a Linux kernel to be built
  286. --------------------------
  287. If there is a dependency on both toolchain options and the Linux
  288. kernel, use this format:
  289. --------------------------
  290. foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
  291. --------------------------
  292. ==== Dependencies on udev /dev management
  293. If a package needs udev /dev management, it should depend on symbol
  294. +BR2_PACKAGE_HAS_UDEV+, and the following comment should be added:
  295. --------------------------
  296. foo needs udev /dev management
  297. --------------------------
  298. If there is a dependency on both toolchain options and udev /dev
  299. management, use this format:
  300. --------------------------
  301. foo needs udev /dev management and a toolchain w/ featA, featB, featC
  302. --------------------------
  303. ==== Dependencies on features provided by virtual packages
  304. Some features can be provided by more than one package, such as the
  305. openGL libraries.
  306. See xref:virtual-package-tutorial[] for more on the virtual packages.
  307. === The +.mk+ file
  308. [[adding-packages-mk]]
  309. Finally, here's the hardest part. Create a file named +libfoo.mk+. It
  310. describes how the package should be downloaded, configured, built,
  311. installed, etc.
  312. Depending on the package type, the +.mk+ file must be written in a
  313. different way, using different infrastructures:
  314. * *Makefiles for generic packages* (not using autotools or CMake):
  315. These are based on an infrastructure similar to the one used for
  316. autotools-based packages, but require a little more work from the
  317. developer. They specify what should be done for the configuration,
  318. compilation and installation of the package. This
  319. infrastructure must be used for all packages that do not use the
  320. autotools as their build system. In the future, other specialized
  321. infrastructures might be written for other build systems. We cover
  322. them through in a xref:generic-package-tutorial[tutorial] and a
  323. xref:generic-package-reference[reference].
  324. * *Makefiles for autotools-based software* (autoconf, automake, etc.):
  325. We provide a dedicated infrastructure for such packages, since
  326. autotools is a very common build system. This infrastructure 'must'
  327. be used for new packages that rely on the autotools as their build
  328. system. We cover them through a xref:autotools-package-tutorial[tutorial]
  329. and xref:autotools-package-reference[reference].
  330. * *Makefiles for cmake-based software*: We provide a dedicated
  331. infrastructure for such packages, as CMake is a more and more
  332. commonly used build system and has a standardized behaviour. This
  333. infrastructure 'must' be used for new packages that rely on
  334. CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
  335. and xref:cmake-package-reference[reference].
  336. * *Makefiles for Python modules*: We have a dedicated infrastructure
  337. for Python modules that use either the +distutils+ or the
  338. +setuptools+ mechanism. We cover them through a
  339. xref:python-package-tutorial[tutorial] and a
  340. xref:python-package-reference[reference].
  341. * *Makefiles for Lua modules*: We have a dedicated infrastructure for
  342. Lua modules available through the LuaRocks web site. We cover them
  343. through a xref:luarocks-package-tutorial[tutorial] and a
  344. xref:luarocks-package-reference[reference].
  345. Further formatting details: see xref:writing-rules-mk[the writing
  346. rules].
  347. [[adding-packages-hash]]
  348. === The +.hash+ file
  349. When possible, you must add a third file, named +libfoo.hash+, that
  350. contains the hashes of the downloaded files for the +libfoo+
  351. package. The only reason for not adding a +.hash+ file is when hash
  352. checking is not possible due to how the package is downloaded.
  353. When a package has a version selection choice, then the hash file may be
  354. stored in a subdirectory named after the version, e.g.
  355. +package/libfoo/1.2.3/libfoo.hash+. This is especially important if the
  356. different versions have different licensing terms, but they are stored
  357. in the same file. Otherwise, the hash file should stay in the package's
  358. directory.
  359. The hashes stored in that file are used to validate the integrity of the
  360. downloaded files and of the license files.
  361. The format of this file is one line for each file for which to check the
  362. hash, each line with the following three fields separated by two spaces:
  363. * the type of hash, one of:
  364. ** +md5+, +sha1+, +sha224+, +sha256+, +sha384+, +sha512+, +none+
  365. * the hash of the file:
  366. ** for +none+, one or more non-space chars, usually just the string +xxx+
  367. ** for +md5+, 32 hexadecimal characters
  368. ** for +sha1+, 40 hexadecimal characters
  369. ** for +sha224+, 56 hexadecimal characters
  370. ** for +sha256+, 64 hexadecimal characters
  371. ** for +sha384+, 96 hexadecimal characters
  372. ** for +sha512+, 128 hexadecimal characters
  373. * the name of the file:
  374. ** for a source archive: the basename of the file, without any directory
  375. component,
  376. ** for a license file: the path as it appears in +FOO_LICENSE_FILES+.
  377. Lines starting with a +#+ sign are considered comments, and ignored. Empty
  378. lines are ignored.
  379. There can be more than one hash for a single file, each on its own line. In
  380. this case, all hashes must match.
  381. .Note
  382. Ideally, the hashes stored in this file should match the hashes published by
  383. upstream, e.g. on their website, in the e-mail announcement... If upstream
  384. provides more than one type of hash (e.g. +sha1+ and +sha512+), then it is
  385. best to add all those hashes in the +.hash+ file. If upstream does not
  386. provide any hash, or only provides an +md5+ hash, then compute at least one
  387. strong hash yourself (preferably +sha256+, but not +md5+), and mention
  388. this in a comment line above the hashes.
  389. .Note
  390. The hashes for license files are used to detect a license change when a
  391. package version is bumped. The hashes are checked during the make legal-info
  392. target run. For a package with multiple versions (like Qt5),
  393. create the hash file in a subdirectory +<packageversion>+ of that package
  394. (see also xref:patch-apply-order[]).
  395. The +none+ hash type is reserved to those archives downloaded from a
  396. repository, like a 'git clone', a 'subversion checkout'...
  397. The example below defines a +sha1+ and a +sha256+ published by upstream for
  398. the main +libfoo-1.2.3.tar.bz2+ tarball, an +md5+ from upstream and a
  399. locally-computed +sha256+ hashes for a binary blob, a +sha256+ for a
  400. downloaded patch, and an archive with no hash:
  401. ----
  402. # Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
  403. sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
  404. sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
  405. # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
  406. md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
  407. sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin
  408. # Locally computed:
  409. sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
  410. # No hash for 1234:
  411. none xxx libfoo-1234.tar.gz
  412. # Hash for license files:
  413. sha256 a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8 COPYING
  414. sha256 01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55 doc/COPYING.LGPL
  415. ----
  416. If the +.hash+ file is present, and it contains one or more hashes for a
  417. downloaded file, the hash(es) computed by Buildroot (after download) must
  418. match the hash(es) stored in the +.hash+ file. If one or more hashes do
  419. not match, Buildroot considers this an error, deletes the downloaded file,
  420. and aborts.
  421. If the +.hash+ file is present, but it does not contain a hash for a
  422. downloaded file, Buildroot considers this an error and aborts. However,
  423. the downloaded file is left in the download directory since this
  424. typically indicates that the +.hash+ file is wrong but the downloaded
  425. file is probably OK.
  426. Hashes are currently checked for files fetched from http/ftp servers,
  427. Git repositories, files copied using scp and local files. Hashes are
  428. not checked for other version control systems (such as Subversion,
  429. CVS, etc.) because Buildroot currently does not generate reproducible
  430. tarballs when source code is fetched from such version control
  431. systems.
  432. Hashes should only be added in +.hash+ files for files that are
  433. guaranteed to be stable. For example, patches auto-generated by Github
  434. are not guaranteed to be stable, and therefore their hashes can change
  435. over time. Such patches should not be downloaded, and instead be added
  436. locally to the package folder.
  437. If the +.hash+ file is missing, then no check is done at all.