[Buildroot] [PATCH 1/9 v2] core: add the possibility to provide help for custom rules

[Buildroot] [PATCH 1/9 v2] core: add the possibility to provide help for 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-custom, advertised in our own help info.

It is up to the br2-external tree to provide whatever help text is
deemed necessary. The format of the help is completely free-form.

Note that we need to provide an empty, dummy help-custom rule, since it
is always advertised (making it .PHONY does not work). 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>

---
Changes v1 -> v2:
  - rename the target  (Arnout)
  - document that new rule in the manual (instead of in its own cset)
  - improve the example in the manual to make it clear that this new
    target is *totally* free-form and that nothing is mandatory
---
 Makefile                             |  7 +++++++
 docs/manual/customize-outside-br.txt | 14 ++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/Makefile b/Makefile
index 98c8dc7..7bb5f6d 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-custom            - print help about 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,12 @@ 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. Making the rule
+# .PHONY does not work.
+help-custom:
+
 list-defconfigs:
 	@echo 'Built-in configs:'
 	@$(foreach b, $(sort $(notdir $(wildcard $(TOPDIR)/configs/*_defconfig))), \
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index 9ad177d..be1827e 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -107,3 +107,17 @@ 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-custom+ make
+rule, to document custom make targets specific to this +BR2_EXTERNAL+
+tree. The help is completely free-form.
+
+------
+help-custom:
+    @echo 'Here goes your local help, where you may'
+    @echo 'describe some custom rules:'
+    @echo '  my-rule       - do something'
+    @echo '  my-other-rule - do something else'
+    @echo
+    @echo 'Please contact support at company.com in case of problem.'
+------
-- 
1.9.1

[Buildroot] [PATCH 2/9 v2] core: also display the custom help with our main help

[Yann E. MORIN]

The patch merges the custom help, introduced in the previous patch, at
the end of our internal help.

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>

---
Changes v1 -> v2:
  - new patch, by popular demand... :-/
---
 Makefile | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 7bb5f6d..ea8b1e4 100644
--- a/Makefile
+++ b/Makefile
@@ -893,7 +893,9 @@ endif
 	rm -rf $(BR2_CONFIG) $(CONFIG_DIR)/.config.old $(CONFIG_DIR)/..config.tmp \
 		$(CONFIG_DIR)/.auto.deps $(BR2_EXTERNAL_FILE)
 
-help:
+help: help-internal help-custom
+
+help-internal:
 	@echo 'Cleaning:'
 	@echo '  clean                  - delete all files created by build'
 	@echo '  distclean              - delete all non-source files (including .config)'
@@ -966,7 +968,6 @@ 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-custom            - print help about 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'
-- 
1.9.1

[Buildroot] [PATCH 0/9 v2] 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
help, most probably from a br2-external tree (or from a local.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" (although this is mostly a
technical limitation/artifact), we do similarly for the custom help,
albeit with a slight shorter moniker, 'help-custom'.

The first two patches implement this new make target, the first by
adding it as a purely separate and new target, the scond by making it
appended after out internal help.

Third patch adds a new helper make function, that can be used to
pretty-print the package-specific help. This macro is added to to the
manual, as an *example* of what the custom help could use.

The 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 themselves, to clean up
the main help code (the entries are still displayed there, they are just
defined in each concerned package).

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


Additional notes:

  - only the first two patches are what is required to get custom help.
    The followup patches only address the other part of J?r?me's patch,
    which is about moving patckage-specifi help to the concerned
    packages;

  - the new custom help is not intermixed with our internal help; rather
    it is appended to it;

  - indeed, this macro does not allow packages to expose arbitrary help.
    It does not however prevent packages from documenting arbitrary
    rules. If a package wants to provide arbitrary help, then it would
    probably do in its .mk file something like:
        LIBFOO_HELP = "libfoo-help : print help for libfoo"
        libfoo-help:
            @cat my-biggish-help-file



Changes v1 -> v2:
  - rename the custom help make target
  - make it explicit that it is *absolutely* free-form
  - better document it in the manual
  - print custom help after our internal help
  - properly pretty-print on multi lines

(Sorry, I haven't carried Arnout's reviews so far...)

Regards,
Yann E. MORIN.


The following changes since commit 0b7b84310c3781c346eea4c114c8cb4e97bbd8ea:

  olimex_imx233_olinuxino_defconfig: genimage support (2016-03-11 13:14:54 +0100)

are available in the git repository at:

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

for you to fetch changes up to b508f49279beea5e3f1b823408aa12ad7d9a35f9:

  boot/barebox: use the generic help rules (2016-03-11 18:20:45 +0100)

----------------------------------------------------------------
Yann E. MORIN (9):
      core: add the possibility to provide help for custom rules
      core: also display the custom help with our main help
      core/pkg-utils: add a macro to pretty-print a help entry
      docs/manual: print-help can be used in help-custom
      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

 Makefile                                | 27 ++++++++++-----------------
 boot/barebox/barebox.mk                 |  4 ++++
 docs/manual/adding-packages-generic.txt |  6 ++++++
 docs/manual/customize-outside-br.txt    | 26 ++++++++++++++++++++++++++
 linux/linux.mk                          |  6 ++++++
 package/busybox/busybox.mk              |  2 ++
 package/pkg-generic.mk                  |  2 ++
 package/pkg-utils.mk                    | 22 ++++++++++++++++++++++
 package/uclibc/uclibc.mk                |  2 ++
 9 files changed, 80 insertions(+), 17 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/9 v2] 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>

---
Changes v1 -> v2:
  - properly format multi-line output
---
 package/pkg-utils.mk | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/package/pkg-utils.mk b/package/pkg-utils.mk
index f88313a..e9219d8 100644
--- a/package/pkg-utils.mk
+++ b/package/pkg-utils.mk
@@ -104,6 +104,28 @@ 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.
+#
+# The output is a 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
+#
+# (The long spaces are 27 chars.)
+define print-help
+	for h in $(1); do \
+		printf "  %-22s - " "$${h%% : *}"; \
+		printf "%s\n" "$${h#* : }" \
+		|fmt -w52 -u \
+		|sed '2,$$s/^/                           /;'; \
+	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 4/9 v2] docs/manual: print-help can be used in help-custom

[Yann E. MORIN]

... but make it explicit that it is not mandatory.

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>

---
Changes v1 -> v2:
  - move that patch earlier in the series
  - make it explicit that print-help is *not* mandatory for the
    custom help
---
 docs/manual/customize-outside-br.txt | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index be1827e..88fc802 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -110,14 +110,26 @@ And then in +$(BR2_EXTERNAL)/package/package1+ and
 
 Additionally, an +external.mk+ file may define the +help-custom+ make
 rule, to document custom make targets specific to this +BR2_EXTERNAL+
-tree. The help is completely free-form.
+tree. The help is completely free-form. Buildroot however provides the
++print-help+ macro to pretty-print those additional rules, even though
+it is absolutely not mandatory to use it:
 
 ------
+BR2_EXTERNAL_HELP = \
+    "my-rule : some help text for my-rule" \
+    "my-other-rule : some help text for my-other-rule"
+
 help-custom:
     @echo 'Here goes your local help, where you may'
     @echo 'describe some custom rules:'
-    @echo '  my-rule       - do something'
-    @echo '  my-other-rule - do something else'
+    @$(call print-help,$(BR2_EXTERNAL_HELP))
+    @echo
+    @echo 'Another section with more custom help:'
+    @echo '  third-rule  - some help text'
+    @echo '  fourth-rule - even more help text'
     @echo
     @echo 'Please contact support at company.com in case of problem.'
 ------
+
+The format for +BR2_EXTERNAL_HELP+ is the same as for the +LIBFOO_HELP+
+package variable, defined in xref:generic-package-tutorial[].
-- 
1.9.1

[Buildroot] [PATCH 5/9 v2] 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 ea8b1e4..fd953b2 100644
--- a/Makefile
+++ b/Makefile
@@ -934,6 +934,7 @@ help-internal:
 	@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,$(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..0e36ffa 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 6/9 v2] 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 fd953b2..43fa20e 100644
--- a/Makefile
+++ b/Makefile
@@ -935,9 +935,6 @@ help-internal:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call print-help,$(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 7/9 v2] 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 43fa20e..ca7a02e 100644
--- a/Makefile
+++ b/Makefile
@@ -935,12 +935,6 @@ help-internal:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call print-help,$(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 8/9 v2] 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 ca7a02e..c0f8701 100644
--- a/Makefile
+++ b/Makefile
@@ -935,9 +935,6 @@ help-internal:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call print-help,$(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 9/9 v2] 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 c0f8701..5f46296 100644
--- a/Makefile
+++ b/Makefile
@@ -935,10 +935,6 @@ help-internal:
 	@echo '  <pkg>-reconfigure      - Restart the build from the configure step'
 	@echo '  <pkg>-rebuild          - Restart the build from the build step'
 	@$(call print-help,$(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 1/9 v2] core: add the possibility to provide help for custom rules

[Thomas Petazzoni]

Hello,

On Fri, 11 Mar 2016 18:41:09 +0100, Yann E. MORIN wrote:

> diff --git a/Makefile b/Makefile
> index 98c8dc7..7bb5f6d 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-custom            - print help about 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,12 @@ 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. Making the rule
> +# .PHONY does not work.
> +help-custom:
> +

There is a pretty important problem with this implementation (which
gets even worse when PATCH 2 is applied), but I am not sure why it
happens: the custom help is not taken into account if you don't have a
configuration file defined. This is weird, because BR2_EXTERNAL_FILE
gets included outside of the BR2_HAVE_DOT_CONFIG condition. But still:

thomas at skate:~/projets/buildroot (master)$ cat /tmp/external/external.mk 
help-custom:
	@echo TEST
thomas at skate:~/projets/buildroot (master)$ make BR2_EXTERNAL=/tmp/external help-custom
make[1]: Nothing to be done for 'help-custom'.

And then, if I create a .config file:

thomas at skate:~/projets/buildroot (master)$ make defconfig
[...]
thomas at skate:~/projets/buildroot (master)$ make BR2_EXTERNAL=/tmp/external help-custom
TEST

This is not expected, since the help text is supposed to be available
even when no configuration has been defined.

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

[Buildroot] [PATCH 1/9 v2] core: add the possibility to provide help for custom rules

[Yann E. MORIN]

Thomas, All,

On 2016-03-19 19:05 +0100, Thomas Petazzoni spake thusly:
> On Fri, 11 Mar 2016 18:41:09 +0100, Yann E. MORIN wrote:
> 
> > diff --git a/Makefile b/Makefile
> > index 98c8dc7..7bb5f6d 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-custom            - print help about 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,12 @@ 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. Making the rule
> > +# .PHONY does not work.
> > +help-custom:
> > +
> 
> There is a pretty important problem with this implementation (which
> gets even worse when PATCH 2 is applied), but I am not sure why it
> happens: the custom help is not taken into account if you don't have a
> configuration file defined. This is weird, because BR2_EXTERNAL_FILE
> gets included outside of the BR2_HAVE_DOT_CONFIG condition. But still:
> 
> thomas at skate:~/projets/buildroot (master)$ cat /tmp/external/external.mk 
> help-custom:
> 	@echo TEST
> thomas at skate:~/projets/buildroot (master)$ make BR2_EXTERNAL=/tmp/external help-custom
> make[1]: Nothing to be done for 'help-custom'.
> 
> And then, if I create a .config file:
> 
> thomas at skate:~/projets/buildroot (master)$ make defconfig
> [...]
> thomas at skate:~/projets/buildroot (master)$ make BR2_EXTERNAL=/tmp/external help-custom
> TEST
> 
> This is not expected, since the help text is supposed to be available
> even when no configuration has been defined.

Indeed, that's bad.

However, the proposal by J?r?me has exactly the same problem.

I'll look at it. 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.  |
'------------------------------^-------^------------------^--------------------'