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 <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>

1 files 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]]