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