[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Yann E. MORIN]

Hello All!

This series is an alternative proposal to support displaying custom,
local help, most probably from a br2-external tree (or from a lcal.mk,
but that'd be pretty insane).

The basic idea is to offer the user help entries for local
customisations, but without mixing them with our own help entries.

I believe we want to keep them separate, as inter-mixing the two could
lead users to believe those addtional help entries are "native" in
buildroot, when they are not.

The same way we expose all of br2-external config options under a
sub-menu labelled "User-provided options", we do similarly for the
custom help, albeit with a slight shorter moniker, 'help-local'.

After the first patch implements this (which is really all that is
needed to print custom help), we go further with providing a macro that
pretty-prints the help for rules, so that the layout is all handled in a
single location. This macro can also be used by the local help, too.

This macro is then used to implement per-package specific help (which is
currently only about kconfig-related changes, but can not easily be done
in the kconfig-package infra) into the packages themseves, to clean up
the main help code (the entris are still displayed there, they are just
definedin each concerned package).

All that, plus a bit of associated documentation, of course. ;-)

Thanks to J?r?me for his initial proposal, and Arnout for
before-inception suggestions:
    http://lists.busybox.net/pipermail/buildroot/2016-March/155415.html

Regards,
Yann E. MORIN.


The following changes since commit 07f46c2b6daec44a6176039c90be67e66c4c2e42:

  package/busybox: support automatic module loading with mdev (2016-03-09 23:07:44 +0100)

are available in the git repository at:

  git://git.busybox.net/~ymorin/git/buildroot yem/help

for you to fetch changes up to b94d50a5f7717ad1ea2d9cab129155a0ab203f71:

  docs/manual: document the br2-external help-local (2016-03-09 23:10:37 +0100)

----------------------------------------------------------------
Yann E. MORIN (8):
      core: add the possibility to provide help for local, custom rules
      core/pkg-utils: add a macro to pretty-print a help entry
      core/pkg-generic: add help about package-specific rules
      package/busybox: use the generic help rules
      linux: add the generic help rules
      package/uclibc: use the generic help rules
      boot/barebox: use the generic help rules
      docs/manual: document the br2-external help-local

 Makefile                                | 23 +++++++----------------
 boot/barebox/barebox.mk                 |  4 ++++
 docs/manual/adding-packages-generic.txt |  6 ++++++
 docs/manual/customize-outside-br.txt    | 20 ++++++++++++++++++++
 linux/linux.mk                          |  6 ++++++
 package/busybox/busybox.mk              |  2 ++
 package/pkg-generic.mk                  |  2 ++
 package/pkg-utils.mk                    | 13 +++++++++++++
 package/uclibc/uclibc.mk                |  2 ++
 9 files changed, 62 insertions(+), 16 deletions(-)

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 1/8] core: add the possibility to provide help for local, custom rules

[Yann E. MORIN]

When using a br2-external tree, it is possible (as stated in our manual)
to implement whatever arbitrary extra make rules (such as flashing a
board, or extracting the rootfs in an NFS export...). Some of those
extra rules might be exposed to the user as new entry points that the
user can call by itself.

However, there is no way for the br2-external to advertise those new
rules in the help text.

We add the possibility to do so, by adding a new make rule, called
help-local, advertised in our own help info.

It is up to the br2-external tree to provide whatever help text is
deemed necessary.

Note that we need to provide an empty, dummy help-local' rule, since it
is always advertised. Since this rule is empty, make gently reports that
there is "Nothing to be done for `help-local'", which is pretty well
fitting when help-local was not provided (either because there's no
br2-external tree, or when the br2-external tree does not provide it.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Makefile b/Makefile
index f2822a2..d24793b 100644
--- a/Makefile
+++ b/Makefile
@@ -966,6 +966,7 @@ endif
 	@echo '  source-check           - check selected packages for valid download URLs'
 	@echo '  external-deps          - list external packages used'
 	@echo '  legal-info             - generate info about license compliance'
+	@echo '  help-local             - print help about local, custom actions (if any)'
 	@echo
 	@echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
 	@echo '  make O=dir             - Locate all output files in "dir", including .config'
@@ -974,6 +975,11 @@ endif
 	@echo 'it on-line at http://buildroot.org/docs.html'
 	@echo
 
+# This rule does nothing, it is expected to be overloaded by
+# a br2-external tree or a local.mk . However, it must exist,
+# as we reference it in the main help, above.
+help-local:
+
 list-defconfigs:
 	@echo 'Built-in configs:'
 	@$(foreach b, $(sort $(notdir $(wildcard $(TOPDIR)/configs/*_defconfig))), \
-- 
1.9.1

[Buildroot] [PATCH 1/8] core: add the possibility to provide help for local, custom rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> When using a br2-external tree, it is possible (as stated in our manual)
> to implement whatever arbitrary extra make rules (such as flashing a
> board, or extracting the rootfs in an NFS export...). Some of those
> extra rules might be exposed to the user as new entry points that the
> user can call by itself.
>
> However, there is no way for the br2-external to advertise those new
> rules in the help text.
>
> We add the possibility to do so, by adding a new make rule, called
> help-local, advertised in our own help info.
>
> It is up to the br2-external tree to provide whatever help text is
> deemed necessary.
>
> Note that we need to provide an empty, dummy help-local' rule, since it
> is always advertised. Since this rule is empty, make gently reports that
> there is "Nothing to be done for `help-local'", which is pretty well
> fitting when help-local was not provided (either because there's no
> br2-external tree, or when the br2-external tree does not provide it.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>   Makefile | 6 ++++++
>   1 file changed, 6 insertions(+)
>
> diff --git a/Makefile b/Makefile
> index f2822a2..d24793b 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -966,6 +966,7 @@ endif
>   	@echo '  source-check           - check selected packages for valid download URLs'
>   	@echo '  external-deps          - list external packages used'
>   	@echo '  legal-info             - generate info about license compliance'
> +	@echo '  help-local             - print help about local, custom actions (if any)'
>   	@echo
>   	@echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
>   	@echo '  make O=dir             - Locate all output files in "dir", including .config'
> @@ -974,6 +975,11 @@ endif
>   	@echo 'it on-line at http://buildroot.org/docs.html'
>   	@echo
>
> +# This rule does nothing, it is expected to be overloaded by
> +# a br2-external tree or a local.mk . However, it must exist,
> +# as we reference it in the main help, above.
> +help-local:

  It's sufficient and better to do

.PHONY: help-local

(and then there is no need for a comment either).

  Regards,
  Arnout

> +
>   list-defconfigs:
>   	@echo 'Built-in configs:'
>   	@$(foreach b, $(sort $(notdir $(wildcard $(TOPDIR)/configs/*_defconfig))), \
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 1/8] core: add the possibility to provide help for local, custom rules

[Yann E. MORIN]

Arnout, All,

On 2016-03-10 00:35 +0100, Arnout Vandecappelle spake thusly:
> On 03/09/16 23:22, Yann E. MORIN wrote:
> >When using a br2-external tree, it is possible (as stated in our manual)
> >to implement whatever arbitrary extra make rules (such as flashing a
> >board, or extracting the rootfs in an NFS export...). Some of those
> >extra rules might be exposed to the user as new entry points that the
> >user can call by itself.
> >
> >However, there is no way for the br2-external to advertise those new
> >rules in the help text.
> >
> >We add the possibility to do so, by adding a new make rule, called
> >help-local, advertised in our own help info.
> >
> >It is up to the br2-external tree to provide whatever help text is
> >deemed necessary.
> >
> >Note that we need to provide an empty, dummy help-local' rule, since it
> >is always advertised. Since this rule is empty, make gently reports that
> >there is "Nothing to be done for `help-local'", which is pretty well
> >fitting when help-local was not provided (either because there's no
> >br2-external tree, or when the br2-external tree does not provide it.
> >
> >Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> >Cc: J?r?me Pouiller <jezz@sysmic.org>
> >Cc: Arnout Vandecappelle <arnout@mind.be>
> >Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> >---
> >  Makefile | 6 ++++++
> >  1 file changed, 6 insertions(+)
> >
> >diff --git a/Makefile b/Makefile
> >index f2822a2..d24793b 100644
> >--- a/Makefile
> >+++ b/Makefile
> >@@ -966,6 +966,7 @@ endif
> >  	@echo '  source-check           - check selected packages for valid download URLs'
> >  	@echo '  external-deps          - list external packages used'
> >  	@echo '  legal-info             - generate info about license compliance'
> >+	@echo '  help-local             - print help about local, custom actions (if any)'
> >  	@echo
> >  	@echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
> >  	@echo '  make O=dir             - Locate all output files in "dir", including .config'
> >@@ -974,6 +975,11 @@ endif
> >  	@echo 'it on-line at http://buildroot.org/docs.html'
> >  	@echo
> >
> >+# This rule does nothing, it is expected to be overloaded by
> >+# a br2-external tree or a local.mk . However, it must exist,
> >+# as we reference it in the main help, above.
> >+help-local:
> 
>  It's sufficient and better to do
> 
> .PHONY: help-local

I tried (evenm before I submitted!) and it does not work. It still
prints that there is nothing to do...

Here's my test case:

    $ cat Makefile
    .PHONY: help
    help:

    $ make help
    make: Nothing to be done for `help'.

Regards,
Yann E. MORIN.

> (and then there is no need for a comment either).
> 
>  Regards,
>  Arnout
> 
> >+
> >  list-defconfigs:
> >  	@echo 'Built-in configs:'
> >  	@$(foreach b, $(sort $(notdir $(wildcard $(TOPDIR)/configs/*_defconfig))), \
> >
> 
> 
> -- 
> Arnout Vandecappelle                          arnout at mind be
> Senior Embedded Software Architect            +32-16-286500
> Essensium/Mind                                http://www.mind.be
> G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
> LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
> GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 1/8] core: add the possibility to provide help for local, custom rules

[Arnout Vandecappelle]

On 03/10/16 21:22, Yann E. MORIN wrote:
> Arnout, All,
>
> On 2016-03-10 00:35 +0100, Arnout Vandecappelle spake thusly:
>> On 03/09/16 23:22, Yann E. MORIN wrote:
>>> When using a br2-external tree, it is possible (as stated in our manual)
>>> to implement whatever arbitrary extra make rules (such as flashing a
>>> board, or extracting the rootfs in an NFS export...). Some of those
>>> extra rules might be exposed to the user as new entry points that the
>>> user can call by itself.
>>>
>>> However, there is no way for the br2-external to advertise those new
>>> rules in the help text.
>>>
>>> We add the possibility to do so, by adding a new make rule, called
>>> help-local, advertised in our own help info.
>>>
>>> It is up to the br2-external tree to provide whatever help text is
>>> deemed necessary.
>>>
>>> Note that we need to provide an empty, dummy help-local' rule, since it
>>> is always advertised. Since this rule is empty, make gently reports that
>>> there is "Nothing to be done for `help-local'", which is pretty well
>>> fitting when help-local was not provided (either because there's no
>>> br2-external tree, or when the br2-external tree does not provide it.
>>>
>>> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
>>> Cc: J?r?me Pouiller <jezz@sysmic.org>
>>> Cc: Arnout Vandecappelle <arnout@mind.be>
>>> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
>>> ---
>>>   Makefile | 6 ++++++
>>>   1 file changed, 6 insertions(+)
>>>
>>> diff --git a/Makefile b/Makefile
>>> index f2822a2..d24793b 100644
>>> --- a/Makefile
>>> +++ b/Makefile
>>> @@ -966,6 +966,7 @@ endif
>>>   	@echo '  source-check           - check selected packages for valid download URLs'
>>>   	@echo '  external-deps          - list external packages used'
>>>   	@echo '  legal-info             - generate info about license compliance'
>>> +	@echo '  help-local             - print help about local, custom actions (if any)'
>>>   	@echo
>>>   	@echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
>>>   	@echo '  make O=dir             - Locate all output files in "dir", including .config'
>>> @@ -974,6 +975,11 @@ endif
>>>   	@echo 'it on-line at http://buildroot.org/docs.html'
>>>   	@echo
>>>
>>> +# This rule does nothing, it is expected to be overloaded by
>>> +# a br2-external tree or a local.mk . However, it must exist,
>>> +# as we reference it in the main help, above.
>>> +help-local:
>>
>>   It's sufficient and better to do
>>
>> .PHONY: help-local
>
> I tried (evenm before I submitted!) and it does not work. It still
> prints that there is nothing to do...
>
> Here's my test case:
>
>      $ cat Makefile
>      .PHONY: help
>      help:
>
>      $ make help
>      make: Nothing to be done for `help'.

  But that's also the case with the empty rule, no?

  My point was: if you just declare it phony, it will have the same effect. In 
addition, you've declared it phony already which is really what we want in the 
end. And finally, when declaring it phony, there's no need to add a comment 
because it's obvious that it's a phony target.

  Regards,
  Arnout


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 2/8] core/pkg-utils: add a macro to pretty-print a help entry

[Yann E. MORIN]

To ensure that all the help entries we display are all formatted the
same, we currently indent the help texts manually.

Also, when a br2-external tree wants to display local custom help, they
have to rely on a hard-coded layout (if they want to match our iwn
output, which is not mandatory).

Add a macro to pretty-print make rules in the help texts.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 package/pkg-utils.mk | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/package/pkg-utils.mk b/package/pkg-utils.mk
index f88313a..873dbec 100644
--- a/package/pkg-utils.mk
+++ b/package/pkg-utils.mk
@@ -104,6 +104,19 @@ define sep
 
 endef
 
+# Pretty-print a make rule in the help text
+#
+# $(1): a list of double- or single-quoted string representing the rule
+#       and their help text, formatted as:  "action : help for action"
+#       'action' should be less than 22 characters, otherwise the help
+#       text will not be correctly indented.
+#
+define HELP_RULE
+	for h in $(1); do \
+		printf "  %-22s - %s\n" "$${h%% : *}" "$${h#* : }"; \
+	done
+endef
+
 # check-deprecated-variable -- throw an error on deprecated variables
 # example:
 #   $(eval $(call check-deprecated-variable,FOO_MAKE_OPT,FOO_MAKE_OPTS))
-- 
1.9.1

[Buildroot] [PATCH 2/8] core/pkg-utils: add a macro to pretty-print a help entry

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> To ensure that all the help entries we display are all formatted the
> same, we currently indent the help texts manually.
>
> Also, when a br2-external tree wants to display local custom help, they
> have to rely on a hard-coded layout (if they want to match our iwn
> output, which is not mandatory).
>
> Add a macro to pretty-print make rules in the help texts.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>   package/pkg-utils.mk | 13 +++++++++++++
>   1 file changed, 13 insertions(+)
>
> diff --git a/package/pkg-utils.mk b/package/pkg-utils.mk
> index f88313a..873dbec 100644
> --- a/package/pkg-utils.mk
> +++ b/package/pkg-utils.mk
> @@ -104,6 +104,19 @@ define sep
>
>   endef
>
> +# Pretty-print a make rule in the help text
> +#
> +# $(1): a list of double- or single-quoted string representing the rule
> +#       and their help text, formatted as:  "action : help for action"
> +#       'action' should be less than 22 characters, otherwise the help
> +#       text will not be correctly indented.
> +#
> +define HELP_RULE

  Most of our functions are lowercase. Perhaps print-help?

  If we don't have the help-local indirection but directly do it in the 
top-level help, then there's no need for an additional function.

  Regards,
  Arnout

> +	for h in $(1); do \
> +		printf "  %-22s - %s\n" "$${h%% : *}" "$${h#* : }"; \
> +	done
> +endef
> +
>   # check-deprecated-variable -- throw an error on deprecated variables
>   # example:
>   #   $(eval $(call check-deprecated-variable,FOO_MAKE_OPT,FOO_MAKE_OPTS))
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 2/8] core/pkg-utils: add a macro to pretty-print a help entry

[Jérôme Pouiller]

Hello Arnout, Yann,

On Thursday 10 March 2016 00:37:17 Arnout Vandecappelle wrote:
> On 03/09/16 23:22, Yann E. MORIN wrote:
[...]

> > +	for h in $(1); do \
> > +		printf "  %-22s - %s\n" "$${h%% : *}" "$${h#* : }"; \
> > +	done
Personally, I dislike this automatic splitting of argument. Especially,
this macro is not obvious and it may look like black magic.

Regards,

-- 
J?r?me Pouiller, Sysmic
Embedded Linux specialist
http://www.sysmic.fr

[Buildroot] [PATCH 2/8] core/pkg-utils: add a macro to pretty-print a help entry

[Yann E. MORIN]

J?r?me, All,

On 2016-03-10 10:31 +0100, J?r?me Pouiller spake thusly:
> Hello Arnout, Yann,
> 
> On Thursday 10 March 2016 00:37:17 Arnout Vandecappelle wrote:
> > On 03/09/16 23:22, Yann E. MORIN wrote:
> [...]
> 
> > > +	for h in $(1); do \
> > > +		printf "  %-22s - %s\n" "$${h%% : *}" "$${h#* : }"; \
> > > +	done
> Personally, I dislike this automatic splitting of argument. Especially,
> this macro is not obvious and it may look like black magic.

Hmmm... Standard shell expansions that have been documented in POSIX
for, like, forever... And really, if you find this to be black magic,
I'm not sure what to say...

http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 2/8] core/pkg-utils: add a macro to pretty-print a help entry

[Yann E. MORIN]

Arnout, All,

On 2016-03-10 00:37 +0100, Arnout Vandecappelle spake thusly:
> On 03/09/16 23:22, Yann E. MORIN wrote:
> >To ensure that all the help entries we display are all formatted the
> >same, we currently indent the help texts manually.
> >
> >Also, when a br2-external tree wants to display local custom help, they
> >have to rely on a hard-coded layout (if they want to match our iwn
> >output, which is not mandatory).
> >
> >Add a macro to pretty-print make rules in the help texts.
> >
> >Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> >Cc: J?r?me Pouiller <jezz@sysmic.org>
> >Cc: Arnout Vandecappelle <arnout@mind.be>
> >Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> >---
> >  package/pkg-utils.mk | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> >
> >diff --git a/package/pkg-utils.mk b/package/pkg-utils.mk
> >index f88313a..873dbec 100644
> >--- a/package/pkg-utils.mk
> >+++ b/package/pkg-utils.mk
> >@@ -104,6 +104,19 @@ define sep
> >
> >  endef
> >
> >+# Pretty-print a make rule in the help text
> >+#
> >+# $(1): a list of double- or single-quoted string representing the rule
> >+#       and their help text, formatted as:  "action : help for action"
> >+#       'action' should be less than 22 characters, otherwise the help
> >+#       text will not be correctly indented.
> >+#
> >+define HELP_RULE
> 
>  Most of our functions are lowercase. Perhaps print-help?

Done, thanks! :-)

>  If we don't have the help-local indirection but directly do it in the
> top-level help, then there's no need for an additional function.

Well... You know what I think about mixing both help.. ;-] So this is a
function so that it can be used by help-custom  (hint, that's the new
name I have for it here! ;-) ).

Regards,
Yann E. MORIN.

>  Regards,
>  Arnout
> 
> >+	for h in $(1); do \
> >+		printf "  %-22s - %s\n" "$${h%% : *}" "$${h#* : }"; \
> >+	done
> >+endef
> >+
> >  # check-deprecated-variable -- throw an error on deprecated variables
> >  # example:
> >  #   $(eval $(call check-deprecated-variable,FOO_MAKE_OPT,FOO_MAKE_OPTS))
> >
> 
> 
> -- 
> Arnout Vandecappelle                          arnout at mind be
> Senior Embedded Software Architect            +32-16-286500
> Essensium/Mind                                http://www.mind.be
> G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
> LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
> GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 3/8] core/pkg-generic: add help about package-specific rules

[Yann E. MORIN]

Add a package-variable to store the package-specific make rules.

Although this variable would be seldom used, we still document it.
However, we make sure the documentation explicitly states that this
variable should not be used (if it needs to be, the submitter of a
package will be told so during reviews).

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile                                | 1 +
 docs/manual/adding-packages-generic.txt | 6 ++++++
 package/pkg-generic.mk                  | 2 ++
 3 files changed, 9 insertions(+)

diff --git a/Makefile b/Makefile
index d24793b..72935b0 100644
--- a/Makefile
+++ b/Makefile
@@ -932,6 +932,7 @@ help:
 	@echo '  <pkg>-dirclean         - Remove <pkg> build directory'
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
+	@$(call HELP_RULE,$(PACKAGE_HELP))
 ifeq ($(BR2_PACKAGE_BUSYBOX),y)
 	@echo '  busybox-menuconfig     - Run BusyBox menuconfig'
 endif
diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index 8ed7fe8..fb20e2d 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -436,6 +436,12 @@ information is (assuming the package name is +libfoo+) :
   FLAT binary format is only 4k bytes. If the application consumes more stack,
   append the required number here.
 
+* +LIBFOO_HELP+ defines the help entries visible when running `make help`.
+  The expected content for this variable is a list of single- or double-
+  quoted strings, with each string in the format "action : help for action". 
+  This is seldom used, as packages rarely have custom rules. Do not use
+  this variable.
+
 The recommended way to define these variables is to use the following
 syntax:
 
diff --git a/package/pkg-generic.mk b/package/pkg-generic.mk
index 3904c09..335b811 100644
--- a/package/pkg-generic.mk
+++ b/package/pkg-generic.mk
@@ -910,6 +910,8 @@ ifeq ($$(patsubst %/,ERROR,$$($(2)_SITE)),ERROR)
 $$(error $(2)_SITE ($$($(2)_SITE)) cannot have a trailing slash)
 endif
 
+PACKAGE_HELP += $$($(2)_HELP)
+
 endif # $(2)_KCONFIG_VAR
 endef # inner-generic-package
 
-- 
1.9.1

[Buildroot] [PATCH 3/8] core/pkg-generic: add help about package-specific rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> Add a package-variable to store the package-specific make rules.
>
> Although this variable would be seldom used, we still document it.
> However, we make sure the documentation explicitly states that this
> variable should not be used (if it needs to be, the submitter of a
> package will be told so during reviews).
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

Reviewed-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

  pending of course the rename or removal of the HELP_RULE function.

  Regards,
  Arnout

> ---
>   Makefile                                | 1 +
>   docs/manual/adding-packages-generic.txt | 6 ++++++
>   package/pkg-generic.mk                  | 2 ++
>   3 files changed, 9 insertions(+)
>
> diff --git a/Makefile b/Makefile
> index d24793b..72935b0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -932,6 +932,7 @@ help:
>   	@echo '  <pkg>-dirclean         - Remove <pkg> build directory'
>   	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
>   	@echo '  <pkg>-rebuild          - Restart the build from the build step'
> +	@$(call HELP_RULE,$(PACKAGE_HELP))
>   ifeq ($(BR2_PACKAGE_BUSYBOX),y)
>   	@echo '  busybox-menuconfig     - Run BusyBox menuconfig'
>   endif
> diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
> index 8ed7fe8..fb20e2d 100644
> --- a/docs/manual/adding-packages-generic.txt
> +++ b/docs/manual/adding-packages-generic.txt
> @@ -436,6 +436,12 @@ information is (assuming the package name is +libfoo+) :
>     FLAT binary format is only 4k bytes. If the application consumes more stack,
>     append the required number here.
>
> +* +LIBFOO_HELP+ defines the help entries visible when running `make help`.
> +  The expected content for this variable is a list of single- or double-
> +  quoted strings, with each string in the format "action : help for action".
> +  This is seldom used, as packages rarely have custom rules. Do not use
> +  this variable.
> +
>   The recommended way to define these variables is to use the following
>   syntax:
>
> diff --git a/package/pkg-generic.mk b/package/pkg-generic.mk
> index 3904c09..335b811 100644
> --- a/package/pkg-generic.mk
> +++ b/package/pkg-generic.mk
> @@ -910,6 +910,8 @@ ifeq ($$(patsubst %/,ERROR,$$($(2)_SITE)),ERROR)
>   $$(error $(2)_SITE ($$($(2)_SITE)) cannot have a trailing slash)
>   endif
>
> +PACKAGE_HELP += $$($(2)_HELP)
> +
>   endif # $(2)_KCONFIG_VAR
>   endef # inner-generic-package
>
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 4/8] package/busybox: use the generic help rules

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile                   | 3 ---
 package/busybox/busybox.mk | 2 ++
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 72935b0..8134a14 100644
--- a/Makefile
+++ b/Makefile
@@ -933,9 +933,6 @@ help:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call HELP_RULE,$(PACKAGE_HELP))
-ifeq ($(BR2_PACKAGE_BUSYBOX),y)
-	@echo '  busybox-menuconfig     - Run BusyBox menuconfig'
-endif
 ifeq ($(BR2_LINUX_KERNEL),y)
 	@echo '  linux-menuconfig       - Run Linux kernel menuconfig'
 	@echo '  linux-savedefconfig    - Run Linux kernel savedefconfig'
diff --git a/package/busybox/busybox.mk b/package/busybox/busybox.mk
index 7c904c8..135f2e1 100644
--- a/package/busybox/busybox.mk
+++ b/package/busybox/busybox.mk
@@ -10,6 +10,8 @@ BUSYBOX_SOURCE = busybox-$(BUSYBOX_VERSION).tar.bz2
 BUSYBOX_LICENSE = GPLv2
 BUSYBOX_LICENSE_FILES = LICENSE
 
+BUSYBOX_HELP = "busybox-menuconfig : Run BusyBox menuconfig"
+
 BUSYBOX_CFLAGS = \
 	$(TARGET_CFLAGS)
 
-- 
1.9.1

[Buildroot] [PATCH 4/8] package/busybox: use the generic help rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

Reviewed-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

  Yeah, really looks better!

  Regards,
  Arnout

> ---
>   Makefile                   | 3 ---
>   package/busybox/busybox.mk | 2 ++
>   2 files changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 72935b0..8134a14 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -933,9 +933,6 @@ help:
>   	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
>   	@echo '  <pkg>-rebuild          - Restart the build from the build step'
>   	@$(call HELP_RULE,$(PACKAGE_HELP))
> -ifeq ($(BR2_PACKAGE_BUSYBOX),y)
> -	@echo '  busybox-menuconfig     - Run BusyBox menuconfig'
> -endif
>   ifeq ($(BR2_LINUX_KERNEL),y)
>   	@echo '  linux-menuconfig       - Run Linux kernel menuconfig'
>   	@echo '  linux-savedefconfig    - Run Linux kernel savedefconfig'
> diff --git a/package/busybox/busybox.mk b/package/busybox/busybox.mk
> index 7c904c8..135f2e1 100644
> --- a/package/busybox/busybox.mk
> +++ b/package/busybox/busybox.mk
> @@ -10,6 +10,8 @@ BUSYBOX_SOURCE = busybox-$(BUSYBOX_VERSION).tar.bz2
>   BUSYBOX_LICENSE = GPLv2
>   BUSYBOX_LICENSE_FILES = LICENSE
>
> +BUSYBOX_HELP = "busybox-menuconfig : Run BusyBox menuconfig"
> +
>   BUSYBOX_CFLAGS = \
>   	$(TARGET_CFLAGS)
>
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile       | 6 ------
 linux/linux.mk | 6 ++++++
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 8134a14..cdf2dac 100644
--- a/Makefile
+++ b/Makefile
@@ -933,12 +933,6 @@ help:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call HELP_RULE,$(PACKAGE_HELP))
-ifeq ($(BR2_LINUX_KERNEL),y)
-	@echo '  linux-menuconfig       - Run Linux kernel menuconfig'
-	@echo '  linux-savedefconfig    - Run Linux kernel savedefconfig'
-	@echo '  linux-update-defconfig - Save the Linux configuration to the path specified'
-	@echo '                             by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE'
-endif
 ifeq ($(BR2_TOOLCHAIN_BUILDROOT),y)
 	@echo '  uclibc-menuconfig      - Run uClibc menuconfig'
 endif
diff --git a/linux/linux.mk b/linux/linux.mk
index 7e20255..d530d00 100644
--- a/linux/linux.mk
+++ b/linux/linux.mk
@@ -8,6 +8,12 @@ LINUX_VERSION = $(call qstrip,$(BR2_LINUX_KERNEL_VERSION))
 LINUX_LICENSE = GPLv2
 LINUX_LICENSE_FILES = COPYING
 
+LINUX_HELP = \
+	"linux-menuconfig : Run Linux kernel menuconfig" \
+	"linux-savedefconfig : Run Linux kernel savedefconfig" \
+	"linux-update-defconfig : Save the Linux configuration to the path specified \
+				  by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"
+
 # Compute LINUX_SOURCE and LINUX_SITE from the configuration
 ifeq ($(BR2_LINUX_KERNEL_CUSTOM_TARBALL),y)
 LINUX_TARBALL = $(call qstrip,$(BR2_LINUX_KERNEL_CUSTOM_TARBALL_LOCATION))
-- 
1.9.1

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>   Makefile       | 6 ------
>   linux/linux.mk | 6 ++++++
>   2 files changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 8134a14..cdf2dac 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -933,12 +933,6 @@ help:
>   	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
>   	@echo '  <pkg>-rebuild          - Restart the build from the build step'
>   	@$(call HELP_RULE,$(PACKAGE_HELP))
> -ifeq ($(BR2_LINUX_KERNEL),y)
> -	@echo '  linux-menuconfig       - Run Linux kernel menuconfig'
> -	@echo '  linux-savedefconfig    - Run Linux kernel savedefconfig'
> -	@echo '  linux-update-defconfig - Save the Linux configuration to the path specified'
> -	@echo '                             by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE'
> -endif
>   ifeq ($(BR2_TOOLCHAIN_BUILDROOT),y)
>   	@echo '  uclibc-menuconfig      - Run uClibc menuconfig'
>   endif
> diff --git a/linux/linux.mk b/linux/linux.mk
> index 7e20255..d530d00 100644
> --- a/linux/linux.mk
> +++ b/linux/linux.mk
> @@ -8,6 +8,12 @@ LINUX_VERSION = $(call qstrip,$(BR2_LINUX_KERNEL_VERSION))
>   LINUX_LICENSE = GPLv2
>   LINUX_LICENSE_FILES = COPYING
>
> +LINUX_HELP = \
> +	"linux-menuconfig : Run Linux kernel menuconfig" \
> +	"linux-savedefconfig : Run Linux kernel savedefconfig" \
> +	"linux-update-defconfig : Save the Linux configuration to the path specified \
> +				  by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"

  So now this will be printed on a single line, instead of being split like it 
was before. Well, J?r?me's patch already did that as well I guess.

  Fixing that properly would make the HELP_RULE a bit too complicated, but 
starting the continuation line with " :   by..." doesn't look too shabby.

  I was also thinking that a define would have been better, but that doesn't 
work unfortunately.


  Regards,
  Arnout

> +
>   # Compute LINUX_SOURCE and LINUX_SITE from the configuration
>   ifeq ($(BR2_LINUX_KERNEL_CUSTOM_TARBALL),y)
>   LINUX_TARBALL = $(call qstrip,$(BR2_LINUX_KERNEL_CUSTOM_TARBALL_LOCATION))
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Jérôme Pouiller]

Hello Arnout,

On Thursday 10 March 2016 00:47:01 Arnout Vandecappelle wrote:
> On 03/09/16 23:22, Yann E. MORIN wrote:
[...]
> > +LINUX_HELP = \
> > +	"linux-menuconfig : Run Linux kernel menuconfig" \
> > +	"linux-savedefconfig : Run Linux kernel savedefconfig" \
> > +	"linux-update-defconfig : Save the Linux configuration to the path specified \
> > +				  by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"
> 
>   So now this will be printed on a single line, instead of being split
> like it was before. Well, J?r?me's patch already did that as well I
> guess.
In fact, my patch correctly support this case if you use two separate
strings:
  
EXTRA_HELP += \
   "linux-update-defconfig : Save the Linux configuration to the path specified" \
   "                           by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"


Regards,

-- 
J?r?me Pouiller, Sysmic
Embedded Linux specialist
http://www.sysmic.fr

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Thomas Petazzoni]

Hello,

On Thu, 10 Mar 2016 10:21:17 +0100, J?r?me Pouiller wrote:

> >   So now this will be printed on a single line, instead of being split
> > like it was before. Well, J?r?me's patch already did that as well I
> > guess.
> In fact, my patch correctly support this case if you use two separate
> strings:
>   
> EXTRA_HELP += \
>    "linux-update-defconfig : Save the Linux configuration to the path specified" \
>    "                           by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"

This is not super great either IMO.

What about doing something more Buildroot-esque and use the concept of
hooks that we already use everywhere ?

For example:

diff --git a/Makefile b/Makefile
index f2822a2..db9aee0 100644
--- a/Makefile
+++ b/Makefile
@@ -969,6 +969,7 @@ endif
        @echo
        @echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
        @echo '  make O=dir             - Locate all output files in "dir", including .config'
+       $(foreach hook,$(HELP_HOOKS),$(call $(hook)$(sep)))
        @echo
        @echo 'For further details, see README, generate the Buildroot manual, or consult'
        @echo 'it on-line at http://buildroot.org/docs.html'
diff --git a/package/busybox/busybox.mk b/package/busybox/busybox.mk
index 7c904c8..1a0b09c 100644
--- a/package/busybox/busybox.mk
+++ b/package/busybox/busybox.mk
@@ -250,4 +250,10 @@ $(error No BusyBox configuration file specified, check your BR2_PACKAGE_BUSYBOX_
 endif
 endif
 
+define BUSYBOX_HELP
+       @echo '  busybox-baz            - do stuff'
+endef
+
+HELP_HOOKS += BUSYBOX_HELP
+
 $(eval $(kconfig-package))

This way, it is just a function call, and the package, or external.mk
can do whatever it wants in terms of formatting the help text.
Including iterating on variables, showing the contents of a file, or
whatever.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Arnout Vandecappelle]

On 03/10/16 10:39, Thomas Petazzoni wrote:
> Hello,
>
> On Thu, 10 Mar 2016 10:21:17 +0100, J?r?me Pouiller wrote:
>
>>>    So now this will be printed on a single line, instead of being split
>>> like it was before. Well, J?r?me's patch already did that as well I
>>> guess.
>> In fact, my patch correctly support this case if you use two separate
>> strings:
>>
>> EXTRA_HELP += \
>>     "linux-update-defconfig : Save the Linux configuration to the path specified" \
>>     "                           by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"
>
> This is not super great either IMO.
>
> What about doing something more Buildroot-esque and use the concept of
> hooks that we already use everywhere ?
>
> For example:
>
> diff --git a/Makefile b/Makefile
> index f2822a2..db9aee0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -969,6 +969,7 @@ endif
>          @echo
>          @echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
>          @echo '  make O=dir             - Locate all output files in "dir", including .config'
> +       $(foreach hook,$(HELP_HOOKS),$(call $(hook)$(sep)))

  $(call ...) is redundant here. Yes, we currently have it in pkg-generic.mk, 
but it should be removed from there. Actually $(addsuffix $(sep),$(HELP_HOOKS)) 
will probably work.


>          @echo
>          @echo 'For further details, see README, generate the Buildroot manual, or consult'
>          @echo 'it on-line at http://buildroot.org/docs.html'
> diff --git a/package/busybox/busybox.mk b/package/busybox/busybox.mk
> index 7c904c8..1a0b09c 100644
> --- a/package/busybox/busybox.mk
> +++ b/package/busybox/busybox.mk
> @@ -250,4 +250,10 @@ $(error No BusyBox configuration file specified, check your BR2_PACKAGE_BUSYBOX_
>   endif
>   endif
>
> +define BUSYBOX_HELP
> +       @echo '  busybox-baz            - do stuff'
> +endef
> +
> +HELP_HOOKS += BUSYBOX_HELP

  This bit could easily be done in generic-package. I definitely don't like 
direct manipulation of global variables in a package.mk.

> +
>   $(eval $(kconfig-package))
>
> This way, it is just a function call, and the package, or external.mk
> can do whatever it wants in terms of formatting the help text.
> Including iterating on variables, showing the contents of a file, or
> whatever.

  It's incredible how much discussion we have about such a corner feature :-)
I guess we just need _something_ to disagree about :-P


  Regards,
  Arnout

-- 
Arnout Vandecappelle      arnout dot vandecappelle at essensium dot com
Senior Embedded Software Architect . . . . . . +32-478-010353 (mobile)
Essensium, Mind division . . . . . . . . . . . . . . http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium . . . . . BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Thomas Petazzoni]

Hello,

On Thu, 10 Mar 2016 10:52:03 +0100, Arnout Vandecappelle wrote:

>   This bit could easily be done in generic-package. I definitely don't like 
> direct manipulation of global variables in a package.mk.

You mean like TARGET_FINALIZE_HOOKS ? :-)

package/google-breakpad/google-breakpad.mk:TARGET_FINALIZE_HOOKS += GOOGLE_BREAKPAD_EXTRACT_SYMBOLS
package/luarocks/luarocks.mk:TARGET_FINALIZE_HOOKS += LUAROCKS_FINALIZE_TARGET
package/perl/perl.mk:TARGET_FINALIZE_HOOKS += PERL_FINALIZE_TARGET
package/python/python.mk:TARGET_FINALIZE_HOOKS += PYTHON_FINALIZE_TARGET
package/python3/python3.mk:TARGET_FINALIZE_HOOKS += PYTHON3_FINALIZE_TARGET
...

>   It's incredible how much discussion we have about such a corner feature :-)
> I guess we just need _something_ to disagree about :-P

Yes, I agree it's incredible. But I personally don't like Yann's
solution, it is too much over-engineered IMO, and is in fact less
flexible than simpler solutions.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Yann E. MORIN]

Thomas, All,

On 2016-03-10 10:39 +0100, Thomas Petazzoni spake thusly:
> On Thu, 10 Mar 2016 10:21:17 +0100, J?r?me Pouiller wrote:
> 
> > >   So now this will be printed on a single line, instead of being split
> > > like it was before. Well, J?r?me's patch already did that as well I
> > > guess.
> > In fact, my patch correctly support this case if you use two separate
> > strings:
> >   
> > EXTRA_HELP += \
> >    "linux-update-defconfig : Save the Linux configuration to the path specified" \
> >    "                           by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"
> 
> This is not super great either IMO.
> 
> What about doing something more Buildroot-esque and use the concept of
> hooks that we already use everywhere ?
> 
> For example:
> 
> diff --git a/Makefile b/Makefile
> index f2822a2..db9aee0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -969,6 +969,7 @@ endif
>         @echo
>         @echo '  make V=0|1             - 0 => quiet build (default), 1 => verbose build'
>         @echo '  make O=dir             - Locate all output files in "dir", including .config'
> +       $(foreach hook,$(HELP_HOOKS),$(call $(hook)$(sep)))
>         @echo
>         @echo 'For further details, see README, generate the Buildroot manual, or consult'
>         @echo 'it on-line at http://buildroot.org/docs.html'
> diff --git a/package/busybox/busybox.mk b/package/busybox/busybox.mk
> index 7c904c8..1a0b09c 100644
> --- a/package/busybox/busybox.mk
> +++ b/package/busybox/busybox.mk
> @@ -250,4 +250,10 @@ $(error No BusyBox configuration file specified, check your BR2_PACKAGE_BUSYBOX_
>  endif
>  endif
>  
> +define BUSYBOX_HELP
> +       @echo '  busybox-baz            - do stuff'
> +endef

There is one thing here that bothers me: duplicating the layout of the
help text in that many locations.

Having the macro be used means we can change that layout (e.g. to
accomodate for larger rules) in a single place, and
magically^Wautomatically see all the help texts all properly indented
at once.

Regards,
Yann E. MORIN.

> +HELP_HOOKS += BUSYBOX_HELP

To be done in pkg-generic, of course. ;-)

>  $(eval $(kconfig-package))
> 
> This way, it is just a function call, and the package, or external.mk
> can do whatever it wants in terms of formatting the help text.
> Including iterating on variables, showing the contents of a file, or
> whatever.

Well, remember that all this is *only* about documented the
package-specific rules, not any arbitrary package help.

Do we want to allow for any arbitrary package help? No; please, no.

Regards,
Yann E. MORIN.

> Best regards,
> 
> Thomas
> -- 
> Thomas Petazzoni, CTO, Free Electrons
> Embedded Linux, Kernel and Android engineering
> http://free-electrons.com

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Thomas Petazzoni]

Hello,

On Thu, 10 Mar 2016 21:34:38 +0100, Yann E. MORIN wrote:

> > +define BUSYBOX_HELP
> > +       @echo '  busybox-baz            - do stuff'
> > +endef
> 
> There is one thing here that bothers me: duplicating the layout of the
> help text in that many locations.
> 
> Having the macro be used means we can change that layout (e.g. to
> accomodate for larger rules) in a single place, and
> magically^Wautomatically see all the help texts all properly indented
> at once.

How often have we changed this layout over the years? I'd say probably
never. So why bother?

> > +HELP_HOOKS += BUSYBOX_HELP
> 
> To be done in pkg-generic, of course. ;-)

Well, if we are to do this in pkg-generic, then we should also do it
for TARGET_FINALIZE_HOOKS (but I agree it would be good idea).

> > This way, it is just a function call, and the package, or external.mk
> > can do whatever it wants in terms of formatting the help text.
> > Including iterating on variables, showing the contents of a file, or
> > whatever.
> 
> Well, remember that all this is *only* about documented the
> package-specific rules, not any arbitrary package help.
> 
> Do we want to allow for any arbitrary package help? No; please, no.

Of course we want. And just like any other thing in Buildroot, bad
things will not creep into the main tree because we review stuff.

It is *trivial* to realize that a bad help text is being added, much
more than many other things that we already have to check when
reviewing patches.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 5/8] linux: add the generic help rules

[Yann E. MORIN]

On 2016-03-10 00:47 +0100, Arnout Vandecappelle spake thusly:
> On 03/09/16 23:22, Yann E. MORIN wrote:
> >Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> >Cc: J?r?me Pouiller <jezz@sysmic.org>
> >Cc: Arnout Vandecappelle <arnout@mind.be>
> >Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> >---
> >  Makefile       | 6 ------
> >  linux/linux.mk | 6 ++++++
> >  2 files changed, 6 insertions(+), 6 deletions(-)
> >
> >diff --git a/Makefile b/Makefile
> >index 8134a14..cdf2dac 100644
> >--- a/Makefile
> >+++ b/Makefile
> >@@ -933,12 +933,6 @@ help:
> >  	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
> >  	@echo '  <pkg>-rebuild          - Restart the build from the build step'
> >  	@$(call HELP_RULE,$(PACKAGE_HELP))
> >-ifeq ($(BR2_LINUX_KERNEL),y)
> >-	@echo '  linux-menuconfig       - Run Linux kernel menuconfig'
> >-	@echo '  linux-savedefconfig    - Run Linux kernel savedefconfig'
> >-	@echo '  linux-update-defconfig - Save the Linux configuration to the path specified'
> >-	@echo '                             by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE'
> >-endif
> >  ifeq ($(BR2_TOOLCHAIN_BUILDROOT),y)
> >  	@echo '  uclibc-menuconfig      - Run uClibc menuconfig'
> >  endif
> >diff --git a/linux/linux.mk b/linux/linux.mk
> >index 7e20255..d530d00 100644
> >--- a/linux/linux.mk
> >+++ b/linux/linux.mk
> >@@ -8,6 +8,12 @@ LINUX_VERSION = $(call qstrip,$(BR2_LINUX_KERNEL_VERSION))
> >  LINUX_LICENSE = GPLv2
> >  LINUX_LICENSE_FILES = COPYING
> >
> >+LINUX_HELP = \
> >+	"linux-menuconfig : Run Linux kernel menuconfig" \
> >+	"linux-savedefconfig : Run Linux kernel savedefconfig" \
> >+	"linux-update-defconfig : Save the Linux configuration to the path specified \
> >+				  by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE"
> 
>  So now this will be printed on a single line, instead of being split like
> it was before. Well, J?r?me's patch already did that as well I guess.
> 
>  Fixing that properly would make the HELP_RULE a bit too complicated, but
> starting the continuation line with " :   by..." doesn't look too shabby.
> 
>  I was also thinking that a define would have been better, but that doesn't
> work unfortunately.

I have fixed it here. It works for any arbitrary number of needed extra
lines.

/me expects some flaming for a trivial sed expression... ;-)

Regards,
Yann E. MORIN.

>  Regards,
>  Arnout
> 
> >+
> >  # Compute LINUX_SOURCE and LINUX_SITE from the configuration
> >  ifeq ($(BR2_LINUX_KERNEL_CUSTOM_TARBALL),y)
> >  LINUX_TARBALL = $(call qstrip,$(BR2_LINUX_KERNEL_CUSTOM_TARBALL_LOCATION))
> >
> 
> 
> -- 
> Arnout Vandecappelle                          arnout at mind be
> Senior Embedded Software Architect            +32-16-286500
> Essensium/Mind                                http://www.mind.be
> G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
> LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
> GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 6/8] package/uclibc: use the generic help rules

[Yann E. MORIN]

Note that the uclibc-menuconfig rule was guarded behind
BR2_TOOLCHAIN_BUILDROOT, which is wrong ince we can build glibc or musl
toolchains too...

This is de facto fixed by moving the help text to the uClibc package.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile                 | 3 ---
 package/uclibc/uclibc.mk | 2 ++
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index cdf2dac..8973921 100644
--- a/Makefile
+++ b/Makefile
@@ -933,9 +933,6 @@ help:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call HELP_RULE,$(PACKAGE_HELP))
-ifeq ($(BR2_TOOLCHAIN_BUILDROOT),y)
-	@echo '  uclibc-menuconfig      - Run uClibc menuconfig'
-endif
 ifeq ($(BR2_TARGET_BAREBOX),y)
 	@echo '  barebox-menuconfig     - Run barebox menuconfig'
 	@echo '  barebox-savedefconfig  - Run barebox savedefconfig'
diff --git a/package/uclibc/uclibc.mk b/package/uclibc/uclibc.mk
index 200de04..c685828 100644
--- a/package/uclibc/uclibc.mk
+++ b/package/uclibc/uclibc.mk
@@ -11,6 +11,8 @@ UCLIBC_LICENSE = LGPLv2.1+
 UCLIBC_LICENSE_FILES = COPYING.LIB
 UCLIBC_INSTALL_STAGING = YES
 
+UCLIBC_HELP = "uclibc-menuconfig : Run uClibc menuconfig"
+
 # uclibc is part of the toolchain so disable the toolchain dependency
 UCLIBC_ADD_TOOLCHAIN_DEPENDENCY = NO
 
-- 
1.9.1

[Buildroot] [PATCH 6/8] package/uclibc: use the generic help rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> Note that the uclibc-menuconfig rule was guarded behind
> BR2_TOOLCHAIN_BUILDROOT, which is wrong ince we can build glibc or musl
> toolchains too...
>
> This is de facto fixed by moving the help text to the uClibc package.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

Reviewed-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

  Regards,
  Arnout

> ---
>   Makefile                 | 3 ---
>   package/uclibc/uclibc.mk | 2 ++
>   2 files changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index cdf2dac..8973921 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -933,9 +933,6 @@ help:
>   	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
>   	@echo '  <pkg>-rebuild          - Restart the build from the build step'
>   	@$(call HELP_RULE,$(PACKAGE_HELP))
> -ifeq ($(BR2_TOOLCHAIN_BUILDROOT),y)
> -	@echo '  uclibc-menuconfig      - Run uClibc menuconfig'
> -endif
>   ifeq ($(BR2_TARGET_BAREBOX),y)
>   	@echo '  barebox-menuconfig     - Run barebox menuconfig'
>   	@echo '  barebox-savedefconfig  - Run barebox savedefconfig'
> diff --git a/package/uclibc/uclibc.mk b/package/uclibc/uclibc.mk
> index 200de04..c685828 100644
> --- a/package/uclibc/uclibc.mk
> +++ b/package/uclibc/uclibc.mk
> @@ -11,6 +11,8 @@ UCLIBC_LICENSE = LGPLv2.1+
>   UCLIBC_LICENSE_FILES = COPYING.LIB
>   UCLIBC_INSTALL_STAGING = YES
>
> +UCLIBC_HELP = "uclibc-menuconfig : Run uClibc menuconfig"
> +
>   # uclibc is part of the toolchain so disable the toolchain dependency
>   UCLIBC_ADD_TOOLCHAIN_DEPENDENCY = NO
>
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 7/8] boot/barebox: use the generic help rules

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile                | 4 ----
 boot/barebox/barebox.mk | 4 ++++
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 8973921..a9cfe03 100644
--- a/Makefile
+++ b/Makefile
@@ -933,10 +933,6 @@ help:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call HELP_RULE,$(PACKAGE_HELP))
-ifeq ($(BR2_TARGET_BAREBOX),y)
-	@echo '  barebox-menuconfig     - Run barebox menuconfig'
-	@echo '  barebox-savedefconfig  - Run barebox savedefconfig'
-endif
 	@echo
 	@echo 'Documentation:'
 	@echo '  manual                 - build manual in all formats'
diff --git a/boot/barebox/barebox.mk b/boot/barebox/barebox.mk
index 7715daf..32ecd76 100644
--- a/boot/barebox/barebox.mk
+++ b/boot/barebox/barebox.mk
@@ -6,6 +6,10 @@
 
 BAREBOX_VERSION = $(call qstrip,$(BR2_TARGET_BAREBOX_VERSION))
 
+BAREBOX_HELP = \
+	"barebox-menuconfig : Run barebox menuconfig" \
+	"barebox-savedefconfig : Run barebox savedefconfig"
+
 ifeq ($(BAREBOX_VERSION),custom)
 # Handle custom Barebox tarballs as specified by the configuration
 BAREBOX_TARBALL = $(call qstrip,$(BR2_TARGET_BAREBOX_CUSTOM_TARBALL_LOCATION))
-- 
1.9.1

[Buildroot] [PATCH 7/8] boot/barebox: use the generic help rules

[Arnout Vandecappelle]

On 03/09/16 23:22, Yann E. MORIN wrote:
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> Cc: J?r?me Pouiller <jezz@sysmic.org>
> Cc: Arnout Vandecappelle <arnout@mind.be>
> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

Reviewed-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

  Regards,
  Arnout

> ---
>   Makefile                | 4 ----
>   boot/barebox/barebox.mk | 4 ++++
>   2 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 8973921..a9cfe03 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -933,10 +933,6 @@ help:
>   	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
>   	@echo '  <pkg>-rebuild          - Restart the build from the build step'
>   	@$(call HELP_RULE,$(PACKAGE_HELP))
> -ifeq ($(BR2_TARGET_BAREBOX),y)
> -	@echo '  barebox-menuconfig     - Run barebox menuconfig'
> -	@echo '  barebox-savedefconfig  - Run barebox savedefconfig'
> -endif
>   	@echo
>   	@echo 'Documentation:'
>   	@echo '  manual                 - build manual in all formats'
> diff --git a/boot/barebox/barebox.mk b/boot/barebox/barebox.mk
> index 7715daf..32ecd76 100644
> --- a/boot/barebox/barebox.mk
> +++ b/boot/barebox/barebox.mk
> @@ -6,6 +6,10 @@
>
>   BAREBOX_VERSION = $(call qstrip,$(BR2_TARGET_BAREBOX_VERSION))
>
> +BAREBOX_HELP = \
> +	"barebox-menuconfig : Run barebox menuconfig" \
> +	"barebox-savedefconfig : Run barebox savedefconfig"
> +
>   ifeq ($(BAREBOX_VERSION),custom)
>   # Handle custom Barebox tarballs as specified by the configuration
>   BAREBOX_TARBALL = $(call qstrip,$(BR2_TARGET_BAREBOX_CUSTOM_TARBALL_LOCATION))
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 8/8] docs/manual: document the br2-external help-local

[Yann E. MORIN]

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: J?r?me Pouiller <jezz@sysmic.org>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/manual/customize-outside-br.txt | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index 9ad177d..d89dc6f 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -107,3 +107,23 @@ And then in +$(BR2_EXTERNAL)/package/package1+ and
    output of +make list-defconfigs+ and allow them to be loaded with the
    normal +make <name>_defconfig+ command. They will be visible under the
    +User-provided configs+' label in the 'make list-defconfigs' output.
+
+Additionally, an +external.mk+ file may define the +help-local+ make
+rule, to document custom make targets specific to this +BR2_EXTERNAL+
+tree. It is possible to use the +HELP_RULE+ macro to pretty-print those
+additional rules:
+
+------
+BR2_EXTERNAL_HELP = \
+    "my-rule : some help text for my-rule" \
+    "my-other-rule : some help text for my-other-rule"
+
+help-local:
+    @echo 'Here goes your local help'
+    @$(call HELP_RULE,$(BR2_EXTERNAL_HELP))
+    @echo
+    @echo 'Please contact support at company.com in case of problem.'
+------
+
+The format for +BR2_EXTERNAL_HELP+ is the same as the +LIBFOO_HELP+
+package variable, defined in xref:generic-package-tutorial[].
-- 
1.9.1

[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Arnout Vandecappelle]

  Hi Yann,

  Feedback on the overall series rather than individual patches.

On 03/09/16 23:22, Yann E. MORIN wrote:
> Hello All!
>
> This series is an alternative proposal to support displaying custom,
> local help, most probably from a br2-external tree (or from a lcal.mk,
> but that'd be pretty insane).
>
> The basic idea is to offer the user help entries for local
> customisations, but without mixing them with our own help entries.
 >
> I believe we want to keep them separate, as inter-mixing the two could
> lead users to believe those addtional help entries are "native" in
> buildroot, when they are not.

  This is where I have a different opinion. I don't see a problem with "mixing" 
(it's actually appending) with the normal buildroot help. For the user, it makes 
no difference if it's internal or external. And all the additional documentation 
and special handling is really not worth it for such a corner case, IMHO.

  That said, it's mostly bike-shedding, so I don't care too much either way.


> The same way we expose all of br2-external config options under a
> sub-menu labelled "User-provided options",

  Well, I think that's more a technical accident than a deliberate decision. 
It's just not possible to insert external stuff into package/Config.in.

> we do similarly for the
> custom help, albeit with a slight shorter moniker, 'help-local'.

  What I _do_ strongly oppose is the 'local' bit. external or something is 
better IMHO.


> After the first patch implements this (which is really all that is
> needed to print custom help), we go further with providing a macro that
> pretty-prints the help for rules, so that the layout is all handled in a
> single location. This macro can also be used by the local help, too.

  This bit I really like!


  Regards,
  Arnout

> This macro is then used to implement per-package specific help (which is
> currently only about kconfig-related changes, but can not easily be done
> in the kconfig-package infra) into the packages themseves, to clean up
> the main help code (the entris are still displayed there, they are just
> definedin each concerned package).
>
> All that, plus a bit of associated documentation, of course. ;-)
>
> Thanks to J?r?me for his initial proposal, and Arnout for
> before-inception suggestions:
>      http://lists.busybox.net/pipermail/buildroot/2016-March/155415.html
>
> Regards,
> Yann E. MORIN.
>
>
> The following changes since commit 07f46c2b6daec44a6176039c90be67e66c4c2e42:
>
>    package/busybox: support automatic module loading with mdev (2016-03-09 23:07:44 +0100)
>
> are available in the git repository at:
>
>    git://git.busybox.net/~ymorin/git/buildroot yem/help
>
> for you to fetch changes up to b94d50a5f7717ad1ea2d9cab129155a0ab203f71:
>
>    docs/manual: document the br2-external help-local (2016-03-09 23:10:37 +0100)
>
> ----------------------------------------------------------------
> Yann E. MORIN (8):
>        core: add the possibility to provide help for local, custom rules
>        core/pkg-utils: add a macro to pretty-print a help entry
>        core/pkg-generic: add help about package-specific rules
>        package/busybox: use the generic help rules
>        linux: add the generic help rules
>        package/uclibc: use the generic help rules
>        boot/barebox: use the generic help rules
>        docs/manual: document the br2-external help-local
>
>   Makefile                                | 23 +++++++----------------
>   boot/barebox/barebox.mk                 |  4 ++++
>   docs/manual/adding-packages-generic.txt |  6 ++++++
>   docs/manual/customize-outside-br.txt    | 20 ++++++++++++++++++++
>   linux/linux.mk                          |  6 ++++++
>   package/busybox/busybox.mk              |  2 ++
>   package/pkg-generic.mk                  |  2 ++
>   package/pkg-utils.mk                    | 13 +++++++++++++
>   package/uclibc/uclibc.mk                |  2 ++
>   9 files changed, 62 insertions(+), 16 deletions(-)
>


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7493 020B C7E3 8618 8DEC 222C 82EB F404 F9AC 0DDF

[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Thomas Petazzoni]

Hello,

On Thu, 10 Mar 2016 00:35:03 +0100, Arnout Vandecappelle wrote:

> > After the first patch implements this (which is really all that is
> > needed to print custom help), we go further with providing a macro that
> > pretty-prints the help for rules, so that the layout is all handled in a
> > single location. This macro can also be used by the local help, too.
> 
>   This bit I really like!

Doesn't Yann proposal fails short if you want to pretty print something
like this:

	foobar - This is a really really long help message that spans
	         multiple lines, and would definitely be too long on
	         one single line.

IOW, I believe we should leave more freedom to what is appended to the
help text, and simply leave it to the person writing the help text to
format it properly.

In my opinion, the very simple proposal from J?r?me has turned into a
much more complicated solution, with no real benefit.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Yann E. MORIN]

Thomas, All,

On 2016-03-10 09:31 +0100, Thomas Petazzoni spake thusly:
> On Thu, 10 Mar 2016 00:35:03 +0100, Arnout Vandecappelle wrote:
> 
> > > After the first patch implements this (which is really all that is
> > > needed to print custom help), we go further with providing a macro that
> > > pretty-prints the help for rules, so that the layout is all handled in a
> > > single location. This macro can also be used by the local help, too.
> > 
> >   This bit I really like!
> 
> Doesn't Yann proposal fails short if you want to pretty print something
> like this:
> 
> 	foobar - This is a really really long help message that spans
> 	         multiple lines, and would definitely be too long on
> 	         one single line.

Indeed, it was no longer possible with the patchset I posted (which was
just hacked around quickly), but it's fixed locally.

> IOW, I believe we should leave more freedom to what is appended to the
> help text, and simply leave it to the person writing the help text to
> format it properly.

Well, the first patch in my series is just that: expost a new hel prule
that the user is *entirely* free to implement on his own. The macro is
just an added bonus.

Basically, if all one wants is to display help for br2-external or other
such customisations, then the first patch in my series was entirely
sufficient. It is addressing my concenr about mixing our help with
custom help.

On the other hand, patches 2 onweard were addressing the second patch in
J?r?me's series, which was moving packages' specific help into the
corresponding packages. It has nothing to do with providing custom help,
althgouh custom help may (anmd it's only a 'may') use that macro, of
course.

> In my opinion, the very simple proposal from J?r?me has turned into a
> much more complicated solution, with no real benefit.

Well, I have two concerns about that series:
 1- the mixing of internal and custom help,
 2- the way it is implemented looks ugly to me.

And I doubt my own proposal is very complex. Sure, there are two trivial
shell expansions, that are even POSIX and not bashisms. Compared to
other dirty tricks we do in a lot of other places, those are hardly
black magic...

Regards,
Yann E. MORIN.

> Best regards,
> 
> Thomas
> -- 
> Thomas Petazzoni, CTO, Free Electrons
> Embedded Linux, Kernel and Android engineering
> http://free-electrons.com

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 0/8] core: allow for custom, local help; rearrange package-specific help (branch yem/help)

[Thomas Petazzoni]

Hello,

On Thu, 10 Mar 2016 00:35:03 +0100, Arnout Vandecappelle wrote:

>   This is where I have a different opinion. I don't see a problem with "mixing" 
> (it's actually appending) with the normal buildroot help. For the user, it makes 
> no difference if it's internal or external. And all the additional documentation 
> and special handling is really not worth it for such a corner case, IMHO.

I do fully agree with you. We want the simplest possible solution here,
because we don't want:

 1/ to enforce too much things

 2/ to have to write tons of documentation in our manual to document
    such a silly / corner case aspect

Please, let's stop over-engineering things. Keep It Simple Stupid.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com