@@ -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]]
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> --- v3: - incorporate Arnout's comments - add (e)glibc text to documentation (previously mentioned as 'to be decided') v2: - explicitly add parts on target architecture and MMU support (no comment needed) (comment ThomasP) - remove 'without scrolling' text (comment Arnout) docs/manual/adding-packages-directory.txt | 90 ++++++++++++++++++++++++-- 1 files changed, 82 insertions(+), 8 deletions(-)