From c3a832a7fb26fed8fd7834e96f09e3565b637f69 Mon Sep 17 00:00:00 2001 From: Thomas De Schampheleire Date: Sun, 13 Oct 2013 16:55:31 +0200 Subject: [PATCH] manual: add section about depending on target and toolchain options Currently, the comments in Config.in files when depending on toolchain options are not at all lined up. This patch adds a section to the documentation that explains which format is to be used. Signed-off-by: Thomas De Schampheleire Signed-off-by: Peter Korsgaard --- docs/manual/adding-packages-directory.txt | 90 +++++++++++++++++++++-- 1 file changed, 82 insertions(+), 8 deletions(-) diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt index ca72970365..3ebe50e285 100644 --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -70,13 +70,9 @@ rules: * 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 toolchain options (target - architecture, MMU support, C library, C++ support, large file - support, thread support, RPC support, IPV6 support, WCHAR support), - or for dependencies on "big" things, such as the X.org system. For - dependencies on toolchain options, there should be a +comment+ that - is displayed when the option is not - enabled, so that the user knows why the package is not available. + 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. @@ -101,7 +97,7 @@ config BR2_PACKAGE_ACL http://savannah.nongnu.org/projects/acl -comment "acl requires a toolchain with LARGEFILE support" +comment "acl needs a toolchain w/ largefile" depends on !BR2_LARGEFILE -------------------------- @@ -167,6 +163,84 @@ 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 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 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+ + + The +.mk+ file ~~~~~~~~~~~~~~ [[adding-packages-mk]]