[PATCH 0/3] make help

[PATCH 0/3] make help

[Thomas Monjalon]

Let's add help for building DPDK.

---

Thomas Monjalon (3):
  mk: rule showconfigs for configs listing
  doc: how to build
  mk: rule help

 doc/build-sdk-quick.txt |   22 ++++++++++++++++++++++
 mk/rte.sdkconfig.mk     |    4 ++++
 mk/rte.sdkdoc.mk        |    8 ++++++++
 mk/rte.sdkroot.mk       |    7 ++++---
 4 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 doc/build-sdk-quick.txt

[PATCH 1/3] mk: rule showconfigs for configs listing

[Thomas Monjalon]

Allow to list configs in config/ directory with a simple make rule.

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 mk/rte.sdkconfig.mk |    4 ++++
 mk/rte.sdkroot.mk   |    4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/mk/rte.sdkconfig.mk b/mk/rte.sdkconfig.mk
index ed81c47..179089e 100644
--- a/mk/rte.sdkconfig.mk
+++ b/mk/rte.sdkconfig.mk
@@ -36,6 +36,10 @@ INSTALL_CONFIGS := $(filter-out %~,\
 	$(wildcard $(RTE_SRCDIR)/config/defconfig_*)))
 INSTALL_TARGETS := $(addsuffix _install,$(INSTALL_CONFIGS))
 
+.PHONY: showconfigs
+showconfigs:
+	@$(foreach CONFIG, $(INSTALL_CONFIGS), echo $(CONFIG);)
+
 .PHONY: config
 ifeq ($(RTE_CONFIG_TEMPLATE),)
 config:
diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
index f555e33..6bbbd54 100644
--- a/mk/rte.sdkroot.mk
+++ b/mk/rte.sdkroot.mk
@@ -87,8 +87,8 @@ export ROOTDIRS-y ROOTDIRS- ROOTDIRS-n
 .PHONY: default
 default: all
 
-.PHONY: config
-config:
+.PHONY: config showconfigs
+config showconfigs:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk $@
 
 .PHONY: test fast_test ring_test mempool_test
-- 
1.7.10.4

[PATCH 2/3] doc: how to build

[Thomas Monjalon]

This is a cheat sheet to build DPDK and can be used for a "make help".
It is explicitly described as a build help in order to concatenate it
with other helps such as test commands.

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 doc/build-sdk-quick.txt |   22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 doc/build-sdk-quick.txt

diff --git a/doc/build-sdk-quick.txt b/doc/build-sdk-quick.txt
new file mode 100644
index 0000000..3f88522
--- /dev/null
+++ b/doc/build-sdk-quick.txt
@@ -0,0 +1,22 @@
+Basic build
+	make config T=x86_64-default-linuxapp-gcc && make
+Build commands
+	config      get configuration from target template (T=)
+	all         same as build (default rule)
+	build       build in a configured directory
+	clean       remove files but keep configuration
+	install     build many targets (wildcard allowed) in fixed directories
+	uninstall   remove all installed targets
+Build options
+	T   target template (install default: *) - used with config or install
+	O   output directory (default: build/)   - cannot be used with install
+	V   verbose
+	D   debug dependencies
+	CROSS            toolchain prefix
+	EXTRA_CPPFLAGS   preprocessor options
+	EXTRA_CFLAGS     compiler options
+	EXTRA_LDFLAGS    linker options
+Build targets
+	format: <arch-machine-execenv-toolchain>
+	templates in config/defconfig_*:
+		# make showconfigs
-- 
1.7.10.4

[PATCH 3/3] mk: rule help

[Thomas Monjalon]

The goal of this rule is to show which rules/options are available from a
"make" command.
Let's start by printing short doc about SDK building.

The macro maketxt allow to interpret syntax "# make foo" while keeping
indentation of the source document.
Here, it is used to call "make showconfigs" to list available targets.

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 mk/rte.sdkdoc.mk  |    8 ++++++++
 mk/rte.sdkroot.mk |    3 ++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index edae1e7..6850c39 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -38,6 +38,14 @@ $(error "Cannot use T= with doc target")
 endif
 endif
 
+define maketxt
+	sed 's,^\([[:space:]]*\)# make \(.*\),make -rRs \2 | sed "s/^/\1/",e' $1
+endef
+
+.PHONY: help
+help:
+	@$(call maketxt, $(RTE_SDK)/doc/build-sdk-quick.txt)
+
 .PHONY: all
 all: htmlapi
 
diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
index 6bbbd54..905b678 100644
--- a/mk/rte.sdkroot.mk
+++ b/mk/rte.sdkroot.mk
@@ -103,8 +103,9 @@ testall testimport:
 install uninstall:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
 
-.PHONY: doc
+.PHONY: doc help
 doc: doc-all
+help: doc-help
 doc-%:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
 
-- 
1.7.10.4

Re: [PATCH 1/3] mk: rule showconfigs for configs listing

[Olivier MATZ]

Hi Thomas,

I wonder if this new rule is really needed: I think you can already
do a "make config" without argument to list the supported
configurations.

Olivier

On 05/07/2013 05:17 PM, Thomas Monjalon wrote:
> Allow to list configs in config/ directory with a simple make rule.
> 
> Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
> ---
>  mk/rte.sdkconfig.mk |    4 ++++
>  mk/rte.sdkroot.mk   |    4 ++--
>  2 files changed, 6 insertions(+), 2 deletions(-)
> 
> diff --git a/mk/rte.sdkconfig.mk b/mk/rte.sdkconfig.mk
> index ed81c47..179089e 100644
> --- a/mk/rte.sdkconfig.mk
> +++ b/mk/rte.sdkconfig.mk
> @@ -36,6 +36,10 @@ INSTALL_CONFIGS := $(filter-out %~,\
>  	$(wildcard $(RTE_SRCDIR)/config/defconfig_*)))
>  INSTALL_TARGETS := $(addsuffix _install,$(INSTALL_CONFIGS))
>  
> +.PHONY: showconfigs
> +showconfigs:
> +	@$(foreach CONFIG, $(INSTALL_CONFIGS), echo $(CONFIG);)
> +
>  .PHONY: config
>  ifeq ($(RTE_CONFIG_TEMPLATE),)
>  config:
> diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
> index f555e33..6bbbd54 100644
> --- a/mk/rte.sdkroot.mk
> +++ b/mk/rte.sdkroot.mk
> @@ -87,8 +87,8 @@ export ROOTDIRS-y ROOTDIRS- ROOTDIRS-n
>  .PHONY: default
>  default: all
>  
> -.PHONY: config
> -config:
> +.PHONY: config showconfigs
> +config showconfigs:
>  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk $@
>  
>  .PHONY: test fast_test ring_test mempool_test

Re: [PATCH 2/3] doc: how to build

[Olivier MATZ]

Hi Thomas,

Good to see a "make help" ;)

What do you think of replacing "Build options" by "Build variables" ?
I think it is not obvious that we have to use V=1 for instance for
a verbose build.

About the "build targets", I suggest to include it in the help of T
variable. What do you think ?

Olivier

On 05/07/2013 05:17 PM, Thomas Monjalon wrote:
> This is a cheat sheet to build DPDK and can be used for a "make help".
> It is explicitly described as a build help in order to concatenate it
> with other helps such as test commands.
> 
> Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
> ---
>  doc/build-sdk-quick.txt |   22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
>  create mode 100644 doc/build-sdk-quick.txt
> 
> diff --git a/doc/build-sdk-quick.txt b/doc/build-sdk-quick.txt
> new file mode 100644
> index 0000000..3f88522
> --- /dev/null
> +++ b/doc/build-sdk-quick.txt
> @@ -0,0 +1,22 @@
> +Basic build
> +	make config T=x86_64-default-linuxapp-gcc && make
> +Build commands
> +	config      get configuration from target template (T=)
> +	all         same as build (default rule)
> +	build       build in a configured directory
> +	clean       remove files but keep configuration
> +	install     build many targets (wildcard allowed) in fixed directories
> +	uninstall   remove all installed targets
> +Build options
> +	T   target template (install default: *) - used with config or install
> +	O   output directory (default: build/)   - cannot be used with install
> +	V   verbose
> +	D   debug dependencies
> +	CROSS            toolchain prefix
> +	EXTRA_CPPFLAGS   preprocessor options
> +	EXTRA_CFLAGS     compiler options
> +	EXTRA_LDFLAGS    linker options
> +Build targets
> +	format: <arch-machine-execenv-toolchain>
> +	templates in config/defconfig_*:
> +		# make showconfigs

Re: [PATCH 3/3] mk: rule help

[Olivier MATZ]

Thomas,

I think the "maketxt" macro is overkill... why not just a "cat" ?

Olivier

On 05/07/2013 05:17 PM, Thomas Monjalon wrote:
> The goal of this rule is to show which rules/options are available from a
> "make" command.
> Let's start by printing short doc about SDK building.
> 
> The macro maketxt allow to interpret syntax "# make foo" while keeping
> indentation of the source document.
> Here, it is used to call "make showconfigs" to list available targets.
> 
> Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
> ---
>  mk/rte.sdkdoc.mk  |    8 ++++++++
>  mk/rte.sdkroot.mk |    3 ++-
>  2 files changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
> index edae1e7..6850c39 100644
> --- a/mk/rte.sdkdoc.mk
> +++ b/mk/rte.sdkdoc.mk
> @@ -38,6 +38,14 @@ $(error "Cannot use T= with doc target")
>  endif
>  endif
>  
> +define maketxt
> +	sed 's,^\([[:space:]]*\)# make \(.*\),make -rRs \2 | sed "s/^/\1/",e' $1
> +endef
> +
> +.PHONY: help
> +help:
> +	@$(call maketxt, $(RTE_SDK)/doc/build-sdk-quick.txt)
> +
>  .PHONY: all
>  all: htmlapi
>  
> diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
> index 6bbbd54..905b678 100644
> --- a/mk/rte.sdkroot.mk
> +++ b/mk/rte.sdkroot.mk
> @@ -103,8 +103,9 @@ testall testimport:
>  install uninstall:
>  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
>  
> -.PHONY: doc
> +.PHONY: doc help
>  doc: doc-all
> +help: doc-help
>  doc-%:
>  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
>  

Re: [PATCH 1/3] mk: rule showconfigs for configs listing

[Thomas Monjalon]

17/05/2013 11:05, Olivier MATZ :
> I wonder if this new rule is really needed: I think you can already
> do a "make config" without argument to list the supported
> configurations.

Yes it is needed because "make config" adds an error comment.
But I could refactor this patch to use "make showconfigs" in "make config".

-- 
Thomas

Re: [PATCH 2/3] doc: how to build

[Thomas Monjalon]

17/05/2013 11:06, Olivier MATZ :
> On 05/07/2013 05:17 PM, Thomas Monjalon wrote:
> > +Build options
> > +	T   target template (install default: *) - used with config or install
> > +	O   output directory (default: build/)   - cannot be used with install
> > +	V   verbose
> > +	D   debug dependencies
> > +	CROSS            toolchain prefix
> > +	EXTRA_CPPFLAGS   preprocessor options
> > +	EXTRA_CFLAGS     compiler options
> > +	EXTRA_LDFLAGS    linker options
> 
> What do you think of replacing "Build options" by "Build variables" ?

OK

> I think it is not obvious that we have to use V=1 for instance for
> a verbose build.

Is it sufficient to change to "Build variables" ?
I could add "(level number, default: 0)" but, in fact, there is only 2 levels:
empty or any value in V/D variables.

> > +Build targets
> > +	format: <arch-machine-execenv-toolchain>
> > +	templates in config/defconfig_*:
> > +		# make showconfigs
> 
> About the "build targets", I suggest to include it in the help of T
> variable. What do you think ?

It is a whole subject described on several lines.
I think it's clearer to have a dedicated section.

-- 
Thomas

Re: [PATCH 3/3] mk: rule help

[Thomas Monjalon]

17/05/2013 11:06, Olivier MATZ :
> On 05/07/2013 05:17 PM, Thomas Monjalon wrote:
> > The macro maketxt allow to interpret syntax "# make foo" while keeping
> > indentation of the source document.
> > Here, it is used to call "make showconfigs" to list available targets.
> [..]
> > +define maketxt
> > +	sed 's,^\([[:space:]]*\)# make \(.*\),make -rRs \2 | sed "s/^/\1/",e' $1
> > +endef
> 
> I think the "maketxt" macro is overkill... why not just a "cat" ?

Because the syntax "# make" is interpreted.
With build-sdk-quick.txt, it lists all available configurations.
Maybe I should add a comment before the macro to explain it.

-- 
Thomas

[PATCH v2 0/3] make help

[Thomas Monjalon]

Let's add help for building DPDK.

changes since v1: (Olivier's review)
- reword/reorganize help
- reuse "showconfigs" in "config"
- no magic sed to call "make showconfigs" in help

---

Thomas Monjalon (3):
  doc: how to build
  mk: rule showconfigs for configs listing
  mk: rule help

 doc/build-sdk-quick.txt |   20 ++++++++++++++++++++
 mk/rte.sdkconfig.mk     |   12 +++++++-----
 mk/rte.sdkdoc.mk        |    5 +++++
 mk/rte.sdkroot.mk       |    7 ++++---
 4 files changed, 36 insertions(+), 8 deletions(-)
 create mode 100644 doc/build-sdk-quick.txt

-- 
1.7.10.4

[PATCH v2 1/3] doc: how to build

[Thomas Monjalon]

This is a cheat sheet to build DPDK and can be used for a "make help".
It is explicitly described as a build help in order to concatenate it
with other helps such as test commands.

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 doc/build-sdk-quick.txt |   20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 doc/build-sdk-quick.txt

diff --git a/doc/build-sdk-quick.txt b/doc/build-sdk-quick.txt
new file mode 100644
index 0000000..c839676
--- /dev/null
+++ b/doc/build-sdk-quick.txt
@@ -0,0 +1,20 @@
+Basic build
+	make config T=x86_64-default-linuxapp-gcc && make
+Build commands
+	config      get configuration from target template (T=)
+	all         same as build (default rule)
+	build       build in a configured directory
+	clean       remove files but keep configuration
+	install     build many targets (wildcard allowed) in fixed directories
+	uninstall   remove all installed targets
+Build variables
+	CROSS            toolchain prefix
+	EXTRA_CPPFLAGS   preprocessor options
+	EXTRA_CFLAGS     compiler options
+	EXTRA_LDFLAGS    linker options
+	V   verbose
+	D   debug dependencies
+	O   output directory (default: build/)   - cannot be used with install
+	T   target template (install default: *) - used with config or install
+			format: <arch-machine-execenv-toolchain>
+			templates in config/defconfig_*
-- 
1.7.10.4

[PATCH v2 2/3] mk: rule showconfigs for configs listing

[Thomas Monjalon]

Allow to list configs in config/ directory with a simple make rule.

The rule showconfigs is reused in config error.
In the same time, "echo -n" is replaced by the more portable "printf".

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 mk/rte.sdkconfig.mk |   12 +++++++-----
 mk/rte.sdkroot.mk   |    4 ++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/mk/rte.sdkconfig.mk b/mk/rte.sdkconfig.mk
index ed81c47..2c071a2 100644
--- a/mk/rte.sdkconfig.mk
+++ b/mk/rte.sdkconfig.mk
@@ -36,14 +36,16 @@ INSTALL_CONFIGS := $(filter-out %~,\
 	$(wildcard $(RTE_SRCDIR)/config/defconfig_*)))
 INSTALL_TARGETS := $(addsuffix _install,$(INSTALL_CONFIGS))
 
+.PHONY: showconfigs
+showconfigs:
+	@$(foreach CONFIG, $(INSTALL_CONFIGS), echo $(CONFIG);)
+
 .PHONY: config
 ifeq ($(RTE_CONFIG_TEMPLATE),)
 config:
-	@echo -n "No template specified. Use T=template " ; \
-	echo "among the following list:" ; \
-	for t in $(INSTALL_CONFIGS); do \
-		echo "  $$t" ; \
-	done
+	@printf "No template specified. "
+	@echo "Use T=template among the following list:"
+	@$(MAKE) -rR showconfigs | sed 's,^,  ,'
 else
 config: $(RTE_OUTPUT)/include/rte_config.h $(RTE_OUTPUT)/Makefile
 	$(Q)$(MAKE) depdirs
diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
index f555e33..6bbbd54 100644
--- a/mk/rte.sdkroot.mk
+++ b/mk/rte.sdkroot.mk
@@ -87,8 +87,8 @@ export ROOTDIRS-y ROOTDIRS- ROOTDIRS-n
 .PHONY: default
 default: all
 
-.PHONY: config
-config:
+.PHONY: config showconfigs
+config showconfigs:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk $@
 
 .PHONY: test fast_test ring_test mempool_test
-- 
1.7.10.4

[PATCH v2 3/3] mk: rule help

[Thomas Monjalon]

The goal of this rule is to show which rules/options are available from a
"make" command.
Let's start by printing short doc about SDK building.

Signed-off-by: Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>
---
 mk/rte.sdkdoc.mk  |    5 +++++
 mk/rte.sdkroot.mk |    3 ++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index edae1e7..96eec69 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -38,6 +38,11 @@ $(error "Cannot use T= with doc target")
 endif
 endif
 
+.PHONY: help
+help:
+	@cat $(RTE_SDK)/doc/build-sdk-quick.txt
+	@$(MAKE) -rR showconfigs | sed 's,^,\t\t\t\t,'
+
 .PHONY: all
 all: htmlapi
 
diff --git a/mk/rte.sdkroot.mk b/mk/rte.sdkroot.mk
index 6bbbd54..905b678 100644
--- a/mk/rte.sdkroot.mk
+++ b/mk/rte.sdkroot.mk
@@ -103,8 +103,9 @@ testall testimport:
 install uninstall:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
 
-.PHONY: doc
+.PHONY: doc help
 doc: doc-all
+help: doc-help
 doc-%:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
 
-- 
1.7.10.4

Re: [PATCH v2 0/3] make help

[Olivier MATZ]

Hi Thomas,

On 05/29/2013 12:15 AM, Thomas Monjalon wrote:
> Let's add help for building DPDK.
>
> changes since v1: (Olivier's review)
> - reword/reorganize help
> - reuse "showconfigs" in "config"
> - no magic sed to call "make showconfigs" in help

Looks good to me ! Thank you for taking the comments in account.

Olivier

Re: [PATCH v2 0/3] make help

[Thomas Monjalon]

30/05/2013 16:55, Olivier MATZ :
> On 05/29/2013 12:15 AM, Thomas Monjalon wrote:
> > Let's add help for building DPDK.
> > 
> > changes since v1: (Olivier's review)
> > - reword/reorganize help
> > - reuse "showconfigs" in "config"
> > - no magic sed to call "make showconfigs" in help
> 
> Looks good to me ! Thank you for taking the comments in account.

pushed

Thanks for your review
-- 
Thomas