[RFC] build-sys: add make 'help' target

From: Marc-André Lureau <marcandre.lureau@redhat.com>

Add a make 'help', to print a summary of the main Makefile targets.
The format is loosely inspired by Linux make 'help' output.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 Makefile | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

ping

On Mon, Jun 20, 2016 at 7:19 PM,  <marcandre.lureau@redhat.com> wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Add a make 'help', to print a summary of the main Makefile targets.
> The format is loosely inspired by Linux make 'help' output.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  Makefile | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
>
> diff --git a/Makefile b/Makefile
> index 53e4119..c6bf3d6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -666,3 +666,36 @@ endif
>  -include $(wildcard *.d tests/*.d)
>
>  include $(SRC_PATH)/tests/docker/Makefile.include
> +
> +.PHONY: help
> +help:
> +
> +       @echo  'Cleaning targets:'
> +       @echo  '  clean           - Remove most generated files but keep the config'
> +       @echo  '  distclean       - Remove all generated files'
> +       @echo  '  dist            - Build a distributable tarball'
> +       @echo  ''
> +       @echo  'Test targets:'
> +       @echo  '  check           - Run all tests (check-help for details)'
> +       @echo  '  docker          - Build QEMU and run tests inside Docker containers'
> +       @echo  '  test/speed      - Run TCG tests'
> +       @echo  ''
> +       @echo  'Documentation targets:'
> +       @echo  '  dvi/html/'
> +       @echo  '  info/pdf        - Build documentation in specified format'
> +       @echo  ''
> +       @echo  'Other generic targets:'
> +       @echo  '  all             - Build all'
> +       @echo  '  install         - Install QEMU, documentation and tools'
> +       @echo  '  ctags/TAGS      - Generate tags file for editors'
> +       @echo  '  cscope          - Generate cscope index'
> +ifdef CONFIG_WIN32
> +       @echo  ''
> +       @echo  'Windows targets:'
> +       @echo  '  installer       - Build NSIS-based installer'
> +ifdef QEMU_GA_MSI_ENABLED
> +       @echo  '  msi             - Build MSI-based installer'
> +endif
> +endif
> +       @echo  ''
> +       @echo  '  make V=0|1 [targets] 0 => quiet build (default), 1 => verbose build'
> --
> 2.7.4
>
>

On 20/06/2016 17:19, marcandre.lureau@redhat.com wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
> 
> Add a make 'help', to print a summary of the main Makefile targets.
> The format is loosely inspired by Linux make 'help' output.
> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  Makefile | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/Makefile b/Makefile
> index 53e4119..c6bf3d6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -666,3 +666,36 @@ endif
>  -include $(wildcard *.d tests/*.d)
>  
>  include $(SRC_PATH)/tests/docker/Makefile.include
> +
> +.PHONY: help
> +help:
> +
> +	@echo  'Cleaning targets:'
> +	@echo  '  clean           - Remove most generated files but keep the config'
> +	@echo  '  distclean       - Remove all generated files'
> +	@echo  '  dist            - Build a distributable tarball'
> +	@echo  ''
> +	@echo  'Test targets:'
> +	@echo  '  check           - Run all tests (check-help for details)'
> +	@echo  '  docker          - Build QEMU and run tests inside Docker containers'

"docker" is a help target.

> +	@echo  '  test/speed      - Run TCG tests'
> +	@echo  ''
> +	@echo  'Documentation targets:'
> +	@echo  '  dvi/html/'
> +	@echo  '  info/pdf        - Build documentation in specified format'
> +	@echo  ''
> +	@echo  'Other generic targets:'
> +	@echo  '  all             - Build all'

Shouldn't "all" come first?

> +	@echo  '  install         - Install QEMU, documentation and tools'
> +	@echo  '  ctags/TAGS      - Generate tags file for editors'
> +	@echo  '  cscope          - Generate cscope index'
> +ifdef CONFIG_WIN32
> +	@echo  ''
> +	@echo  'Windows targets:'
> +	@echo  '  installer       - Build NSIS-based installer'
> +ifdef QEMU_GA_MSI_ENABLED
> +	@echo  '  msi             - Build MSI-based installer'

Build MSI-based installer for qemu-ga.

Paolo

> +endif
> +endif
> +	@echo  ''
> +	@echo  '  make V=0|1 [targets] 0 => quiet build (default), 1 => verbose build'
>

On 20 June 2016 at 16:19,  <marcandre.lureau@redhat.com> wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Add a make 'help', to print a summary of the main Makefile targets.
> The format is loosely inspired by Linux make 'help' output.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  Makefile | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
>
> diff --git a/Makefile b/Makefile
> index 53e4119..c6bf3d6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -666,3 +666,36 @@ endif
>  -include $(wildcard *.d tests/*.d)
>
>  include $(SRC_PATH)/tests/docker/Makefile.include
> +
> +.PHONY: help
> +help:
> +
> +       @echo  'Cleaning targets:'
> +       @echo  '  clean           - Remove most generated files but keep the config'
> +       @echo  '  distclean       - Remove all generated files'
> +       @echo  '  dist            - Build a distributable tarball'

There's a cute trick which will let us put these help strings
next to the actual makefile targets, which might make it easier
for us to remember to update and add them: you have a rune
something like
help:    ## Show this help.
        @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' |
sed -e 's/##//'

and then you can annotate all your targets with their doc strings:

check:     ## Run all tests

Idea from https://gist.github.com/prwhite/8168133

We'd need to elaborate it somewhat to add categories, but you get the
general idea.

Does this seem useful, or like overkill ?

thanks
-- PMM

Hi

----- Original Message -----
> On 20 June 2016 at 16:19,  <marcandre.lureau@redhat.com> wrote:
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
> > Add a make 'help', to print a summary of the main Makefile targets.
> > The format is loosely inspired by Linux make 'help' output.
> >
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > ---
> >  Makefile | 33 +++++++++++++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> >
> > diff --git a/Makefile b/Makefile
> > index 53e4119..c6bf3d6 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -666,3 +666,36 @@ endif
> >  -include $(wildcard *.d tests/*.d)
> >
> >  include $(SRC_PATH)/tests/docker/Makefile.include
> > +
> > +.PHONY: help
> > +help:
> > +
> > +       @echo  'Cleaning targets:'
> > +       @echo  '  clean           - Remove most generated files but keep
> > the config'
> > +       @echo  '  distclean       - Remove all generated files'
> > +       @echo  '  dist            - Build a distributable tarball'
> 
> There's a cute trick which will let us put these help strings
> next to the actual makefile targets, which might make it easier
> for us to remember to update and add them: you have a rune
> something like
> help:    ## Show this help.
>         @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//'
>         |
> sed -e 's/##//'
> 
> and then you can annotate all your targets with their doc strings:
> 
> check:     ## Run all tests
> 
> Idea from https://gist.github.com/prwhite/8168133
> 
> We'd need to elaborate it somewhat to add categories, but you get the
> general idea.
> 
> Does this seem useful, or like overkill ?

Interesting, in fact I use a similar trick in some of my shell scripts:
https://github.com/elmarco/virgl-ci/blob/master/virgl-test.sh#L258

But tbh, I don't think it's so great, it's a bit overkill indeed.