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