'make help' and README update
cover 'make help' and README update
On the BR developer meeting at FOSDEM two months ago I was volunteered
to update the 'make help' output and the README according to the conclusions of the meeting:
* Keep one big 'make help', no 'make foo-help'. Order the output in a more logical way.
* Create a new 'make list-defconfigs' to reduce the output of 'make help'. Add a FAQ entry that refers to this.
* The README should be rewritten so it is small and refers to other documentation.
Now, I've finally gotten around to do this...
There is one potential change I haven't included here: Thomas had also
added documentation for the ccache-specific targets in 'make help'. Perhaps that still makes sense? Note however that the help text without linux-menuconfig and friends is already 63 lines long, that's almost 3 pages on some terminals...
Regards,
Arnout
----------------------------------------------------------------
Arnout Vandecappelle (Essensium/Mind) (4):
Makefile: declare 'help' target as phony.
Makefile: split off 'list-defconfigs' from 'help'
Makefile: help: add package-specific targets
README: reduce it to a single page and refer to other documentation
Makefile | 27 ++++++++++++++++++++++----- README | 59 ++++++++++------------------------------------------------- docs/manual/customize-outside-br.txt | 6 +++--- docs/manual/make-tips.txt | 6 ++++++ 4 files changed, 41 insertions(+), 57 deletions(-)
PATCH 1/4 Makefile: declare 'help' target as phony.
--- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Makefile +1 -1
@@ -433,7 +433,7 @@ prepare: $(BUILD_DIR)/buildroot-config/auto.conf world: target-post-image .PHONY: all world toolchain dirs clean distclean source outputmakefile \ - legal-info legal-info-prepare legal-info-clean printvars \ + legal-info legal-info-prepare legal-info-clean printvars help \ target-finalize target-post-image \ $(TARGETS) $(TARGETS_ROOTFS) \ $(TARGETS_DIRCLEAN) $(TARGETS_SOURCE) $(TARGETS_LEGAL_INFO) \
Signature · 1 line
2.1.4
Thomas Petazzoni
AppliedPATCH 1/4 Makefile: declare 'help' target as phony.
Dear Arnout Vandecappelle (Essensium/Mind),
Quoted 4 lines · Arnout Vandecappelle (Essensium/Mind)
--- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Applied, thanks.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
PATCH 2/4 Makefile: split off 'list-defconfigs' from 'help'
In reply to Arnout Vandecappelle (Essensium/Mind)As discussed in the FOSDEM2015 BR developer meeting, the output of 'make help' is too long for comfortable reading. To shorten it, split off the list of defconfigs in a new target, 'list-defconfigs'.
Declare the new target as phony.
Add 'list-defconfigs' to the documentation.
--- Makefile | 10 ++++++---- docs/manual/customize-outside-br.txt | 6 +++--- docs/manual/make-tips.txt | 6 ++++++ 3 files changed, 15 insertions(+), 7 deletions(-)
Makefile +6 -4
@@ -434,7 +434,7 @@ world: target-post-image .PHONY: all world toolchain dirs clean distclean source outputmakefile \ legal-info legal-info-prepare legal-info-clean printvars help \ - target-finalize target-post-image \ + list-defconfigs target-finalize target-post-image \ $(TARGETS) $(TARGETS_ROOTFS) \ $(TARGETS_DIRCLEAN) $(TARGETS_SOURCE) $(TARGETS_LEGAL_INFO) \ $(BUILD_DIR) $(STAGING_DIR) $(TARGET_DIR) \
@@ -905,6 +905,11 @@ endif @echo ' make V=0|1 - 0 => quiet build (default), 1 => verbose build' @echo ' 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' + @echo + +list-defconfigs: @echo 'Built-in configs:' @$(foreach b, $(sort $(notdir $(wildcard $(TOPDIR)/configs/*_defconfig))), \ printf " %-35s - Build for %s\\n" $(b) $(b:_defconfig=);)
@@ -915,9 +920,6 @@ ifneq ($(wildcard $(BR2_EXTERNAL)/configs/*_defconfig),) printf " %-35s - Build for %s\\n" $(b) $(b:_defconfig=);) endif @echo - @echo 'For further details, see README, generate the Buildroot manual, or consult' - @echo 'it on-line at http://buildroot.org/docs.html' - @echo release: OUT = buildroot-$(BR2_VERSION)
docs/manual/customize-outside-br.txt +3 -3
@@ -100,6 +100,6 @@ And then in +$(BR2_EXTERNAL)/package/package1+ and * One can store Buildroot defconfigs in the +configs+ subdirectory of +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the - output of +make help+ 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 help' output. + 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.
docs/manual/make-tips.txt +6 -0
@@ -12,6 +12,12 @@ This is a collection of tips that help you make the most of Buildroot. $ make V=1 <target> -------------------- +.Display the list of boards with a defconfig: + +-------------------- + $ make list-defconfigs +-------------------- + .Display all available targets: --------------------
Signature · 1 line
2.1.4
Thomas Petazzoni
AppliedPATCH 2/4 Makefile: split off 'list-defconfigs' from 'help'
Dear Arnout Vandecappelle (Essensium/Mind),
Quoted 6 lines · Arnout Vandecappelle (Essensium/Mind)
As discussed in the FOSDEM2015 BR developer meeting, the output of 'make help' is too long for comfortable reading. To shorten it, split off the list of defconfigs in a new target, 'list-defconfigs'.
Declare the new target as phony.
Quoted 8 lines
Add 'list-defconfigs' to the documentation.
--- Makefile | 10 ++++++---- docs/manual/customize-outside-br.txt | 6 +++--- docs/manual/make-tips.txt | 6 ++++++ 3 files changed, 15 insertions(+), 7 deletions(-)
Applied, thanks. Should the 'make help' text be extended to mention 'list-defconfigs' ?
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
PATCH 3/4 Makefile: help: add package-specific targets
In reply to Arnout Vandecappelle (Essensium/Mind)The documentation of the package-specific targets is heavily inspired by the earlier patch by Thomas Petazzoni [1], but the <pkg>-install* targets were left out since they're not useful for the developer IMHO.
The *-menuconfig target's help text is moved to the package-specific targets.
[1] http://patchwork.ozlabs.org/patch/433692
---
I wasn't sure about putting a condition on BR2_HAVE_DOT_CONFIG around the package-specific targets. Obviously they only make sense when you do have a configuration, but I don't see why we would change the help text based on that.
--- Makefile | 15 +++++++++++++++ 1 file changed, 15 insertions(+)
Makefile +15 -0
@@ -871,6 +871,21 @@ help: @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' + @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 - Display <pkg>'\''s dependencies' + @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' + @echo ' <pkg>-legal-info - Generate license information for <pkg>' ifeq ($(BR2_PACKAGE_BUSYBOX),y) @echo ' busybox-menuconfig - Run BusyBox menuconfig' endif
Signature · 1 line
2.1.4
PATCH 3/4 Makefile: help: add package-specific targets
Dear Arnout Vandecappelle (Essensium/Mind),
Makefile help: · line 884
Quoted 11 lines · Arnout Vandecappelle (Essensium/Mind)
Makefile +11
-0+ @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 - Display <pkg>'\''s dependencies' + @echo ' <pkg>-graph-depends - Generate a graph of <pkg>'\''s dependencies'
Why <pkg>-graph-depends two times? I've kept only the second occurrence.
Makefile help: · line 887
Quoted 3 lines
Makefile +3
-0+ @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'
Do you think it would make sense to add <pkg>-reinstall here?
Applied with the <pkg>-graph-depends thing fixed.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
PATCH 4/4 README: reduce it to a single page and refer to other documentation
In reply to Arnout Vandecappelle (Essensium/Mind)As discussed on the BR developer meeting at FOSDEM, the README should be very short and instead refer to other documentation: the manual, the website, the mailing list, the IRC channel.
--- README | 59 ++++++++++------------------------------------------------- 1 file changed, 10 insertions(+), 49 deletions(-)
README +10 -49
@@ -1,59 +1,20 @@ +Buildroot is a simple, efficient and easy-to-use tool to generate embedded +Linux systems through cross-compilation. + +The documentation can be found in docs/manual. You can generate a text +document with 'make manual-text' and read output/docs/manual/manual.text. +Online documentation can be found at http://buildroot.org/docs.html + To build and use the buildroot stuff, do the following: 1) run 'make menuconfig' -2) select the packages you wish to compile +2) select the target architecture and the packages you wish to compile 3) run 'make' 4) wait while it compiles -5) Use your shiny new root filesystem. Depending on which sort of - root filesystem you selected, you may want to loop mount it, - chroot into it, nfs mount it on your target device, burn it - to flash, or whatever is appropriate for your target system. +5) find the kernel, bootloader, root filesystem, etc. in output/images You do not need to be root to build or run buildroot. Have fun! -Offline build: -============== - -In order to do an offline-build (not connected to the net), fetch all -selected source by issuing a -$ make source - -before you disconnect. -If your build-host is never connected, then you have to copy buildroot -and your toplevel .config to a machine that has an internet-connection -and issue "make source" there, then copy the content of your dl/ dir to -the build-host. - -Building out-of-tree: -===================== - -Buildroot supports building out of tree with a syntax similar -to the Linux kernel. To use it, add O=<directory> to the -make command line, E.G.: - -$ make O=/tmp/build - -And all the output files (including .config) will be located under /tmp/build. - -More finegrained configuration: -=============================== - -You can specify a config-file for uClibc: -$ make UCLIBC_CONFIG_FILE=/my/uClibc.config - -And you can specify a config-file for busybox: -$ make BUSYBOX_CONFIG_FILE=/my/busybox.config - -To use a non-standard host-compiler (if you do not have 'gcc'), -make sure that the compiler is in your PATH and that the library paths are -setup properly, if your compiler is built dynamically: -$ make HOSTCC=gcc-4.3.orig HOSTCXX=gcc-4.3-mine - -Depending on your configuration, there are some targets you can use to -use menuconfig of certain packages. This includes: -$ make HOSTCC=gcc-4.3 linux-menuconfig -$ make HOSTCC=gcc-4.3 uclibc-menuconfig -$ make HOSTCC=gcc-4.3 busybox-menuconfig - Please feed suggestions, bug reports, insults, and bribes back to the buildroot mailing list: buildroot at buildroot.org +You can also find us on #buildroot on Freenode IRC.
Signature · 1 line
2.1.4
PATCH 1/1 README: mention 'make list-defconfigs'
'make list-defconfigs' is probably one of the more useful things to get started quickly.
--- README | 3 +++ 1 file changed, 3 insertions(+)
README +3 -0
@@ -15,6 +15,9 @@ To build and use the buildroot stuff, do the following: You do not need to be root to build or run buildroot. Have fun! +Buildroot comes with a basic configuration for a number of boards. Run +'make list-defconfigs' to view the list of provided configurations. + Please feed suggestions, bug reports, insults, and bribes back to the buildroot mailing list: buildroot at buildroot.org You can also find us on #buildroot on Freenode IRC.
Signature · 1 line
2.1.4
Thomas Petazzoni
AppliedPATCH 1/1 README: mention 'make list-defconfigs'
Dear Arnout Vandecappelle (Essensium/Mind),
Quoted 7 lines · Arnout Vandecappelle (Essensium/Mind)
'make list-defconfigs' is probably one of the more useful things to get started quickly.
--- README | 3 +++ 1 file changed, 3 insertions(+)
Applied, thanks.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
Thomas Petazzoni
AppliedPATCH 4/4 README: reduce it to a single page and refer to other documentation
In reply to Arnout Vandecappelle (Essensium/Mind)Dear Arnout Vandecappelle (Essensium/Mind),
Quoted 8 lines · Arnout Vandecappelle (Essensium/Mind)
As discussed on the BR developer meeting at FOSDEM, the README should be very short and instead refer to other documentation: the manual, the website, the mailing list, the IRC channel.
--- README | 59 ++++++++++------------------------------------------------- 1 file changed, 10 insertions(+), 49 deletions(-)
Applied, thanks.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com