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