[Buildroot] [PATCH 0/4] 'make help' and README update

[Buildroot] [PATCH 0/4] 'make help' and README update

[Arnout Vandecappelle]

 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(-)

[Buildroot] [PATCH 1/4] Makefile: declare 'help' target as phony.

[Arnout Vandecappelle]

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 33a89b1..de2abfe 100644
--- a/Makefile
+++ b/Makefile
@@ -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) \
-- 
2.1.4

[Buildroot] [PATCH 1/4] Makefile: declare 'help' target as phony.

[Thomas Petazzoni]

Dear Arnout Vandecappelle (Essensium/Mind),

On Sat, 21 Mar 2015 20:49:45 +0100, Arnout Vandecappelle
(Essensium/Mind) wrote:
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  Makefile | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied, thanks.

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

[Buildroot] [PATCH 2/4] Makefile: split off 'list-defconfigs' from 'help'

[Arnout Vandecappelle]

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.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 Makefile                             | 10 ++++++----
 docs/manual/customize-outside-br.txt |  6 +++---
 docs/manual/make-tips.txt            |  6 ++++++
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/Makefile b/Makefile
index de2abfe..ea08e6a 100644
--- a/Makefile
+++ b/Makefile
@@ -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)
 
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
index 5d63e60..aac9a43 100644
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -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.
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index 027eddf..1cf1544 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -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:
 
 --------------------
-- 
2.1.4

[Buildroot] [PATCH 2/4] Makefile: split off 'list-defconfigs' from 'help'

[Thomas Petazzoni]

Dear Arnout Vandecappelle (Essensium/Mind),

On Sat, 21 Mar 2015 20:49:46 +0100, Arnout Vandecappelle
(Essensium/Mind) wrote:
> 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.
> 
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  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
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 3/4] Makefile: help: add package-specific targets

[Arnout Vandecappelle]

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

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
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.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 Makefile | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Makefile b/Makefile
index ea08e6a..50fb5cf 100644
--- a/Makefile
+++ b/Makefile
@@ -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
-- 
2.1.4

[Buildroot] [PATCH 3/4] Makefile: help: add package-specific targets

[Thomas Petazzoni]

Dear Arnout Vandecappelle (Essensium/Mind),

On Sat, 21 Mar 2015 20:49:47 +0100, Arnout Vandecappelle
(Essensium/Mind) wrote:

> +	@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.

> +	@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
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 4/4] README: reduce it to a single page and refer to other documentation

[Arnout Vandecappelle]

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.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 README | 59 ++++++++++-------------------------------------------------
 1 file changed, 10 insertions(+), 49 deletions(-)

diff --git a/README b/README
index 944347d..a7dae24 100644
--- a/README
+++ b/README
@@ -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.
-- 
2.1.4

[Buildroot] [PATCH] README: mention 'make list-defconfigs'

[Arnout Vandecappelle]

'make list-defconfigs' is probably one of the more useful things
to get started quickly.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 README | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README b/README
index a7dae24..e863f0e 100644
--- a/README
+++ b/README
@@ -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.
-- 
2.1.4

[Buildroot] [PATCH] README: mention 'make list-defconfigs'

[Thomas Petazzoni]

Dear Arnout Vandecappelle (Essensium/Mind),

On Sat, 21 Mar 2015 20:57:13 +0100, Arnout Vandecappelle
(Essensium/Mind) wrote:
> 'make list-defconfigs' is probably one of the more useful things
> to get started quickly.
> 
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  README | 3 +++
>  1 file changed, 3 insertions(+)

Applied, thanks.

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

[Buildroot] [PATCH 4/4] README: reduce it to a single page and refer to other documentation

[Thomas Petazzoni]

Dear Arnout Vandecappelle (Essensium/Mind),

On Sat, 21 Mar 2015 20:49:48 +0100, Arnout Vandecappelle
(Essensium/Mind) wrote:
> 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.
> 
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  README | 59 ++++++++++-------------------------------------------------
>  1 file changed, 10 insertions(+), 49 deletions(-)

Applied, thanks.

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