docs/manual/adding-packages-directory.txt

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