Patchwork [1,of,2,v3] manual: add section about depending on target and toolchain options

login
register
mail settings
Submitter Thomas De Schampheleire
Date Oct. 13, 2013, 2:55 p.m.
Message ID <21b9bd1f7132d7e17e8a.1381676131@argentina>
Download mbox | patch
Permalink /patch/283094/
State Accepted
Commit c3a832a7fb26fed8fd7834e96f09e3565b637f69
Headers show

Comments

Thomas De Schampheleire - Oct. 13, 2013, 2:55 p.m.
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(-)
Peter Korsgaard - Oct. 14, 2013, 8:48 p.m.
>>>>> "Thomas" == Thomas De Schampheleire <patrickdepinguin@gmail.com> writes:

 Thomas> Currently, the comments in Config.in files when depending on
 Thomas> toolchain options are not at all lined up. This patch adds a
 Thomas> section to the documentation that explains which format is to
 Thomas> be used.

Committed series, thanks!

Just a small reminder about keeping your commit message lines <= ~70
chars.
Thomas De Schampheleire - Oct. 15, 2013, 1:10 p.m.
Hi Peter,

On Mon, Oct 14, 2013 at 10:48 PM, Peter Korsgaard <jacmet@uclibc.org> wrote:
>>>>>> "Thomas" == Thomas De Schampheleire <patrickdepinguin@gmail.com> writes:
>
>  Thomas> Currently, the comments in Config.in files when depending on
>  Thomas> toolchain options are not at all lined up. This patch adds a
>  Thomas> section to the documentation that explains which format is to
>  Thomas> be used.
>
> Committed series, thanks!

Thanks a lot!

>
> Just a small reminder about keeping your commit message lines <= ~70
> chars.

Aargh, I did effectively set up my mercurial for this after your first
comment, but as this series already existed before that it didn't have
any effect and I failed to check it manually.

Shouldn't happen again in the future. I'm not sure about some of the
patches already in the queue though, like the Mercurial series.
Probably same problem there. Do you prefer me to resubmit, or is it
unnecessary noise in this case?

Thanks,
Thomas

Patch

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
--- 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]]