[Buildroot] [PATCH 1/8 v3] core/pkg-generic: add support for package-defined help

[Buildroot] [PATCH 1/8 v3] core/pkg-generic: add support for package-defined help

[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: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

---
Changes v2 -> v3:
  - package don't provide help text, they provide help commands
---
 Makefile                                | 1 +
 docs/manual/adding-packages-generic.txt | 6 ++++++
 package/pkg-generic.mk                  | 4 ++++
 3 files changed, 11 insertions(+)

diff --git a/Makefile b/Makefile
index 21d63f6..d77b539 100644
--- a/Makefile
+++ b/Makefile
@@ -937,6 +937,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'
+	$(foreach p,$(HELP_PACKAGES),$($(p)_HELP_CMDS)$(sep))
 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..de8aca2 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -497,6 +497,12 @@ different steps of the build process.
   systemd is selected as the init system in the configuration, only
   +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
 
+* +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
+  is included to the main +make help+ output. These commands can print
+  anything in any format.
+  This is seldom used, as packages rarely have custom rules. *Do not use
+  this variable*, unless you really know that you need to print help.
+
 The preferred way to define these variables is:
 
 ----------------------
diff --git a/package/pkg-generic.mk b/package/pkg-generic.mk
index b031879..374d9d5 100644
--- a/package/pkg-generic.mk
+++ b/package/pkg-generic.mk
@@ -914,6 +914,10 @@ ifeq ($$(patsubst %/,ERROR,$$($(2)_SITE)),ERROR)
 $$(error $(2)_SITE ($$($(2)_SITE)) cannot have a trailing slash)
 endif
 
+ifneq ($$($(2)_HELP_CMDS),)
+HELP_PACKAGES += $(2)
+endif
+
 endif # $(2)_KCONFIG_VAR
 endef # inner-generic-package
 
-- 
2.7.4

[Buildroot] [PATCH 2/8 v3] core: name the package before its help text

[Yann E. MORIN]

Currently, all our internal packages provide actions that are prefixed
with their own names. This makes it obvious what package the action
refer to.

However, the help commands are really free-form. This means that
packages (and especially packages from a br2-external tree) may provide
completely arbitrary help text.

As such, all that text can get pretty easily mixed up, and it will be
very difficult to read.

Prefix each package-specific help text with the name of the package it
refers to. This generate a "make help" that looks like:

    [...]
    Package-specific:
      <pkg>                  - Build and install <pkg> and all its dependencies
      <pkg>-source           - Only download the source files for <pkg>
      <pkg>-extract          - Extract <pkg> sources
      <pkg>-patch            - Apply patches to <pkg>
      <pkg>-depends          - Build <pkg>'s dependencies
      <pkg>-configure        - Build <pkg> up to the configure step
      <pkg>-build            - Build <pkg> up to the build step
      <pkg>-graph-depends    - Generate a graph of <pkg>'s dependencies
      <pkg>-dirclean         - Remove <pkg> build directory
      <pkg>-reconfigure      - Restart the build from the configure step
      <pkg>-rebuild          - Restart the build from the build step

    busybox:
      busybox-menuconfig     - Run BusyBox menuconfig
      busybox-nconfig        - Run BusyBox nconfig

    barebox:
      barebox-menuconfig     - Run barebox menuconfig
      barebox-savedefconfig  - Run barebox savedefconfig

    linux:
      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

    Documentation:
      manual                 - build manual in all formats
      manual-html            - build manual in HTML
      [...]

(Note: busybox, barebox, linux help will be converted in followup
commits, they are represented here as an example of what this patch
does look like.)

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index d77b539..65f5a65 100644
--- a/Makefile
+++ b/Makefile
@@ -937,7 +937,10 @@ 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'
-	$(foreach p,$(HELP_PACKAGES),$($(p)_HELP_CMDS)$(sep))
+	$(foreach p,$(HELP_PACKAGES), \
+		@echo $(sep) \
+		@echo '$($(p)_NAME):' $(sep) \
+		$($(p)_HELP_CMDS)$(sep))
 ifeq ($(BR2_PACKAGE_BUSYBOX),y)
 	@echo '  busybox-menuconfig     - Run BusyBox menuconfig'
 endif
-- 
2.7.4

[Buildroot] [PATCH 0/8 v3] core: add support for package help (branch yem/help)

[Yann E. MORIN]

Hello All!

This series introduces the ability for packages to declare help entries,
that are added to the main help.

This is done by allowing packages to define an additional set of
commands, besides the existing configure/build/instal/... ones. Packages
can provide whatever they want as their help text, it is completely
free-form. However, to help packages present help that lines up well
with the rest of the main help, we provide a new macro to do a nice
formatting; its use is totally optional.

This is used for our bundled packages to display their kconfig rules [0]:
busybox, uClibc, linux and barebox, to replace the hard-coded entries in
our main help.

Finally, we also make use of the new macro to print our main help, to
ensure consistency in the output.


[0] we could very well move that to the kconfig infra, btw, but that can
    be done in follow-up patches.


Changes v2 -> v3:
  - don't force packages to only provide canned help text, allow them
    to provide arbitrary commands.  (Thomas)
  - make the macro a little bit simpler; only print a single line at
    each call; use a awk script that is easier to grok than the sed
    script. Enhance the commit log and comment in the code.
  - add conversion of the main help over to using the help macro.
  - drop the custom help target as it does not work (it was applied
    and then reverted).


Regards,
Yann E. MORIN.


The following changes since commit a898d5de17f4b32ee29ff47734ff5717c6b40f03

  package/nodejs: Update npm to use NODEJS_CONF_OPTS (2016-06-04 14:32:16 +0200)


are available in the git repository at:

  https://git.busybox.net/~ymorin/git/buildroot

for you to fetch changes up to f6bb545ede1f4e8692e031f48393991b0303f835

  core: use the print-help macro to print the main help (2016-06-04 18:06:01 +0200)


----------------------------------------------------------------
Yann E. MORIN (8):
      core/pkg-generic: add support for package-defined help
      core: name the package before its help text
      core/pkg-utils: add a macro to pretty-print a help entry
      package/busybox: use the generic help rules
      linux: use the generic help rules
      package/uclibc: use the generic help rules
      boot/barebox: use the generic help rules
      core: use the print-help macro to print the main help

 Makefile                                | 129 ++++++++++++++++----------------
 boot/barebox/barebox/barebox.mk         |   5 ++
 docs/manual/adding-packages-generic.txt |  16 ++++
 linux/linux.mk                          |   7 ++
 package/busybox/busybox.mk              |   5 ++
 package/pkg-generic.mk                  |   4 +
 package/pkg-utils.mk                    |  27 +++++++
 package/uclibc/uclibc.mk                |   4 +
 8 files changed, 134 insertions(+), 63 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 3/8 v3] 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.

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

The output is formatted as the rest of the help text is (the left pipe
denotes the left of the terminal ditto the right one for the right):

    |.-----------------79-------------------.|
    |  .------22------.   .-------52-------. |
    |  action-name      - Help text on maybe |
    |                     more than a line   |

The macro is not using a simple:
    printf "  %-22s - %-52s\n" "$(1)" "$(2)"

because some packages may want to print a long description that does not
fit on a 80-char wide line (actually, linux is such a package, with the
help text for its linux-update-defconfig rule).

Instead, we use a little trick:

 1- print the action to the correct width, followed by the separating
    hyphen, but with no terminating new line;

 2- use fmt(1) to re-format the help text to the correct width, but
    with no left margin;

 3- use a simple awk script to indent all but the first line of the
    re-formated help text.

We can't use only fmt, as it is not smart enough to achieve the above
formatting; it is only as good as for what we use it. Un-assigned
variables in awk are treated as zero when evaluated as a int, so we need
not assign it before using it.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

---
Changes v2 -> v3:
  - only print a single help entry
  - expect two args, one for action, one for help

Changes v1 -> v2:
  - properly format multi-line output
---
 docs/manual/adding-packages-generic.txt | 12 +++++++++++-
 package/pkg-utils.mk                    | 27 +++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index de8aca2..047f3ec 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -499,7 +499,8 @@ different steps of the build process.
 
 * +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
   is included to the main +make help+ output. These commands can print
-  anything in any format.
+  anything in any format; to help format the output the same as the main
+  help, you can use the +print-help+ macro (see below for an example).
   This is seldom used, as packages rarely have custom rules. *Do not use
   this variable*, unless you really know that you need to print help.
 
@@ -531,4 +532,13 @@ In the action definitions, you can use the following variables:
 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
   variables to install the packages properly.
 
+To pretty-print the help text, you can use the +print-help+ macro:
+
+----
+define LIBFOO_HELP_CMDS
+	$(call print-help,package-action,help text for package-action)
+	$(call print-help,some-action,help text for some-action)
+endef
+----
+
 Finally, you can also use hooks. See xref:hooks[] for more information.
diff --git a/package/pkg-utils.mk b/package/pkg-utils.mk
index f88313a..40578de 100644
--- a/package/pkg-utils.mk
+++ b/package/pkg-utils.mk
@@ -104,6 +104,33 @@ define sep
 
 endef
 
+# Pretty-print a make rule in the help text
+#
+# $(1): the action (aka the make target); should be less than 22
+#       characters, otherwise the help text will not be correctly
+#       indented.
+# $(2): the help text
+#
+# Both should be un-quoted.
+#
+# The output is a 79-char wide line formatted as such (with two
+# leading spaces):
+#   action-up-to-22-chars-long - help for action up to 52 chars wide
+#                                with the remaining of the help text
+#                                that does not fit on the first line
+#
+# Note: in the awk script, the 'i' variable is first used unset, but
+# in awk, unset variables are evaluated to zero, which is right what
+# we need on the first line; then i is set and will be used for the
+# second-and-further lines.
+#
+define print-help
+	@printf "  %-22s - " "$(strip $(1))"; \
+	printf "%s\n" "$(strip $(2))" \
+	|fmt -w52 -g52 -u \
+	|awk '{ printf( "%-*s%s\n", i, "", $$(0) ); i=27 }'
+endef
+
 # check-deprecated-variable -- throw an error on deprecated variables
 # example:
 #   $(eval $(call check-deprecated-variable,FOO_MAKE_OPT,FOO_MAKE_OPTS))
-- 
2.7.4

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

[Yann E. MORIN]

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

diff --git a/Makefile b/Makefile
index 65f5a65..f5ae613 100644
--- a/Makefile
+++ b/Makefile
@@ -941,9 +941,6 @@ help:
 		@echo $(sep) \
 		@echo '$($(p)_NAME):' $(sep) \
 		$($(p)_HELP_CMDS)$(sep))
-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 c7fb8b4..5d46e5a 100644
--- a/package/busybox/busybox.mk
+++ b/package/busybox/busybox.mk
@@ -10,6 +10,11 @@ BUSYBOX_SOURCE = busybox-$(BUSYBOX_VERSION).tar.bz2
 BUSYBOX_LICENSE = GPLv2
 BUSYBOX_LICENSE_FILES = LICENSE
 
+define BUSYBOX_HELP_CMDS
+	$(call print-help,busybox-menuconfig,Run BusyBox menuconfig)
+	$(call print-help,busybox-nconfig,Run BusyBox nconfig)
+endef
+
 BUSYBOX_CFLAGS = \
 	$(TARGET_CFLAGS)
 
-- 
2.7.4

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

[Yann E. MORIN]

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

diff --git a/Makefile b/Makefile
index f5ae613..bb3d588 100644
--- a/Makefile
+++ b/Makefile
@@ -941,12 +941,6 @@ help:
 		@echo $(sep) \
 		@echo '$($(p)_NAME):' $(sep) \
 		$($(p)_HELP_CMDS)$(sep))
-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 4f4f802..d6d9132 100644
--- a/linux/linux.mk
+++ b/linux/linux.mk
@@ -8,6 +8,13 @@ LINUX_VERSION = $(call qstrip,$(BR2_LINUX_KERNEL_VERSION))
 LINUX_LICENSE = GPLv2
 LINUX_LICENSE_FILES = COPYING
 
+define LINUX_HELP_CMDS
+	$(call print-help,linux-menuconfig,Run Linux kernel menuconfig)
+	$(call print-help,linux-savedefconfig,Run Linux kernel savedefconfig)
+	$(call print-help,linux-update-defconfig,Save the Linux configuration \
+		to the path specified by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE)
+endef
+
 # 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))
-- 
2.7.4

[Buildroot] [PATCH 6/8 v3] 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 since 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: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile                 | 3 ---
 package/uclibc/uclibc.mk | 4 ++++
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index bb3d588..f007db2 100644
--- a/Makefile
+++ b/Makefile
@@ -941,9 +941,6 @@ help:
 		@echo $(sep) \
 		@echo '$($(p)_NAME):' $(sep) \
 		$($(p)_HELP_CMDS)$(sep))
-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 cf343a4..aa5fc79 100644
--- a/package/uclibc/uclibc.mk
+++ b/package/uclibc/uclibc.mk
@@ -11,6 +11,10 @@ UCLIBC_LICENSE = LGPLv2.1+
 UCLIBC_LICENSE_FILES = COPYING.LIB
 UCLIBC_INSTALL_STAGING = YES
 
+define UCLIBC_HELP_CMDS
+	$(call print-help,uclibc-menuconfig,Run uClibc menuconfig)
+endef
+
 # uclibc is part of the toolchain so disable the toolchain dependency
 UCLIBC_ADD_TOOLCHAIN_DEPENDENCY = NO
 
-- 
2.7.4

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

[Yann E. MORIN]

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

diff --git a/Makefile b/Makefile
index f007db2..3f5c3d3 100644
--- a/Makefile
+++ b/Makefile
@@ -941,10 +941,6 @@ help:
 		@echo $(sep) \
 		@echo '$($(p)_NAME):' $(sep) \
 		$($(p)_HELP_CMDS)$(sep))
-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/barebox.mk b/boot/barebox/barebox/barebox.mk
index 6a5a80d..9359ddd 100644
--- a/boot/barebox/barebox/barebox.mk
+++ b/boot/barebox/barebox/barebox.mk
@@ -4,5 +4,10 @@
 #
 ################################################################################
 
+define BAREBOX_HELP_CMDS
+	$(call print-help,barebox-menuconfig,Run barebox menuconfig)
+	$(call print-help,barebox-savedefconfig,Run barebox savedefconfig)
+endef
+
 # Instantiate the barebox package
 $(eval $(barebox-package))
-- 
2.7.4

[Buildroot] [PATCH 8/8 v3] core: use the print-help macro to print the main help

[Yann E. MORIN]

The formatting of the main help is not consistent. We have most lines
that are wrapped below 80-chars, while a few are larger than that.

Use the new print-help macro for all entries in the help text, to ensure
consistency in the formatting.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 Makefile | 109 ++++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 62 insertions(+), 47 deletions(-)

diff --git a/Makefile b/Makefile
index 3f5c3d3..2885469 100644
--- a/Makefile
+++ b/Makefile
@@ -900,68 +900,83 @@ endif
 
 help:
 	@echo 'Cleaning:'
-	@echo '  clean                  - delete all files created by build'
-	@echo '  distclean              - delete all non-source files (including .config)'
+	$(call print-help,clean,Delete all files created by build)
+	$(call print-help,distclean,Delete all non-source files (including .config))
 	@echo
 	@echo 'Build:'
-	@echo '  all                    - make world'
-	@echo '  toolchain              - build toolchain'
+	$(call print-help,all,Make world)
+	$(call print-help,toolchain,Build toolchain)
 	@echo
 	@echo 'Configuration:'
-	@echo '  menuconfig             - interactive curses-based configurator'
-	@echo '  nconfig                - interactive ncurses-based configurator'
-	@echo '  xconfig                - interactive Qt-based configurator'
-	@echo '  gconfig                - interactive GTK-based configurator'
-	@echo '  oldconfig              - resolve any unresolved symbols in .config'
-	@echo '  silentoldconfig        - Same as oldconfig, but quietly, additionally update deps'
-	@echo '  olddefconfig           - Same as silentoldconfig but sets new symbols to their default value'
-	@echo '  randconfig             - New config with random answer to all options'
-	@echo '  defconfig              - New config with default answer to all options'
-	@echo '                             BR2_DEFCONFIG, if set, is used as input'
-	@echo '  savedefconfig          - Save current config to BR2_DEFCONFIG (minimal config)'
-	@echo '  allyesconfig           - New config where all options are accepted with yes'
-	@echo '  allnoconfig            - New config where all options are answered with no'
-	@echo '  randpackageconfig      - New config with random answer to package options'
-	@echo '  allyespackageconfig    - New config where pkg options are accepted with yes'
-	@echo '  allnopackageconfig     - New config where package options are answered with no'
+	$(call print-help,menuconfig,Interactive curses-based configurator)
+	$(call print-help,nconfig,Interactive ncurses-based configurator)
+	$(call print-help,xconfig,Interactive Qt-based configurator)
+	$(call print-help,gconfig,Interactive GTK-based configurator)
+	$(call print-help,oldconfig,Resolve any unresolved symbols in .config)
+	$(call print-help,silentoldconfig,Same as oldconfig but quiet)
+	$(call print-help,olddefconfig, \
+		Same as silentoldconfig but sets new \
+		symbols to their default value)
+	$(call print-help,randconfig, \
+		New config with random answer to all options)
+	$(call print-help,defconfig, \
+		New config with default answer to all options; \
+		BR2_DEFCONFIG if set is used as input)
+	$(call print-help,savedefconfig, \
+		Save current config to BR2_DEFCONFIG (minimal config))
+	$(call print-help,allyesconfig, \
+		New config where all options are accepted with yes)
+	$(call print-help,allnoconfig, \
+		New config where all options are answered with no)
+	$(call print-help,randpackageconfig, \
+		New config with random answer to package options)
+	$(call print-help,allyespackageconfig, \
+		New config where pkg options are accepted with yes)
+	$(call print-help,allnopackageconfig, \
+		New config where pkg options are answered with no)
 	@echo
 	@echo 'Package-specific:'
-	@echo '  <pkg>                  - Build and install <pkg> and all its dependencies'
-	@echo '  <pkg>-source           - Only download the source files for <pkg>'
-	@echo '  <pkg>-extract          - Extract <pkg> sources'
-	@echo '  <pkg>-patch            - Apply patches to <pkg>'
-	@echo '  <pkg>-depends          - Build <pkg>'\''s dependencies'
-	@echo '  <pkg>-configure        - Build <pkg> up to the configure step'
-	@echo '  <pkg>-build            - Build <pkg> up to the build step'
-	@echo '  <pkg>-graph-depends    - Generate a graph of <pkg>'\''s dependencies'
-	@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 print-help,<pkg>,Build and install <pkg> and all its dependencies)
+	$(call print-help,<pkg>-source,Only download the source files for <pkg>)
+	$(call print-help,<pkg>-extract,Extract <pkg> sources)
+	$(call print-help,<pkg>-patch,Apply patches to <pkg>)
+	$(call print-help,<pkg>-depends,Build the dependencies of <pkg>)
+	$(call print-help,<pkg>-configure,Build <pkg> up to the configure step)
+	$(call print-help,<pkg>-build,Build <pkg> up to the build step)
+	$(call print-help,<pkg>-graph-depends,Generate a dependency graph of <pkg>)
+	$(call print-help,<pkg>-dirclean,Remove the build directory for <pkg>)
+	$(call print-help,<pkg>-reconfigure,Restart the build from the configure step)
+	$(call print-help,<pkg>-rebuild,Restart the build from the build step)
 	$(foreach p,$(HELP_PACKAGES), \
 		@echo $(sep) \
 		@echo '$($(p)_NAME):' $(sep) \
 		$($(p)_HELP_CMDS)$(sep))
 	@echo
 	@echo 'Documentation:'
-	@echo '  manual                 - build manual in all formats'
-	@echo '  manual-html            - build manual in HTML'
-	@echo '  manual-split-html      - build manual in split HTML'
-	@echo '  manual-pdf             - build manual in PDF'
-	@echo '  manual-text            - build manual in text'
-	@echo '  manual-epub            - build manual in ePub'
-	@echo '  graph-build            - generate graphs of the build times'
-	@echo '  graph-depends          - generate graph of the dependency tree'
-	@echo '  graph-size             - generate stats of the filesystem size'
-	@echo '  list-defconfigs        - list all defconfigs (pre-configured minimal systems)'
+	$(call print-help,manual,Build manual in all formats)
+	$(call print-help,manual-html,Build manual in HTML)
+	$(call print-help,manual-split-html,Build manual in split HTML)
+	$(call print-help,manual-pdf,Build manual in PDF)
+	$(call print-help,manual-text,Build manual in text)
+	$(call print-help,manual-epub,Build manual in ePub)
+	$(call print-help,graph-build,Generate graphs of the build times)
+	$(call print-help,graph-depends,Generate graph of the dependency tree)
+	$(call print-help,graph-size,Generate stats of the filesystem size)
+	$(call print-help,list-defconfigs, \
+		List all defconfigs (pre-configured minimal systems))
 	@echo
 	@echo 'Miscellaneous:'
-	@echo '  source                 - download all sources needed for offline-build'
-	@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'
+	$(call print-help,source, \
+		Download all sources needed for offline-build)
+	$(call print-help,source-check, \
+		Check selected packages for valid download URLs)
+	$(call print-help,external-deps,List external packages used)
+	$(call print-help,legal-info,Generate info about license compliance)
 	@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'
+	$(call print-help,make V=0|1, \
+		0 => quiet build (default); 1 => verbose build)
+	$(call print-help,make O=dir, \
+		Locate all output files in 'dir' (including .config))
 	@echo
 	@echo 'For further details, see README, generate the Buildroot manual, or consult'
 	@echo 'it on-line at http://buildroot.org/docs.html'
-- 
2.7.4

[Buildroot] [PATCH 0/8 v3] core: add support for package help (branch yem/help)

[Thomas Petazzoni]

Hello,

On Sat,  4 Jun 2016 18:30:49 +0200, Yann E. MORIN wrote:

> Yann E. MORIN (8):
>       core/pkg-generic: add support for package-defined help
>       core: name the package before its help text
>       core/pkg-utils: add a macro to pretty-print a help entry
>       package/busybox: use the generic help rules
>       linux: use the generic help rules
>       package/uclibc: use the generic help rules
>       boot/barebox: use the generic help rules
>       core: use the print-help macro to print the main help

This last commit made me realize that the helper is a bad idea:

 1/ It makes the code longer in number of lines.

 2/ It makes it harder to read.

So, as discussed on IRC, I've reworked your patches to drop the helper
that pretty-print the help text, and simply used the @echo calls in the
various packages.

So essentially, I've dropped patches 3/8 and 8/8, and I've reworked
patches 4, 5, 6 and 7 to not use the helper.

Thanks a lot!

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

[Buildroot] [PATCH 0/8 v3] core: add support for package help (branch yem/help)

[Yann E. MORIN]

Thomas, All,

On 2016-06-07 22:18 +0200, Thomas Petazzoni spake thusly:
> On Sat,  4 Jun 2016 18:30:49 +0200, Yann E. MORIN wrote:
> > Yann E. MORIN (8):
> >       core/pkg-generic: add support for package-defined help
> >       core: name the package before its help text
> >       core/pkg-utils: add a macro to pretty-print a help entry
> >       package/busybox: use the generic help rules
> >       linux: use the generic help rules
> >       package/uclibc: use the generic help rules
> >       boot/barebox: use the generic help rules
> >       core: use the print-help macro to print the main help
> 
> This last commit made me realize that the helper is a bad idea:
> 
>  1/ It makes the code longer in number of lines.
> 
>  2/ It makes it harder to read.
> 
> So, as discussed on IRC, I've reworked your patches to drop the helper
> that pretty-print the help text, and simply used the @echo calls in the
> various packages.
> 
> So essentially, I've dropped patches 3/8 and 8/8, and I've reworked
> patches 4, 5, 6 and 7 to not use the helper.

Thanks! :-)

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.  |
'------------------------------^-------^------------------^--------------------'