manual: add section about depending on target and toolchain options

* 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.

          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

--------------------------

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