| // -*- mode:doc; -*- |
| // vim: set syntax=asciidoc: |
| |
| Package directory |
| ~~~~~~~~~~~~~~~~~ |
| |
| First of all, create a directory under the +package+ directory for |
| your software, for example +libfoo+. |
| |
| Some packages have been grouped by topic in a sub-directory: |
| +x11r7+, +efl+ and +matchbox+. If your package fits in |
| one of these categories, then create your package directory in these. |
| New subdirectories are discouraged, however. |
| |
| |
| +Config.in+ file |
| ~~~~~~~~~~~~~~~~ |
| |
| Then, create a file named +Config.in+. This file will contain the |
| option descriptions related to our +libfoo+ software that will be used |
| and displayed in the configuration tool. It should basically contain: |
| |
| --------------------------- |
| config BR2_PACKAGE_LIBFOO |
| bool "libfoo" |
| help |
| This is a comment that explains what libfoo is. |
| |
| http://foosoftware.org/libfoo/ |
| --------------------------- |
| |
| The +bool+ line, +help+ line and other meta-informations about the |
| configuration option must be indented with one tab. The help text |
| itself should be indented with one tab and two spaces, and it must |
| mention the upstream URL of the project. |
| |
| You can add other sub-options into a +if |
| BR2_PACKAGE_LIBFOO...endif+ statement to configure particular things |
| in your software. You can look at examples in other packages. The |
| syntax of the +Config.in+ file is the same as the one for the kernel |
| Kconfig file. The documentation for this syntax is available at |
| http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[] |
| |
| Finally you have to add your new +libfoo/Config.in+ to |
| +package/Config.in+ (or in a category subdirectory if you decided to |
| put your package in one of the existing categories). The files |
| included there are 'sorted alphabetically' per category and are 'NOT' |
| supposed to contain anything but the 'bare' name of the package. |
| |
| -------------------------- |
| source "package/libfoo/Config.in" |
| -------------------------- |
| |
| [[depends-on-vs-select]] |
| Choosing +depends on+ or +select+ |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The +Config.in+ file of your package must also ensure that |
| dependencies are enabled. Typically, Buildroot uses the following |
| rules: |
| |
| * Use a +select+ type of dependency for dependencies on |
| libraries. These dependencies are generally not obvious and it |
| therefore make sense to have the kconfig system ensure that the |
| dependencies are selected. For example, the _libgtk2_ package uses |
| +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also |
| enabled. |
| The +select+ keyword expresses the dependency with a backward |
| semantic. |
| |
| * Use a +depends on+ type of dependency when the user really needs to |
| be aware of the dependency. Typically, Buildroot uses this type of |
| dependency for dependencies on target architecture, MMU support and |
| toolchain options (see xref:dependencies-target-toolchain-options[]), |
| or for dependencies on "big" things, such as the X.org system. |
| The +depends on+ keyword expresses the dependency with a forward |
| semantic. |
| |
| .Note |
| The current problem with the _kconfig_ language is that these two |
| dependency semantics are not internally linked. Therefore, it may be |
| possible to select a package, whom one of its dependencies/requirement |
| is not met. |
| |
| An example illustrates both the usage of +select+ and +depends on+. |
| |
| -------------------------- |
| config BR2_PACKAGE_ACL |
| bool "acl" |
| select BR2_PACKAGE_ATTR |
| depends on BR2_LARGEFILE |
| help |
| POSIX Access Control Lists, which are used to define more |
| fine-grained discretionary access rights for files and |
| directories. |
| This package also provides libacl. |
| |
| http://savannah.nongnu.org/projects/acl |
| |
| comment "acl needs a toolchain w/ largefile" |
| depends on !BR2_LARGEFILE |
| -------------------------- |
| |
| |
| Note that these two dependency types are only transitive with the |
| dependencies of the same kind. |
| |
| This means, in the following example: |
| |
| -------------------------- |
| config BR2_PACKAGE_A |
| bool "Package A" |
| |
| config BR2_PACKAGE_B |
| bool "Package B" |
| depends on BR2_PACKAGE_A |
| |
| config BR2_PACKAGE_C |
| bool "Package C" |
| depends on BR2_PACKAGE_B |
| |
| config BR2_PACKAGE_D |
| bool "Package D" |
| select BR2_PACKAGE_B |
| |
| config BR2_PACKAGE_E |
| bool "Package E" |
| select BR2_PACKAGE_D |
| -------------------------- |
| |
| * Selecting +Package C+ will be visible if +Package B+ has been |
| selected, which in turn is only visible if +Package A+ has been |
| selected. |
| |
| * Selecting +Package E+ will select +Package D+, which will select |
| +Package B+, it will not check for the dependencies of +Package B+, |
| so it will not select +Package A+. |
| |
| * Since +Package B+ is selected but +Package A+ is not, this violates |
| the dependency of +Package B+ on +Package A+. Therefore, in such a |
| situation, the transitive dependency has to be added explicitly: |
| |
| -------------------------- |
| config BR2_PACKAGE_D |
| bool "Package D" |
| select BR2_PACKAGE_B |
| depends on BR2_PACKAGE_A |
| |
| config BR2_PACKAGE_E |
| bool "Package E" |
| select BR2_PACKAGE_D |
| depends on BR2_PACKAGE_A |
| -------------------------- |
| |
| Overall, for package library dependencies, +select+ should be |
| preferred. |
| |
| Note that such dependencies will ensure that the dependency option |
| is also enabled, but not necessarily built before your package. To do |
| so, the dependency also needs to be expressed in the +.mk+ file of the |
| package. |
| |
| Further formatting details: see xref:writing-rules-config-in[the |
| coding style]. |
| |
| [[dependencies-target-toolchain-options]] |
| Dependencies on target and toolchain options |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| Many packages depend on certain options of the toolchain: the choice of |
| C library, C++ support, largefile support, thread support, RPC support, |
| IPv6 support, wchar support, or dynamic library support. Some packages |
| can only be built on certain target architectures, or if an MMU is |
| available in the processor. |
| |
| These dependencies have to be expressed with the appropriate 'depends |
| on' statements in the Config.in file. Additionally, for dependencies on |
| toolchain options, a +comment+ should be displayed when the option is |
| not enabled, so that the user knows why the package is not available. |
| Dependencies on target architecture or MMU support should not be |
| made visible in a comment: since it is unlikely that the user can |
| freely choose another target, it makes little sense to show these |
| dependencies explicitly. |
| |
| The +comment+ should only be visible if the +config+ option itself would |
| be visible when the toolchain option dependencies are met. This means |
| that all other dependencies of the package (including dependencies on |
| target architecture and MMU support) have to be repeated on the |
| +comment+ definition. To keep it clear, the +depends on+ statement for |
| these non-toolchain option should be kept separate from the +depends on+ |
| statement for the toolchain options. |
| If there is a dependency on a config option in that same file (typically |
| the main package) it is preferable to have a global +if ... endif+ |
| construct rather than repeating the +depends on+ statement on the |
| comment and other config options. |
| |
| The general format of a dependency +comment+ for package foo is: |
| -------------------------- |
| foo needs a toolchain w/ featA, featB, featC |
| -------------------------- |
| |
| for example: |
| -------------------------- |
| aircrack-ng needs a toolchain w/ largefile, threads |
| -------------------------- |
| |
| Note that this text is kept brief on purpose, so that it will fit on a |
| 80-character terminal. |
| |
| The rest of this section enumerates the different target and toolchain |
| options, the corresponding config symbols to depend on, and the text to |
| use in the comment. |
| |
| * Target architecture |
| ** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+) |
| ** Comment string: no comment to be added |
| |
| * MMU support |
| ** Dependency symbol: +BR2_USE_MMU+ |
| ** Comment string: no comment to be added |
| |
| * C library |
| ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+, |
| +BR2_TOOLCHAIN_USES_UCLIBC+ |
| ** Comment string: for the C library, a slightly different comment text |
| is used: +foo needs an (e)glibc toolchain+, or `foo needs an (e)glibc |
| toolchain w/ C++ support` |
| |
| * C++ support |
| ** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+ |
| ** Comment string: `C++` |
| |
| * largefile support |
| ** Dependency symbol: +BR2_LARGEFILE+ |
| ** Comment string: +largefile+ |
| |
| * thread support |
| ** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+ |
| ** Comment string: +threads+ |
| |
| * RPC support |
| ** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+ |
| ** Comment string: +RPC+ |
| |
| * IPv6 support |
| ** Dependency symbol: +BR2_INET_IPV6+ |
| ** Comment string: +IPv6+ (lowercase v) |
| |
| * wchar support |
| ** Dependency symbol: +BR2_USE_WCHAR+ |
| ** Comment string: +wchar+ |
| |
| * dynamic library |
| ** Dependency symbol: +!BR2_PREFER_STATIC_LIB+ |
| ** Comment string: +dynamic library+ |
| |
| Dependencies on a Linux kernel built by buildroot |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| Some packages need a Linux kernel to be built by buildroot. These are |
| typically kernel modules or firmware. A comment should be added in the |
| Config.in file to express this dependency, similar to dependencies on |
| toolchain options. The general format is: |
| |
| -------------------------- |
| foo needs a Linux kernel to be built |
| -------------------------- |
| |
| If there is a dependency on both toolchain options and the Linux |
| kernel, use this format: |
| -------------------------- |
| foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built |
| -------------------------- |
| |
| Dependencies on udev /dev management |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| If a package needs udev /dev management, it should depend on symbol |
| +BR2_ROOTFS_DEVICE_CREATION_DYNAMIC_UDEV+, and the following comment |
| should be added: |
| |
| -------------------------- |
| foo needs udev /dev management |
| -------------------------- |
| |
| If there is a dependency on both toolchain options and udev /dev |
| management, use this format: |
| |
| -------------------------- |
| foo needs udev /dev management and a toolchain w/ featA, featB, featC |
| -------------------------- |
| |
| The +.mk+ file |
| ~~~~~~~~~~~~~~ |
| [[adding-packages-mk]] |
| |
| Finally, here's the hardest part. Create a file named +libfoo.mk+. It |
| describes how the package should be downloaded, configured, built, |
| installed, etc. |
| |
| Depending on the package type, the +.mk+ file must be written in a |
| different way, using different infrastructures: |
| |
| * *Makefiles for generic packages* (not using autotools or CMake): |
| These are based on an infrastructure similar to the one used for |
| autotools-based packages, but require a little more work from the |
| developer. They specify what should be done for the configuration, |
| compilation and installation of the package. This |
| infrastructure must be used for all packages that do not use the |
| autotools as their build system. In the future, other specialized |
| infrastructures might be written for other build systems. We cover |
| them through in a xref:generic-package-tutorial[tutorial] and a |
| xref:generic-package-reference[reference]. |
| |
| * *Makefiles for autotools-based software* (autoconf, automake, etc.): |
| We provide a dedicated infrastructure for such packages, since |
| autotools is a very common build system. This infrastructure 'must' |
| be used for new packages that rely on the autotools as their build |
| system. We cover them through a xref:autotools-package-tutorial[tutorial] |
| and xref:autotools-package-reference[reference]. |
| |
| * *Makefiles for cmake-based software*: We provide a dedicated |
| infrastructure for such packages, as CMake is a more and more |
| commonly used build system and has a standardized behaviour. This |
| infrastructure 'must' be used for new packages that rely on |
| CMake. We cover them through a xref:cmake-package-tutorial[tutorial] |
| and xref:cmake-package-reference[reference]. |
| |
| Further formatting details: see xref:writing-rules-mk[the writing |
| rules]. |