| Message ID | 679aaf4f4d6cb323f13d.1380099395@argentina |
|---|---|
| State | Superseded |
| Headers | show |
On 09/25/13 10:56, Thomas De Schampheleire wrote: > 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> > > --- > v2: > - explicitly add parts on target architecture and MMU support (no comment > needed) (comment ThomasP) > - remove 'without scrolling' text (comment Arnout) > > Notes: > - How we will specify the C library is currently marked as 'to be decided'. > This patch series does not yet unify that, but I plan to do that in a new > patch (or update this series if we can reach a decision shortly). The problem > is that not all packages that have a dependency on e.g. glibc add a comment to > show this to the user. A proposal would be to have a comment like: > foo needs a (e)glibc toolchain w/ featA, featB, featC > where the '(e)glibc' string would be left out if there is no constraint on the > C library. Looks good to me. Though for glibc there is only one feature AFAIK: C++. > > > docs/manual/adding-packages-directory.txt | 88 ++++++++++++++++++++++++++++-- > 1 files changed, 80 insertions(+), 8 deletions(-) > > 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,82 @@ 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, like the "like" indicates that you're giving a few examples, but you're actually giving an exhaustive list. So instead I't put a colon. > +C library, C++ support, largefile support, thread support, RPC the choice of C library, > +support, IPv6 support, wchar support, or dynamic libraries. Some dynamic library support. > +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 string > +literals to use in the comment. "string literals" sounds a bit strange here. "text" seems more appropriate to me. > + > +* Target architecture > +** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+) > +** Comment string: no comment to be added > + I could be wrong, but I think asciidoc doesn't allow an empty line here: you'll end up with two <ul>s with a single <li>. Can you verify that? > +* 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: (to be decided) > + > +* 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+ !BR2_PREFER_STATIC_LIB > +** Comment string: +dynamic library+ For the sake of brevity, maybe "DLL"? Regards, Arnout > + > + > The +.mk+ file > ~~~~~~~~~~~~~~ > [[adding-packages-mk]] >
Hi Arnout, On Thu, Oct 3, 2013 at 7:30 AM, Arnout Vandecappelle <arnout@mind.be> wrote: > On 09/25/13 10:56, Thomas De Schampheleire wrote: [..] >> Notes: >> - How we will specify the C library is currently marked as 'to be >> decided'. >> This patch series does not yet unify that, but I plan to do that in a new >> patch (or update this series if we can reach a decision shortly). The >> problem >> is that not all packages that have a dependency on e.g. glibc add a >> comment to >> show this to the user. A proposal would be to have a comment like: >> foo needs a (e)glibc toolchain w/ featA, featB, featC >> where the '(e)glibc' string would be left out if there is no constraint on >> the >> C library. > > > Looks good to me. Though for glibc there is only one feature AFAIK: C++. > > I'm not sure what you mean here. I think that some packages depend on an (e)glibc toolchain because it requires certain features that are lacking in uclibc. I haven't checked for the details though. It may be the presence of certain system calls. [..] >> +[[dependencies-target-toolchain-options]] >> +Dependencies on target and toolchain options >> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ >> +Many packages depend on certain options of the toolchain, like the > > > "like" indicates that you're giving a few examples, but you're actually > giving an exhaustive list. So instead I't put a colon. > Ok, will fix. > >> +C library, C++ support, largefile support, thread support, RPC > > > the choice of C library, Ok, will fix. > > >> +support, IPv6 support, wchar support, or dynamic libraries. Some > > > dynamic library support. This is partially related to the PREFER_STATIC_LIB discussion, but right now it's probably cleaner to add support, so will fix. [..] >> + >> +The rest of this section enumerates the different target and toolchain >> +options, the corresponding config symbols to depend on, and the string >> +literals to use in the comment. > > > "string literals" sounds a bit strange here. "text" seems more appropriate > to me. > Ok, will fix. > >> + >> +* Target architecture >> +** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see >> +arch/Config.in+) >> +** Comment string: no comment to be added >> + > > > I could be wrong, but I think asciidoc doesn't allow an empty line here: > you'll end up with two <ul>s with a single <li>. Can you verify that? I do see one overal <ul> with several list items 'target architecture', 'mmu support', etc. so it looks ok to me. [..] >> + >> +* dynamic library >> +** Dependency symbol: +BR2_PREFER_STATIC_LIB+ > > > !BR2_PREFER_STATIC_LIB Ok, that's clearer, will fix. > > >> +** Comment string: +dynamic library+ > > > For the sake of brevity, maybe "DLL"? DLL really has a Windows annotation for me. Moreover, it's not so commonly used in the Linux world, don't you think? Thanks for your review! Best regards, Thomas
On 10/03/13 09:34, Thomas De Schampheleire wrote: > Hi Arnout, > > On Thu, Oct 3, 2013 at 7:30 AM, Arnout Vandecappelle <arnout@mind.be> wrote: >> On 09/25/13 10:56, Thomas De Schampheleire wrote: > [..] >>> Notes: >>> - How we will specify the C library is currently marked as 'to be >>> decided'. >>> This patch series does not yet unify that, but I plan to do that in a new >>> patch (or update this series if we can reach a decision shortly). The >>> problem >>> is that not all packages that have a dependency on e.g. glibc add a >>> comment to >>> show this to the user. A proposal would be to have a comment like: >>> foo needs a (e)glibc toolchain w/ featA, featB, featC >>> where the '(e)glibc' string would be left out if there is no constraint on >>> the >>> C library. >> >> >> Looks good to me. Though for glibc there is only one feature AFAIK: C++. >> >> > > I'm not sure what you mean here. I think that some packages depend on > an (e)glibc toolchain because it requires certain features that are > lacking in uclibc. I haven't checked for the details though. It may be > the presence of certain system calls. (e)glibc always has all features enabled, except for C++ (and RPC in some cases but I don't think we have those). Which is fortunate, because it means the additional (e)glibc part isn't likely to make the line too long. [snip] >>> +** Comment string: +dynamic library+ >> >> >> For the sake of brevity, maybe "DLL"? > > DLL really has a Windows annotation for me. Moreover, it's not so > commonly used in the Linux world, don't you think? True. I'm just thinking that this is a pretty long string, that in addition is likely to be combined with a lot of other things. The dynamic library support is anyway a bit of a problem, because it bears little relation to the config option "prefer static libraries". That part, however, will hopefully be fixed when the other Thomas adds the choice between static-only, dynamic-only and both. Regards, Arnout
On 10/03/2013 08:11 AM, Arnout Vandecappelle wrote: >>> For the sake of brevity, maybe "DLL"? >> >> DLL really has a Windows annotation for me. Moreover, it's not so >> commonly used in the Linux world, don't you think? > > True. I'm just thinking that this is a pretty long string, that in > addition is likely to be combined with a lot of other things. DLSO maybe? Regards.
Dear Arnout Vandecappelle, On Thu, 03 Oct 2013 13:11:12 +0200, Arnout Vandecappelle wrote: > The dynamic library support is anyway a bit of a problem, because > it bears little relation to the config option "prefer static > libraries". That part, however, will hopefully be fixed when the > other Thomas adds the choice between static-only, dynamic-only and > both. I have patches that do this, they need a bit more testing, but I should probably send them as a RFC. Thomas
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,82 @@ 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, like the +C library, C++ support, largefile support, thread support, RPC +support, IPv6 support, wchar support, or dynamic libraries. 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 string +literals 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: (to be decided) + +* 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> --- v2: - explicitly add parts on target architecture and MMU support (no comment needed) (comment ThomasP) - remove 'without scrolling' text (comment Arnout) Notes: - How we will specify the C library is currently marked as 'to be decided'. This patch series does not yet unify that, but I plan to do that in a new patch (or update this series if we can reach a decision shortly). The problem is that not all packages that have a dependency on e.g. glibc add a comment to show this to the user. A proposal would be to have a comment like: foo needs a (e)glibc toolchain w/ featA, featB, featC where the '(e)glibc' string would be left out if there is no constraint on the C library. docs/manual/adding-packages-directory.txt | 88 ++++++++++++++++++++++++++++-- 1 files changed, 80 insertions(+), 8 deletions(-)