2 // vim: set syntax=asciidoc:
6 First of all, create a directory under the +package+ directory for
7 your software, for example +libfoo+.
9 Some packages have been grouped by topic in a sub-directory:
10 +x11r7+, +efl+ and +matchbox+. If your package fits in
11 one of these categories, then create your package directory in these.
12 New subdirectories are discouraged, however.
16 For the package to be displayed in the configuration tool, you need to
17 create a Config file in your package directory. There are two types:
18 +Config.in+ and +Config.in.host+.
22 For packages used on the target, create a file named +Config.in+. This
23 file will contain the option descriptions related to our +libfoo+ software
24 that will be used and displayed in the configuration tool. It should basically
27 ---------------------------
28 config BR2_PACKAGE_LIBFOO
31 This is a comment that explains what libfoo is.
33 http://foosoftware.org/libfoo/
34 ---------------------------
36 The +bool+ line, +help+ line and other metadata information about the
37 configuration option must be indented with one tab. The help text
38 itself should be indented with one tab and two spaces, and it must
39 mention the upstream URL of the project.
41 You can add other sub-options into a +if
42 BR2_PACKAGE_LIBFOO...endif+ statement to configure particular things
43 in your software. You can look at examples in other packages. The
44 syntax of the +Config.in+ file is the same as the one for the kernel
45 Kconfig file. The documentation for this syntax is available at
46 http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]
48 Finally you have to add your new +libfoo/Config.in+ to
49 +package/Config.in+ (or in a category subdirectory if you decided to
50 put your package in one of the existing categories). The files
51 included there are 'sorted alphabetically' per category and are 'NOT'
52 supposed to contain anything but the 'bare' name of the package.
54 --------------------------
55 source "package/libfoo/Config.in"
56 --------------------------
59 ==== +Config.in.host+ file
61 Some packages also need to be built for the host system. There are two
64 * The host package is only required to satisfy build-time
65 dependencies of one or more target packages. In this case, add
66 +host-foo+ to the target package's +BAR_DEPENDENCIES+ variable. No
67 +Config.in.host+ file should be created.
69 * The host package should be explicitly selectable by the user from
70 the configuration menu. In this case, create a +Config.in.host+ file
71 for that host package:
73 ---------------------------
74 config BR2_PACKAGE_HOST_FOO
77 This is a comment that explains what foo for the host is.
79 http://foosoftware.org/foo/
80 ---------------------------
82 The same coding style and options as for the +Config.in+ file are valid.
84 Finally you have to add your new +libfoo/Config.in.host+ to
85 +package/Config.in.host+. The files included there are 'sorted alphabetically'
86 and are 'NOT' supposed to contain anything but the 'bare' name of the package.
88 --------------------------
89 source "package/foo/Config.in.host"
90 --------------------------
92 The host package will then be available from the +Host utilities+ menu.
94 [[depends-on-vs-select]]
95 ==== Choosing +depends on+ or +select+
97 The +Config.in+ file of your package must also ensure that
98 dependencies are enabled. Typically, Buildroot uses the following
101 * Use a +select+ type of dependency for dependencies on
102 libraries. These dependencies are generally not obvious and it
103 therefore make sense to have the kconfig system ensure that the
104 dependencies are selected. For example, the _libgtk2_ package uses
105 +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also
107 The +select+ keyword expresses the dependency with a backward
110 * Use a +depends on+ type of dependency when the user really needs to
111 be aware of the dependency. Typically, Buildroot uses this type of
112 dependency for dependencies on target architecture, MMU support and
113 toolchain options (see xref:dependencies-target-toolchain-options[]),
114 or for dependencies on "big" things, such as the X.org system.
115 The +depends on+ keyword expresses the dependency with a forward
119 The current problem with the _kconfig_ language is that these two
120 dependency semantics are not internally linked. Therefore, it may be
121 possible to select a package, whom one of its dependencies/requirement
124 An example illustrates both the usage of +select+ and +depends on+.
126 --------------------------
127 config BR2_PACKAGE_RRDTOOL
129 depends on BR2_USE_WCHAR
130 select BR2_PACKAGE_FREETYPE
131 select BR2_PACKAGE_LIBART
132 select BR2_PACKAGE_LIBPNG
133 select BR2_PACKAGE_ZLIB
135 RRDtool is the OpenSource industry standard, high performance
136 data logging and graphing system for time series data.
138 http://oss.oetiker.ch/rrdtool/
140 comment "rrdtool needs a toolchain w/ wchar"
141 depends on !BR2_USE_WCHAR
142 --------------------------
145 Note that these two dependency types are only transitive with the
146 dependencies of the same kind.
148 This means, in the following example:
150 --------------------------
156 depends on BR2_PACKAGE_A
160 depends on BR2_PACKAGE_B
169 --------------------------
171 * Selecting +Package C+ will be visible if +Package B+ has been
172 selected, which in turn is only visible if +Package A+ has been
175 * Selecting +Package E+ will select +Package D+, which will select
176 +Package B+, it will not check for the dependencies of +Package B+,
177 so it will not select +Package A+.
179 * Since +Package B+ is selected but +Package A+ is not, this violates
180 the dependency of +Package B+ on +Package A+. Therefore, in such a
181 situation, the transitive dependency has to be added explicitly:
183 --------------------------
187 depends on BR2_PACKAGE_A
192 depends on BR2_PACKAGE_A
193 --------------------------
195 Overall, for package library dependencies, +select+ should be
198 Note that such dependencies will ensure that the dependency option
199 is also enabled, but not necessarily built before your package. To do
200 so, the dependency also needs to be expressed in the +.mk+ file of the
203 Further formatting details: see xref:writing-rules-config-in[the
206 [[dependencies-target-toolchain-options]]
207 ==== Dependencies on target and toolchain options
209 Many packages depend on certain options of the toolchain: the choice of
210 C library, C++ support, thread support, RPC support, wchar support,
211 or dynamic library support. Some packages can only be built on certain
212 target architectures, or if an MMU is available in the processor.
214 These dependencies have to be expressed with the appropriate 'depends
215 on' statements in the Config.in file. Additionally, for dependencies on
216 toolchain options, a +comment+ should be displayed when the option is
217 not enabled, so that the user knows why the package is not available.
218 Dependencies on target architecture or MMU support should not be
219 made visible in a comment: since it is unlikely that the user can
220 freely choose another target, it makes little sense to show these
221 dependencies explicitly.
223 The +comment+ should only be visible if the +config+ option itself would
224 be visible when the toolchain option dependencies are met. This means
225 that all other dependencies of the package (including dependencies on
226 target architecture and MMU support) have to be repeated on the
227 +comment+ definition. To keep it clear, the +depends on+ statement for
228 these non-toolchain option should be kept separate from the +depends on+
229 statement for the toolchain options.
230 If there is a dependency on a config option in that same file (typically
231 the main package) it is preferable to have a global +if ... endif+
232 construct rather than repeating the +depends on+ statement on the
233 comment and other config options.
235 The general format of a dependency +comment+ for package foo is:
237 --------------------------
238 foo needs a toolchain w/ featA, featB, featC
239 --------------------------
243 --------------------------
244 mpd needs a toolchain w/ C++, threads, wchar
245 --------------------------
249 --------------------------
250 crda needs a toolchain w/ threads
251 --------------------------
253 Note that this text is kept brief on purpose, so that it will fit on a
254 80-character terminal.
256 The rest of this section enumerates the different target and toolchain
257 options, the corresponding config symbols to depend on, and the text to
260 * Target architecture
261 ** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+)
262 ** Comment string: no comment to be added
265 ** Dependency symbol: +BR2_USE_MMU+
266 ** Comment string: no comment to be added
268 * Atomic instructions (whereby the architecture has instructions to
269 perform some operations atomically, like LOCKCMPXCHG on x86)
270 ** Dependency symbol: +BR2_ARCH_HAS_ATOMICS+
271 ** Comment string: no comment to be added
274 ** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
275 +X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
276 ** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
277 +X.Y+ with the proper version)
280 ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,
281 +BR2_TOOLCHAIN_USES_MUSL+, +BR2_TOOLCHAIN_USES_UCLIBC+
282 ** Comment string: for the C library, a slightly different comment text
283 is used: +foo needs an (e)glibc toolchain+, or `foo needs an (e)glibc
287 ** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+
288 ** Comment string: `C++`
291 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+
292 ** Comment string: +threads+ (unless +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
293 is also needed, in which case, specifying only +NPTL+ is sufficient)
295 * NPTL thread support
296 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS_NPTL+
297 ** Comment string: +NPTL+
300 ** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+
301 ** Comment string: +RPC+
304 ** Dependency symbol: +BR2_USE_WCHAR+
305 ** Comment string: +wchar+
308 ** Dependency symbol: +!BR2_STATIC_LIBS+
309 ** Comment string: +dynamic library+
311 ==== Dependencies on a Linux kernel built by buildroot
313 Some packages need a Linux kernel to be built by buildroot. These are
314 typically kernel modules or firmware. A comment should be added in the
315 Config.in file to express this dependency, similar to dependencies on
316 toolchain options. The general format is:
318 --------------------------
319 foo needs a Linux kernel to be built
320 --------------------------
322 If there is a dependency on both toolchain options and the Linux
323 kernel, use this format:
325 --------------------------
326 foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
327 --------------------------
329 ==== Dependencies on udev /dev management
331 If a package needs udev /dev management, it should depend on symbol
332 +BR2_PACKAGE_HAS_UDEV+, and the following comment should be added:
334 --------------------------
335 foo needs udev /dev management
336 --------------------------
338 If there is a dependency on both toolchain options and udev /dev
339 management, use this format:
341 --------------------------
342 foo needs udev /dev management and a toolchain w/ featA, featB, featC
343 --------------------------
345 ==== Dependencies on features provided by virtual packages
347 Some features can be provided by more than one package, such as the
350 See xref:virtual-package-tutorial[] for more on the virtual packages.
352 See xref:virtual-package-list[] for the symbols to depend on if your package
353 depends on a feature provided by a virtual package.
357 [[adding-packages-mk]]
359 Finally, here's the hardest part. Create a file named +libfoo.mk+. It
360 describes how the package should be downloaded, configured, built,
363 Depending on the package type, the +.mk+ file must be written in a
364 different way, using different infrastructures:
366 * *Makefiles for generic packages* (not using autotools or CMake):
367 These are based on an infrastructure similar to the one used for
368 autotools-based packages, but require a little more work from the
369 developer. They specify what should be done for the configuration,
370 compilation and installation of the package. This
371 infrastructure must be used for all packages that do not use the
372 autotools as their build system. In the future, other specialized
373 infrastructures might be written for other build systems. We cover
374 them through in a xref:generic-package-tutorial[tutorial] and a
375 xref:generic-package-reference[reference].
377 * *Makefiles for autotools-based software* (autoconf, automake, etc.):
378 We provide a dedicated infrastructure for such packages, since
379 autotools is a very common build system. This infrastructure 'must'
380 be used for new packages that rely on the autotools as their build
381 system. We cover them through a xref:autotools-package-tutorial[tutorial]
382 and xref:autotools-package-reference[reference].
384 * *Makefiles for cmake-based software*: We provide a dedicated
385 infrastructure for such packages, as CMake is a more and more
386 commonly used build system and has a standardized behaviour. This
387 infrastructure 'must' be used for new packages that rely on
388 CMake. We cover them through a xref:cmake-package-tutorial[tutorial]
389 and xref:cmake-package-reference[reference].
391 * *Makefiles for Python modules*: We have a dedicated infrastructure
392 for Python modules that use either the +distutils+ or the
393 +setuptools+ mechanism. We cover them through a
394 xref:python-package-tutorial[tutorial] and a
395 xref:python-package-reference[reference].
397 * *Makefiles for Lua modules*: We have a dedicated infrastructure for
398 Lua modules available through the LuaRocks web site. We cover them
399 through a xref:luarocks-package-tutorial[tutorial] and a
400 xref:luarocks-package-reference[reference].
402 Further formatting details: see xref:writing-rules-mk[the writing
405 [[adding-packages-hash]]
408 Optionally, you can add a third file, named +libfoo.hash+, that contains
409 the hashes of the downloaded files for the +libfoo+ package.
411 The hashes stored in that file are used to validate the integrity of the
414 The format of this file is one line for each file for which to check the
415 hash, each line being space-separated, with these three fields:
417 * the type of hash, one of:
418 ** +md5+, +sha1+, +sha224+, +sha256+, +sha384+, +sha512+, +none+
419 * the hash of the file:
420 ** for +none+, one or more non-space chars, usually just the string +xxx+
421 ** for +md5+, 32 hexadecimal characters
422 ** for +sha1+, 40 hexadecimal characters
423 ** for +sha224+, 56 hexadecimal characters
424 ** for +sha256+, 64 hexadecimal characters
425 ** for +sha384+, 96 hexadecimal characters
426 ** for +sha512+, 128 hexadecimal characters
427 * the name of the file, without any directory component
429 Lines starting with a +#+ sign are considered comments, and ignored. Empty
432 There can be more than one hash for a single file, each on its own line. In
433 this case, all hashes must match.
436 Ideally, the hashes stored in this file should match the hashes published by
437 upstream, e.g. on their website, in the e-mail announcement... If upstream
438 provides more than one type of hash (e.g. +sha1+ and +sha512+), then it is
439 best to add all those hashes in the +.hash+ file. If upstream does not
440 provide any hash, or only provides an +md5+ hash, then compute at least one
441 strong hash yourself (preferably +sha256+, but not +md5+), and mention
442 this in a comment line above the hashes.
445 If +libfoo+ is from GitHub (see xref:github-download-url[] for details), we
446 can only accept a +.hash+ file if the package is a released (e.g. uploaded
447 by the maintainer) tarball. Otherwise, the automatically generated tarball
448 may change over time, and thus its hashes may be different each time it is
449 downloaded, causing a +.hash+ mismatch for that tarball.
452 The number of spaces does not matter, so one can use spaces (or tabs) to
453 properly align the different fields.
455 The +none+ hash type is reserved to those archives downloaded from a
456 repository, like a 'git clone', a 'subversion checkout'... or archives
457 downloaded with the xref:github-download-url[github helper].
459 The example below defines a +sha1+ and a +sha256+ published by upstream for
460 the main +libfoo-1.2.3.tar.bz2+ tarball, an +md5+ from upstream and a
461 locally-computed +sha256+ hashes for a binary blob, a +sha256+ for a
462 downloaded patch, and an archive with no hash:
465 # Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
466 sha1 486fb55c3efa71148fe07895fd713ea3a5ae343a libfoo-1.2.3.tar.bz2
467 sha256 efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369 libfoo-1.2.3.tar.bz2
469 # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
470 md5 2d608f3c318c6b7557d551a5a09314f03452f1a1 libfoo-data.bin
471 sha256 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b libfoo-data.bin
474 sha256 ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9 libfoo-fix-blabla.patch
476 # No hash for 1234, comes from the github-helper:
477 none xxx libfoo-1234.tar.gz
480 If the +.hash+ file is present, and it contains one or more hashes for a
481 downloaded file, the hash(es) computed by Buildroot (after download) must
482 match the hash(es) stored in the +.hash+ file. If one or more hashes do
483 not match, Buildroot considers this an error, deletes the downloaded file,
486 If the +.hash+ file is present, but it does not contain a hash for a
487 downloaded file, Buildroot considers this an error and aborts. However,
488 the downloaded file is left in the download directory since this
489 typically indicates that the +.hash+ file is wrong but the downloaded
492 Sources that are downloaded from a version control system (git, subversion,
493 etc...) can not have a hash, because the version control system and tar
494 may not create exactly the same file (dates, files ordering...), so the
495 hash could be wrong even for a valid download. Therefore, the hash check
496 is entirely skipped for such sources.
498 If the +.hash+ file is missing, then no check is done at all.