core: allow for custom, local help; rearrange package-specific help (branch yem/help)
v2 cover core: allow for custom, local help; rearrange package-specific help (branch yem/help)
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(-)
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | 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. | '------------------------------^-------^------------------^--------------------'
PATCH v2 1/9 core: add the possibility to provide help for custom rules
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.
---
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(+)
Makefile +7 -0
@@ -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))), \
docs/manual/customize-outside-br.txt +14 -0
@@ -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.' +------
Signature · 1 line
1.9.1
PATCH v2 1/9 core: add the possibility to provide help for custom rules
Hello,
Quoted 13 lines · Yann E. MORIN
Makefile +1
-0@@ -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'
Makefile endif · line 983
Quoted 9 lines
Makefile +6
-0@@ -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
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
PATCH v2 1/9 core: add the possibility to provide help for custom rules
Thomas, All,
On 2016-03-19 19:05 +0100, Thomas Petazzoni spake thusly:
Quoted 39 lines · Yann E. MORIN
Quoted 14 lines
Makefile +1
-0@@ -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'Makefile endif · line 983
Quoted 9 lines
Makefile +6
-0@@ -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, becauseBR2_EXTERNAL_FILEgets included outside of theBR2_HAVE_DOT_CONFIGcondition. But still:thomas at skate:~/projets/buildroot (master)$ cat
/tmp/external/external.mkhelp-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:
Quoted 7 lines
thomas at skate:~/projets/buildroot (master)$ make defconfig
[...]
thomas at skate:~/projets/buildroot (master)$ make BR2_EXTERNAL=/tmp/external help-custom TESTThis 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.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | 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. | '------------------------------^-------^------------------^--------------------'
PATCH v2 2/9 core: also display the custom help with our main help
In reply to Yann E. MORINThe patch merges the custom help, introduced in the previous patch, at the end of our internal help.
---
Changes v1 -> v2:
- new patch, by popular demand... :-/
--- Makefile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Makefile +3 -2
@@ -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'
Signature · 1 line
1.9.1
PATCH v2 3/9 core/pkg-utils: add a macro to pretty-print a help entry
In reply to Yann E. MORINTo 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.
---
Changes v1 -> v2:
- properly format multi-line output
--- package/pkg-utils.mk | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)
package/pkg-utils.mk +22 -0
@@ -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))
Signature · 1 line
1.9.1
PATCH v2 4/9 docs/manual: print-help can be used in help-custom
In reply to Yann E. MORIN... but make it explicit that it is not mandatory.
---
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(-)
docs/manual/customize-outside-br.txt +15 -3
@@ -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[].
Signature · 1 line
1.9.1
PATCH v2 5/9 core/pkg-generic: add help about package-specific rules
In reply to Yann E. MORINAdd 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).
--- Makefile | 1 + docs/manual/adding-packages-generic.txt | 6 ++++++ package/pkg-generic.mk | 2 ++ 3 files changed, 9 insertions(+)
Makefile +1 -0
@@ -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
docs/manual/adding-packages-generic.txt +6 -0
@@ -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:
package/pkg-generic.mk +2 -0
@@ -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
Signature · 1 line
1.9.1
PATCH v2 6/9 package/busybox: use the generic help rules
In reply to Yann E. MORIN--- Makefile | 3 --- package/busybox/busybox.mk | 2 ++ 2 files changed, 2 insertions(+), 3 deletions(-)
Makefile +0 -3
@@ -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'
package/busybox/busybox.mk +2 -0
@@ -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)
Signature · 1 line
1.9.1
PATCH v2 7/9 linux: add the generic help rules
In reply to Yann E. MORIN--- Makefile | 6 ------ linux/linux.mk | 6 ++++++ 2 files changed, 6 insertions(+), 6 deletions(-)
Makefile +0 -6
@@ -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
linux/linux.mk +6 -0
@@ -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))
Signature · 1 line
1.9.1
PATCH v2 8/9 package/uclibc: use the generic help rules
In reply to Yann E. MORINNote 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.
--- Makefile | 3 --- package/uclibc/uclibc.mk | 2 ++ 2 files changed, 2 insertions(+), 3 deletions(-)
Makefile +0 -3
@@ -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'
package/uclibc/uclibc.mk +2 -0
@@ -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
Signature · 1 line
1.9.1
PATCH v2 9/9 boot/barebox: use the generic help rules
In reply to Yann E. MORIN--- Makefile | 4 ---- boot/barebox/barebox.mk | 4 ++++ 2 files changed, 4 insertions(+), 4 deletions(-)
Makefile +0 -4
@@ -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'
boot/barebox/barebox.mk +4 -0
@@ -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))
Signature · 1 line
1.9.1