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