[PATCH] Makefile: Add help target

[PATCH] Makefile: Add help target

[Stephen Boyd]

Today I forgot whether the target was quick-install-doc or
install-quick-doc and had to open the Makefile again to find out. I'd
rather not do that and just use:

	$ make help

to get a quick summary of the interesting targets when my brain fails to
refresh. Add a help target, but don't add uninteresting things like
strip, install-gitweb, or targets which alias (install-man).

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---

Some things I noticed:

 * make V=0 is verbose

 * sparse checking looks broken for the builtin/ directory structure

 * t/Makefile has a target for valgrind, but the toplevel makefile doesn't

 * 'make tags/TAGS/cscope' is always verbose

 * I stay up late on Tuesdays

 Makefile |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/Makefile b/Makefile
index b4745a5..8c90c33 100644
--- a/Makefile
+++ b/Makefile
@@ -2307,3 +2307,43 @@ coverage-report:
 	grep '^function.*called 0 ' *.c.gcov \
 		| sed -e 's/\([^:]*\)\.gcov: *function \([^ ]*\) called.*/\1: \2/' \
 		| tee coverage-untested-functions
+
+help:
+	@echo 'Cleaning targets:'
+	@echo '  clean      - Remove generated files but keep the configure script'
+	@echo '  distclean  - Remove generated files and the configure script'
+	@echo
+	@echo 'Packaging targets:'
+	@echo '  dist       - Build git-$(GIT_VERSION).tar.gz source tarball'
+	@echo '  rpm        - Build source and binary RPM packages'
+	@echo '  dist-doc   - Build $(manpages).tar.gz and $(htmldocs).tar.gz'
+	@echo
+	@echo 'Documentation targets:'
+	@echo '  doc     - Build man pages and HTML docs'
+	@echo '  man     - Build man pages'
+	@echo '  html    - Build HTML docs'
+	@echo '  info    - Build info docs'
+	@echo '  pdf     - Build PDF docs'
+	@echo
+	@echo 'Installation targets:'
+	@echo '  install             - Install the git suite'
+	@echo '  install-doc         - Install man pages'
+	@echo '  install-html        - Install HTML docs'
+	@echo '  install-info        - Install info docs'
+	@echo '  install-pdf         - Install PDF docs'
+	@echo '  quick-install-doc   - Install pregenerated man pages from origin/man'
+	@echo '  quick-install-html  - Install pregenerated HTML pages from origin/html'
+	@echo
+	@echo 'Common targets:'
+	@echo '  all            - Build the git suite'
+	@echo '  test           - Run the git test suite'
+	@echo
+	@echo 'Other targets:'
+	@echo '  tags/TAGS      - Generate tags for editors'
+	@echo '  cscope         - Generate cscope index'
+	@echo '  coverage       - Build git with gcov support, run the test suite, and'
+	@echo '                   report untested functions'
+	@echo '  check          - Check C sources with sparse'
+	@echo
+	@echo '  make V=1 [targets] verbose build'
+	@echo
-- 
1.7.2.2.169.gb5442

Re: [PATCH] Makefile: Add help target

[Sverre Rabbelier]

Heya,

On Wed, Aug 25, 2010 at 04:51, Stephen Boyd <bebarino@gmail.com> wrote:
> Today I forgot whether the target was quick-install-doc or
> install-quick-doc and had to open the Makefile again to find out. I'd
> rather not do that and just use:
>
>        $ make help
>
> to get a quick summary of the interesting targets when my brain fails to
> refresh. Add a help target, but don't add uninteresting things like
> strip, install-gitweb, or targets which alias (install-man).

Yes please, it would be even better if you're willing to make sure
that this stays up to date ;).

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Makefile: Add help target

[Stephen Boyd]

Hey Sverre,

On Wed, Aug 25, 2010 at 9:27 AM, Sverre Rabbelier <srabbelier@gmail.com> wrote:
> Heya,
>
> On Wed, Aug 25, 2010 at 04:51, Stephen Boyd <bebarino@gmail.com> wrote:
>> Today I forgot whether the target was quick-install-doc or
>> install-quick-doc and had to open the Makefile again to find out. I'd
>> rather not do that and just use:
>>
>>        $ make help
>>
>> to get a quick summary of the interesting targets when my brain fails to
>> refresh. Add a help target, but don't add uninteresting things like
>> strip, install-gitweb, or targets which alias (install-man).
>
> Yes please, it would be even better if you're willing to make sure
> that this stays up to date ;).
>

"Yes please" means you like it?

I'll keep an eye on the list for any interesting Makefile targets, but
no promises ;-)

Re: [PATCH] Makefile: Add help target

[Sverre Rabbelier]

Heya,

On Wed, Aug 25, 2010 at 16:36, Stephen Boyd <bebarino@gmail.com> wrote:
> "Yes please" means you like it?

Indeed.

> I'll keep an eye on the list for any interesting Makefile targets, but
> no promises ;-)

That's all we can ask for right :).

-- 
Cheers,

Sverre Rabbelier

[PATCH] Makefile: Add help target

[Stephen Boyd]

Today I forgot whether the target was quick-install-doc or
install-quick-doc and had to open the Makefile again to find out. I'd
rather not do that and just use:

	$ make help

to get a quick summary of the interesting targets when my brain fails to
refresh. Add a help target, but don't add uninteresting things like
strip, install-gitweb, or targets which alias (install-man).

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Makefile |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/Makefile b/Makefile
index b7a62cf..8c8fcb0 100644
--- a/Makefile
+++ b/Makefile
@@ -2366,3 +2366,43 @@ cover_db: coverage-report
 
 cover_db_html: cover_db
 	cover -report html -outputdir cover_db_html cover_db
+
+help:
+	@echo 'Cleaning targets:'
+	@echo '  clean      - Remove generated files but keep the configure script'
+	@echo '  distclean  - Remove generated files and the configure script'
+	@echo
+	@echo 'Packaging targets:'
+	@echo '  dist       - Build git-$(GIT_VERSION).tar.gz source tarball'
+	@echo '  rpm        - Build source and binary RPM packages'
+	@echo '  dist-doc   - Build $(manpages).tar.gz and $(htmldocs).tar.gz'
+	@echo
+	@echo 'Documentation targets:'
+	@echo '  doc     - Build man pages and HTML docs'
+	@echo '  man     - Build man pages'
+	@echo '  html    - Build HTML docs'
+	@echo '  info    - Build info docs'
+	@echo '  pdf     - Build PDF docs'
+	@echo
+	@echo 'Installation targets:'
+	@echo '  install             - Install the git suite'
+	@echo '  install-doc         - Install man pages'
+	@echo '  install-html        - Install HTML docs'
+	@echo '  install-info        - Install info docs'
+	@echo '  install-pdf         - Install PDF docs'
+	@echo '  quick-install-doc   - Install pregenerated man pages from origin/man'
+	@echo '  quick-install-html  - Install pregenerated HTML pages from origin/html'
+	@echo
+	@echo 'Common targets:'
+	@echo '  all            - Build the git suite'
+	@echo '  test           - Run the git test suite'
+	@echo
+	@echo 'Other targets:'
+	@echo '  tags/TAGS      - Generate tags for editors'
+	@echo '  cscope         - Generate cscope index'
+	@echo '  coverage       - Build git with gcov support and run the test suite'
+	@echo '  cover_db_html  - Generate HTML coverage report of the test suite coverage'
+	@echo '  check          - Check C sources with sparse'
+	@echo
+	@echo '  make V=1 [targets] verbose build'
+	@echo
-- 
1.7.3.16.g5d4d9

Re: [PATCH] Makefile: Add help target

[Junio C Hamano]

Not interested, at least in the current form.

I do not look forward to having to maintain a large number of lines that
are doomed to go stale, and every time we need to touch we need to deal
with a lot of noise "@echo '"?  No thanks.

It might be a bit less distasteful if it were plain text additions at the
end of INSTALL file, though.

Re: [PATCH] Makefile: Add help target

[Sverre Rabbelier]

Heya,

On Tue, Sep 28, 2010 at 11:45, Junio C Hamano <gitster@pobox.com> wrote:
> I do not look forward to having to maintain a large number of lines that
> are doomed to go stale

How often have we changed makefile targets recently? The most recent
one that I can find is Jakub adding "install-gitweb" in 152d94348f,
which was back in May 1st. The next one before that is the addition of
'gitweb' in 62331ef1637f which was back in January 30th. Besides,
'make help' doesn't have to contain _all_ Makefile targets, just the
important ones that a user is most likely to need. Similar to 'git
help' itself.

> and every time we need to touch we need to deal
> with a lot of noise "@echo '"?

I don't understand what is particularly bothersome about the leading
"@echo" lines. Adding or removing a target is still very easy even
with the leading @echo's, the only thing that would be a PITA is
reflowing paragraphs, currently, there _are_ no paragraphs, everything
fits on one line.

> It might be a bit less distasteful if it were plain text additions at the
> end of INSTALL file, though.

That does not help me nearly as much when I want to know how a
makefile target is called. Am I wrong in asserting that having a "make
help" target is an accepted "good practice" in the unix world?

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Makefile: Add help target

[Andreas Ericsson]

On 09/28/2010 01:37 PM, Sverre Rabbelier wrote:
> Heya,
> 
> On Tue, Sep 28, 2010 at 11:45, Junio C Hamano<gitster@pobox.com>  wrote:
>> I do not look forward to having to maintain a large number of lines that
>> are doomed to go stale
> 
> How often have we changed makefile targets recently? The most recent
> one that I can find is Jakub adding "install-gitweb" in 152d94348f,
> which was back in May 1st. The next one before that is the addition of
> 'gitweb' in 62331ef1637f which was back in January 30th. Besides,
> 'make help' doesn't have to contain _all_ Makefile targets, just the
> important ones that a user is most likely to need. Similar to 'git
> help' itself.
> 
>> and every time we need to touch we need to deal
>> with a lot of noise "@echo '"?
> 
> I don't understand what is particularly bothersome about the leading
> "@echo" lines. Adding or removing a target is still very easy even
> with the leading @echo's, the only thing that would be a PITA is
> reflowing paragraphs, currently, there _are_ no paragraphs, everything
> fits on one line.
> 
>> It might be a bit less distasteful if it were plain text additions at the
>> end of INSTALL file, though.
> 
> That does not help me nearly as much when I want to know how a
> makefile target is called. Am I wrong in asserting that having a "make
> help" target is an accepted "good practice" in the unix world?
> 

help:
    @echo Available make targets:
    @echo -----------------------
    @$(MAKE) --print-data-base --question | \
	sed -n -e '/^Makefile/d' -e 's/^\([a-z0-9_-]*\):.*/\1/p' | \
	sort | uniq | grep -v -e ^git -e ^test-

Automatically self-managing and seems to print most sensible targets.
Adjust to taste with whatever's appropriate.

Users with a too-old make program (pre 3.67, I think), won't be able
to use the help target, but that's perfectly acceptable imo.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: [PATCH] Makefile: Add help target

[yj2133011]

Not interested, at least in the current form.

I do not look forward to having to maintain a large number of lines that
are doomed to go stale, and every time we need to touch we need to deal
with a lot of noise "@echo '"?  No thanks.

It might be a bit less distasteful if it were plain text additions at the
end of INSTALL file, though. 

-----
The voice input and output is very good in this 
http://www.tomtop.com/black-ps3-wireless-bluetooth-headset-for-playstation-3.html?aid=z
Wireless PS3 Headset . It is compatible with all PS3 games.Buy from Reliable 
http://www.tomtop.com/google-android-7-notebook-3g-tablet-pc-umpc-wifi-mid-pda.html?aid=z
Google Android PC  apad Wholesalers.
-- 
View this message in context: http://git.661346.n2.nabble.com/PATCH-Makefile-Add-help-target-tp5578369p5582616.html
Sent from the git mailing list archive at Nabble.com.

[PATCH] Makefile: add help target

[Elia Pinto]

Add a help target to the Makefile to be able to run make help, in the same way
does the Makefiles self-generated by some build systems.

The target list has been statically extracted from the git Makefile with a
script and the results have been filtered in an essentially arbitrary way to
leave the ones that i imagines most interesting and frequent for a developer.

Signed-off-by: Elia Pinto <gitter.spiros@gmail.com>
---
The toy script I used is here
https://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh
 Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/Makefile b/Makefile
index e8aba291d7..f6d6de2eb9 100644
--- a/Makefile
+++ b/Makefile
@@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all
 		$(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@
 
 fuzz-all: $(FUZZ_PROGRAMS)
+
+# Help Target
+help:
+	@echo "The following are some of the valid targets for this Makefile:"
+	@echo "... all (the default if no target is provided)"
+	@echo "... build-perl-script"
+	@echo "... build-python-script"
+	@echo "... build-sh-script"
+	@echo "... check"
+	@echo "... check-builtins"
+	@echo "... check-docs"
+	@echo "... check-sha1"
+	@echo "... clean"
+	@echo "... clean-perl-script"
+	@echo "... clean-python-script"
+	@echo "... clean-sh-script"
+	@echo "... coccicheck"
+	@echo "... coccicheck-pending"
+	@echo "... cocciclean"
+	@echo "... configure"
+	@echo "... coverage"
+	@echo "... coverage-clean"
+	@echo "... coverage-clean-results"
+	@echo "... coverage-compile"
+	@echo "... coverage-prove"
+	@echo "... coverage-report"
+	@echo "... coverage-test"
+	@echo "... coverage-untested-functions"
+	@echo "... cover_db"
+	@echo "... cover_db_html"
+	@echo "... cscope"
+	@echo "... dist"
+	@echo "... distclean"
+	@echo "... dist-doc"
+	@echo "... doc"
+	@echo "... fuzz-all"
+	@echo "... fuzz-commit-graph"
+	@echo "... fuzz-objs"
+	@echo "... fuzz-pack-headers"
+	@echo "... fuzz-pack-idx"
+	@echo "... html"
+	@echo "... info"
+	@echo "... install"
+	@echo "... man"
+	@echo "... pdf"
+	@echo "... perf"
+	@echo "... profile"
+	@echo "... profile-clean"
+	@echo "... profile-fast"
+	@echo "... profile-fast-install"
+	@echo "... profile-install"
+	@echo "... quick-install-doc"
+	@echo "... quick-install-html"
+	@echo "... quick-install-man"
+	@echo "... reconfigure"
+	@echo "... rpm"
+	@echo "... sparse"
+	@echo "... strip"
+	@echo "... style"
+	@echo "... tags"
+	@echo "... TAGS"
+	@echo "... test"
+.PHONY : help
-- 
2.35.1

Re: [PATCH] Makefile: add help target

[Philip Oakley]

On 08/04/2022 08:45, Elia Pinto wrote:
> Add a help target to the Makefile to be able to run make help, in the same way
> does the Makefiles self-generated by some build systems.
>
> The target list has been statically extracted from the git Makefile with a
> script and the results have been filtered in an essentially arbitrary way to
> leave the ones that i imagines most interesting and frequent for a developer.
>
> Signed-off-by: Elia Pinto <gitter.spiros@gmail.com>
> ---
> The toy script I used is here
> https://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh
>  Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 63 insertions(+)
>
> diff --git a/Makefile b/Makefile
> index e8aba291d7..f6d6de2eb9 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all
>  		$(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@
>  
>  fuzz-all: $(FUZZ_PROGRAMS)
> +
> +# Help Target
> +help:
> +	@echo "The following are some of the valid targets for this Makefile:"
> +	@echo "... all (the default if no target is provided)"
> +	@echo "... build-perl-script"
> +	@echo "... build-python-script"
> +	@echo "... build-sh-script"
> +	@echo "... check"
> +	@echo "... check-builtins"
> +	@echo "... check-docs"
> +	@echo "... check-sha1"
> +	@echo "... clean"
> +	@echo "... clean-perl-script"
> +	@echo "... clean-python-script"
> +	@echo "... clean-sh-script"
> +	@echo "... coccicheck"
> +	@echo "... coccicheck-pending"
> +	@echo "... cocciclean"
> +	@echo "... configure"
> +	@echo "... coverage"
> +	@echo "... coverage-clean"
> +	@echo "... coverage-clean-results"
> +	@echo "... coverage-compile"
> +	@echo "... coverage-prove"
> +	@echo "... coverage-report"
> +	@echo "... coverage-test"
> +	@echo "... coverage-untested-functions"
> +	@echo "... cover_db"
> +	@echo "... cover_db_html"
> +	@echo "... cscope"
> +	@echo "... dist"
> +	@echo "... distclean"
> +	@echo "... dist-doc"
> +	@echo "... doc"
> +	@echo "... fuzz-all"
> +	@echo "... fuzz-commit-graph"
> +	@echo "... fuzz-objs"
> +	@echo "... fuzz-pack-headers"
> +	@echo "... fuzz-pack-idx"
> +	@echo "... html"
> +	@echo "... info"
> +	@echo "... install"
> +	@echo "... man"
> +	@echo "... pdf"
> +	@echo "... perf"
> +	@echo "... profile"
> +	@echo "... profile-clean"
> +	@echo "... profile-fast"
> +	@echo "... profile-fast-install"
> +	@echo "... profile-install"
> +	@echo "... quick-install-doc"
> +	@echo "... quick-install-html"
> +	@echo "... quick-install-man"
> +	@echo "... reconfigure"
> +	@echo "... rpm"
> +	@echo "... sparse"
> +	@echo "... strip"
> +	@echo "... style"
> +	@echo "... tags"
> +	@echo "... TAGS"
> +	@echo "... test"
> +.PHONY : help

Makes me realise how many areas I'm unfamiliar with, .. which is a help. ;-)
--
Philip

Re: [PATCH] Makefile: add help target

[Taylor Blau]

On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote:
> Add a help target to the Makefile to be able to run make help, in the same way
> does the Makefiles self-generated by some build systems.
>
> The target list has been statically extracted from the git Makefile with a
> script and the results have been filtered in an essentially arbitrary way to
> leave the ones that i imagines most interesting and frequent for a developer.

I could definitely see something like "make help" being helpful, since
make itself doesn't have a convenient way to list all of a Makefile's
targets.

I worry about this list getting stale, though. If we add a new target,
will we remember to update the "help" list here? It would be nice if we
could dynamically generate this list, but I think that loses out on the
filtering you've done here.

Thanks,
Taylor

Re: [PATCH] Makefile: add help target

[Ævar Arnfjörð Bjarmason]

On Fri, Apr 08 2022, Taylor Blau wrote:

> On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote:
>> Add a help target to the Makefile to be able to run make help, in the same way
>> does the Makefiles self-generated by some build systems.
>>
>> The target list has been statically extracted from the git Makefile with a
>> script and the results have been filtered in an essentially arbitrary way to
>> leave the ones that i imagines most interesting and frequent for a developer.
>
> I could definitely see something like "make help" being helpful, since
> make itself doesn't have a convenient way to list all of a Makefile's
> targets.
>
> I worry about this list getting stale, though. If we add a new target,
> will we remember to update the "help" list here? It would be nice if we
> could dynamically generate this list, but I think that loses out on the
> filtering you've done here.

There's some nice suggestions at:
https://stackoverflow.com/questions/4219255/how-do-you-get-the-list-of-targets-in-a-makefile

I managed to get pretty close to this by massaging the various parsers
that were suggested there.

But I wonder if defining help as we go along wouldn't be the best and
least likely to break, and most likely to be kept up-to-date. I.e. some
variant of the comments added there.

Or better (maybe it's discussed in that SO thing, I didn't skim it all),
something like:

    HELP_all = the default target
    all::
    [...]

We could then even print a heading showing what target(s) we're running
by looking at MAKECMDGOALS.

Also, Elia's ad-hoc script here copied from StackOverflow looks awfully
similar to what I have in /usr/share/bash-completion/completions/make
installed with my OS. Available here:
https://github.com/scop/bash-completion/blob/master/completions/make

So maybe we could just make this an optional target that depended on
that widely-available bash completion?

That would also have the nice benefit that to the extent that the output
sucked we could maybe massage our Makefile a bit to make it better, and
then we'd not only benefit "make help" users, but anyone doing "make
<TAB>".

Re: [PATCH] Makefile: add help target

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

> I could definitely see something like "make help" being helpful, since
> make itself doesn't have a convenient way to list all of a Makefile's
> targets.

But is listing all useful to begin with?  I doubt it.

Most useful targets are all .PHONYs, so a possible approach is to
make them double-colon rules, and have a section at the top, next to
where we explain "# The default target of this Makefile is...", that
lists all of them there, and have a rule

	# The default target of this Makefile is...
	all::
	+# Common targets
	+test::
	+doc::
	+...
        +help::
        +        sed -e '/help::/q' Makefile
        # Import tree-wide shared Makefile behavior and libraries
        include shared.mak

perhaps?

> I worry about this list getting stale, though.

Absolutely.

A well-curated list of common targets, maybe, but I find nothing
interesting in the posted patch that lists way too many.

I also suspect that a well-curated list at the top would eliminate
the need for the "help" target in the first place.  Between "make
help" and "less Makefile", the latter is much more intuitive.

Thanks.