[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>
---
 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.

[PATCH] Makefile: implement help target

[Michael J Gruber]

with automatic help text collection from lines starting with "#H# " and
preceding a make target.

Suggested-by: Stephen Boyd <bebarino@gmail.com>
Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
How's this for a version without maintenance issues?
We could sort differently, of course, or at a category key (build, doc, etc.)
but let's not go too far. Currently, the output of make help is:

GIT_VERSION = 1.7.3.99.gc16e8
dist                : Build git-$(GIT_VERSION).tar.gz source
html                : Build HTML doc
info                : Build info docs
man                 : Build man pages
doc                 : Build man pages and HTML docs
dist-doc            : Build $(manpages).tar.gz and $(htmldocs).tar.gz
pdf                 : Build PDF docs
rpm                 : Build source and binary RPM packages
check-docs          : Check documentation coverage
coverage            : Check test coverage
cover_db_html       : Check test coverage and create HTMl report
test                : Check the build by running the test suite
cscope              : Generate cscope index
tags                : Generate tags using ctags
install-html        : Install HTML docs
install-info        : Install info docs
install-doc         : Install man pages
install-man         : Install man pages
install-pdf         : Install PDF docs
quick-install-html  : Install pregenerated HTML pages from origin/html
quick-install-doc   : Install pregenerated man pages from origin/man
quick-install-man   : Install pregenerated man pages from origin/man
install             : Install the git suite
distclean           : Remove generated files and the configure script
clean               : Remove generated files but keep the configure script
help                : Show help for main make targets

 Makefile |   38 ++++++++++++++++++++++++++++++++++++--
 1 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index db2efd6..187a8a2 100644
--- a/Makefile
+++ b/Makefile
@@ -1952,29 +1952,37 @@ $(XDIFF_LIB): $(XDIFF_OBJS)
 $(VCSSVN_LIB): $(VCSSVN_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)
 
+#H# Build man pages and HTML docs
 doc:
 	$(MAKE) -C Documentation all
 
+#H# Build man pages
 man:
 	$(MAKE) -C Documentation man
 
+#H# Build HTML doc
 html:
 	$(MAKE) -C Documentation html
 
+#H# Build info docs
 info:
 	$(MAKE) -C Documentation info
 
+#H# Build PDF docs
 pdf:
 	$(MAKE) -C Documentation pdf
 
+#H# Generate tags using etags
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
 
+#H# Generate tags using ctags
 tags:
 	$(RM) tags
 	$(FIND) . -name '*.[hcS]' -print | xargs ctags -a
 
+#H# Generate cscope index
 cscope:
 	$(RM) cscope*
 	$(FIND) . -name '*.[hcS]' -print | xargs cscope -b
@@ -2040,6 +2048,7 @@ export NO_SVN_TESTS
 
 ### Testing rules
 
+#H# Check the build by running the test suite
 test: all
 	$(MAKE) -C t/ all
 
@@ -2099,6 +2108,7 @@ export gitexec_instdir
 
 install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)
 
+#H# Install the git suite
 install: all
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'
@@ -2155,27 +2165,35 @@ endif
 install-gitweb:
 	$(MAKE) -C gitweb install
 
+#H# Install man pages
 install-doc:
 	$(MAKE) -C Documentation install
 
+#H# Install man pages
 install-man:
 	$(MAKE) -C Documentation install-man
 
+#H# Install HTML docs
 install-html:
 	$(MAKE) -C Documentation install-html
 
+#H# Install info docs
 install-info:
 	$(MAKE) -C Documentation install-info
 
+#H# Install PDF docs
 install-pdf:
 	$(MAKE) -C Documentation install-pdf
 
+#H# Install pregenerated man pages from origin/man
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
+#H# Install pregenerated man pages from origin/man
 quick-install-man:
 	$(MAKE) -C Documentation quick-install-man
 
+#H# Install pregenerated HTML pages from origin/html
 quick-install-html:
 	$(MAKE) -C Documentation quick-install-html
 
@@ -2188,6 +2206,7 @@ git.spec: git.spec.in
 	mv $@+ $@
 
 GIT_TARNAME=git-$(GIT_VERSION)
+#H# Build git-$(GIT_VERSION).tar.gz source
 dist: git.spec git-archive$(X) configure
 	./git-archive --format=tar \
 		--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar
@@ -2203,6 +2222,7 @@ dist: git.spec git-archive$(X) configure
 	@$(RM) -r $(GIT_TARNAME)
 	gzip -f -9 $(GIT_TARNAME).tar
 
+#H# Build source and binary RPM packages
 rpm: dist
 	$(RPMBUILD) \
 		--define "_source_filedigest_algorithm md5" \
@@ -2211,6 +2231,8 @@ rpm: dist
 
 htmldocs = git-htmldocs-$(GIT_VERSION)
 manpages = git-manpages-$(GIT_VERSION)
+
+#H# Build $(manpages).tar.gz and $(htmldocs).tar.gz
 dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir .doc-tmp-dir
@@ -2230,10 +2252,11 @@ dist-doc:
 	$(RM) -r .doc-tmp-dir
 
 ### Cleaning rules
-
+#H# Remove generated files and the configure script
 distclean: clean
 	$(RM) configure
 
+#H# Remove generated files but keep the configure script
 clean:
 	$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \
 		builtin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)
@@ -2268,7 +2291,7 @@ endif
 .PHONY: FORCE TAGS tags cscope
 
 ### Check documentation
-#
+#H# Check documentation coverage
 check-docs::
 	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \
 	do \
@@ -2335,6 +2358,7 @@ check-builtins::
 #
 .PHONY: coverage coverage-clean coverage-build coverage-report
 
+#H# Check test coverage
 coverage:
 	$(MAKE) coverage-build
 	$(MAKE) coverage-report
@@ -2370,5 +2394,15 @@ coverage-untested-functions: coverage-report
 cover_db: coverage-report
 	gcov2perl -db cover_db *.gcov
 
+#H# Check test coverage and create HTMl report
 cover_db_html: cover_db
 	cover -report html -outputdir cover_db_html cover_db
+
+#H# Show help for main make targets
+help:
+	@sed -n  -e '/^#H#/ {N'\
+		-e 's/^#H# \(.*\)\n\([a-z0-9_-]*\):.*/\2 \1/p'\
+		-e '}' <Makefile | sort --key=2 | while read target txt;\
+	do \
+		printf "%-20s: %s\n" "$$target" "$$txt"; \
+	done
-- 
1.7.3.98.g5ad7d

Re: [PATCH] Makefile: implement help target

[Sverre Rabbelier]

Heya,

On Tue, Sep 28, 2010 at 16:44, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> with automatic help text collection from lines starting with "#H# " and
> preceding a make target.

I don't know about the "#H#" in particular, but documenting what each
target does is a Good Thing (tm) in the first place, re-using that
documentation for 'make help' is even better.

> We could sort differently, of course, or at a category key (build, doc, etc.)

I think just sorting alphabetically would be a good start. Maybe pipe
the whole thing through sort?

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Makefile: implement help target

[Ævar Arnfjörð Bjarmason]

On Tue, Sep 28, 2010 at 14:44, Michael J Gruber
<git@drmicha.warpmail.net> wrote:

> +#H# Check test coverage and create HTMl report

HTML, not HTMl

>  cover_db_html: cover_db
>        cover -report html -outputdir cover_db_html cover_db
> +
> +#H# Show help for main make targets

How about something less opaque, like "# Help: Show help [...]" or "#
About:". It would serve the same purpose as #H#, without the reader
wondering what that odd string means.

> +help:
> +       @sed -n  -e '/^#H#/ {N'\
> +               -e 's/^#H# \(.*\)\n\([a-z0-9_-]*\):.*/\2 \1/p'\
> +               -e '}' <Makefile | sort --key=2 | while read target txt;\
> +       do \
> +               printf "%-20s: %s\n" "$$target" "$$txt"; \
> +       done

Looks good, but --key=2 isn't in POSIX.

Re: [PATCH] Makefile: implement help target

[Zbyszek Szmek]

Hi,
the original output (divided into documentation, building, cleaning, etc.)
seems to be much more readable. Maybe a sort key could be added to the
begging of the help message and then stripped before output?
Something like:
  # Help: Building: compile everything
  all:
  
  # Help: Cleaning: remove things
  clean:

Best,
Zbyszek

Re: [PATCH] Makefile: implement help target

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> How's this for a version without maintenance issues?

Something along these lines would be closer to what I had in mind,
actually.

Traditionally a multi-line sed command embed in Makefile has been
portability nightmare, which is a bit worrysome.

Isn't there a "makedoc" ala "perldoc" or "javadoc", by the way?

> ...
> +#H# Show help for main make targets
> +help:
> +	@sed -n  -e '/^#H#/ {N'\
> +		-e 's/^#H# \(.*\)\n\([a-z0-9_-]*\):.*/\2 \1/p'\
> +		-e '}' <Makefile | sort --key=2 | while read target txt;\
> +	do \
> +		printf "%-20s: %s\n" "$$target" "$$txt"; \
> +	done
> -- 
> 1.7.3.98.g5ad7d

Re: [PATCH] Makefile: implement help target

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 28.09.2010 17:33:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> How's this for a version without maintenance issues?
> 
> Something along these lines would be closer to what I had in mind,
> actually.
> 
> Traditionally a multi-line sed command embed in Makefile has been
> portability nightmare, which is a bit worrysome.

Yes, but I thought for "make help" it's not such problem if it works on
most platforms only - others can read inline ;)

If portability is an issue one can work around it - is "grep -A 1"
portable? I'd also have to get rid of sort --key=2.

> Isn't there a "makedoc" ala "perldoc" or "javadoc", by the way?

There is a "makedoc" but that's something different...

Michael

Re: [PATCH] Makefile: implement help target

[Ævar Arnfjörð Bjarmason]

On Tue, Sep 28, 2010 at 15:47, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> If portability is an issue one can work around it - is "grep -A 1"
> portable? I'd also have to get rid of sort --key=2.

No says http://man.cx/grep(1posix)

On the other hand I don't think portability is that important here.

But if you want to make it portable using awk to do most of the work
is probably easiest.

[PATCHv2] Makefile: implement help target

[Michael J Gruber]

with automatic help text collection from lines starting with "# Help: " and
preceding a make target.

Suggested-by: Stephen Boyd <bebarino@gmail.com>
Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
Now how's this for portability and such? New output:

Build targets:
    all:                Build the Git suite
    dist:               Build git-$(GIT_VERSION).tar.gz source
    dist-doc:           Build $(manpages).tar.gz and $(htmldocs).tar.gz
    doc:                Build man pages and HTML docs
    html:               Build HTML doc
    info:               Build info docs
    man:                Build man pages
    pdf:                Build PDF docs
    rpm:                Build source and binary RPM packages
Clean targets:
    clean:              Remove generated files but keep the configure script
    distclean:          Remove generated files and the configure script
Develop targets:
    cscope:             Generate cscope index
    tags:               Generate tags using ctags
    TAGS:               Generate tags using etags
Help targets:
    help:               Show help for main make targets
Install targets:
    install-doc:        Install man pages
    install-html:       Install HTML docs
    install-info:       Install info docs
    install:            Install the Git suite
    install-man:        Install man pages
    install-pdf:        Install PDF docs
    quick-install-doc:  Install pregenerated man pages from origin/man
    quick-install-html: Install pregenerated HTML pages from origin/html
    quick-install-man:  Install pregenerated man pages from origin/man
Test targets:
    check-docs:         Check documentation coverage
    coverage:           Check test coverage
    cover_db_html:      Check test coverage and create HTML report
    test:               Check the build by running the test suite

 Makefile |   43 +++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index db2efd6..497dd92 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
 # The default target of this Makefile is...
+# Help: Build: Build the Git suite
 all::
 
 # Define V=1 to have a more verbose compile.
@@ -1952,29 +1953,37 @@ $(XDIFF_LIB): $(XDIFF_OBJS)
 $(VCSSVN_LIB): $(VCSSVN_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)
 
+# Help: Build: Build man pages and HTML docs
 doc:
 	$(MAKE) -C Documentation all
 
+# Help: Build: Build man pages
 man:
 	$(MAKE) -C Documentation man
 
+# Help: Build: Build HTML doc
 html:
 	$(MAKE) -C Documentation html
 
+# Help: Build: Build info docs
 info:
 	$(MAKE) -C Documentation info
 
+# Help: Build: Build PDF docs
 pdf:
 	$(MAKE) -C Documentation pdf
 
+# Help: Develop: Generate tags using etags
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
 
+# Help: Develop: Generate tags using ctags
 tags:
 	$(RM) tags
 	$(FIND) . -name '*.[hcS]' -print | xargs ctags -a
 
+# Help: Develop: Generate cscope index
 cscope:
 	$(RM) cscope*
 	$(FIND) . -name '*.[hcS]' -print | xargs cscope -b
@@ -2040,6 +2049,7 @@ export NO_SVN_TESTS
 
 ### Testing rules
 
+# Help: Test: Check the build by running the test suite
 test: all
 	$(MAKE) -C t/ all
 
@@ -2099,6 +2109,7 @@ export gitexec_instdir
 
 install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)
 
+# Help: Install: Install the Git suite
 install: all
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'
@@ -2155,27 +2166,35 @@ endif
 install-gitweb:
 	$(MAKE) -C gitweb install
 
+# Help: Install: Install man pages
 install-doc:
 	$(MAKE) -C Documentation install
 
+# Help: Install: Install man pages
 install-man:
 	$(MAKE) -C Documentation install-man
 
+# Help: Install: Install HTML docs
 install-html:
 	$(MAKE) -C Documentation install-html
 
+# Help: Install: Install info docs
 install-info:
 	$(MAKE) -C Documentation install-info
 
+# Help: Install: Install PDF docs
 install-pdf:
 	$(MAKE) -C Documentation install-pdf
 
+# Help: Install: Install pregenerated man pages from origin/man
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
+# Help: Install: Install pregenerated man pages from origin/man
 quick-install-man:
 	$(MAKE) -C Documentation quick-install-man
 
+# Help: Install: Install pregenerated HTML pages from origin/html
 quick-install-html:
 	$(MAKE) -C Documentation quick-install-html
 
@@ -2188,6 +2207,7 @@ git.spec: git.spec.in
 	mv $@+ $@
 
 GIT_TARNAME=git-$(GIT_VERSION)
+# Help: Build: Build git-$(GIT_VERSION).tar.gz source
 dist: git.spec git-archive$(X) configure
 	./git-archive --format=tar \
 		--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar
@@ -2203,6 +2223,7 @@ dist: git.spec git-archive$(X) configure
 	@$(RM) -r $(GIT_TARNAME)
 	gzip -f -9 $(GIT_TARNAME).tar
 
+# Help: Build: Build source and binary RPM packages
 rpm: dist
 	$(RPMBUILD) \
 		--define "_source_filedigest_algorithm md5" \
@@ -2211,6 +2232,8 @@ rpm: dist
 
 htmldocs = git-htmldocs-$(GIT_VERSION)
 manpages = git-manpages-$(GIT_VERSION)
+
+# Help: Build: Build $(manpages).tar.gz and $(htmldocs).tar.gz
 dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir .doc-tmp-dir
@@ -2230,10 +2253,11 @@ dist-doc:
 	$(RM) -r .doc-tmp-dir
 
 ### Cleaning rules
-
+# Help: Clean: Remove generated files and the configure script
 distclean: clean
 	$(RM) configure
 
+# Help: Clean: Remove generated files but keep the configure script
 clean:
 	$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \
 		builtin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)
@@ -2268,7 +2292,7 @@ endif
 .PHONY: FORCE TAGS tags cscope
 
 ### Check documentation
-#
+# Help: Test: Check documentation coverage
 check-docs::
 	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \
 	do \
@@ -2335,6 +2359,7 @@ check-builtins::
 #
 .PHONY: coverage coverage-clean coverage-build coverage-report
 
+# Help: Test: Check test coverage
 coverage:
 	$(MAKE) coverage-build
 	$(MAKE) coverage-report
@@ -2370,5 +2395,19 @@ coverage-untested-functions: coverage-report
 cover_db: coverage-report
 	gcov2perl -db cover_db *.gcov
 
+# Help: Test: Check test coverage and create HTML report
 cover_db_html: cover_db
 	cover -report html -outputdir cover_db_html cover_db
+
+# Help: Help: Show help for main make targets
+help:
+	@awk '/^# Help:/ { l=substr($$0,8); \
+		getline; \
+		j=index(l,":"); \
+		print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
+		}' <Makefile | sort | while read category target text; \
+	do \
+		test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
+		currcat="$$category"; \
+		printf "    %-20s%s\n" "$$target" "$$text"; \
+	done
-- 
1.7.3.98.g5ad7d

Re: [PATCHv2] Makefile: implement help target

[Sverre Rabbelier]

Heya,

On Tue, Sep 28, 2010 at 22:38, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Now how's this for portability and such?

I applaud your leet awk skills :).

> Clean targets:
>    clean:              Remove generated files but keep the configure script
>    distclean:          Remove generated files and the configure script
> Develop targets:
>    cscope:             Generate cscope index
>    tags:               Generate tags using ctags
>    TAGS:               Generate tags using etags

Perhaps an extra newline after the end of a category? Otherwise, looks nice.

I haven't looked at the awk script itself wrt portability though.

-- 
Cheers,

Sverre Rabbelier

Re: [PATCHv2] Makefile: implement help target

[Jakub Narebski]

I'm sorry for duplicated post; I made mistake that made vger anti-SPAM
filter stop it.

Michael J Gruber <git@drmicha.warpmail.net> writes:

> with automatic help text collection from lines starting with "# Help: " and
> preceding a make target.
> 
> Suggested-by: Stephen Boyd <bebarino@gmail.com>
> Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> Now how's this for portability and such? New output:
> 
> Build targets:
>     all:                Build the Git suite
>     dist:               Build git-$(GIT_VERSION).tar.gz source
>     dist-doc:           Build $(manpages).tar.gz and $(htmldocs).tar.gz
>     doc:                Build man pages and HTML docs
>     html:               Build HTML doc
>     info:               Build info docs
>     man:                Build man pages
>     pdf:                Build PDF docs
>     rpm:                Build source and binary RPM packages
> Clean targets:
>     clean:              Remove generated files but keep the configure script
>     distclean:          Remove generated files and the configure script
[...]

Shouldn't some excerpt of this be put in the commit message as example
output fragment?


>  Makefile |   43 +++++++++++++++++++++++++++++++++++++++++--
>  1 files changed, 41 insertions(+), 2 deletions(-)
> 
> diff --git a/Makefile b/Makefile
> index db2efd6..497dd92 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1,4 +1,5 @@
>  # The default target of this Makefile is...
> +# Help: Build: Build the Git suite
>  all::
[...]

>  ### Testing rules

Why can't you use existing headers in Makefile, like the one above, to
divide list of targets in "make help" output into categories of
targets?

> +
> +# Help: Help: Show help for main make targets
> +help:
> +	@awk '/^# Help:/ { l=substr($$0,8); \

Doesn't it need to be $(AWK) not awk?

> +		getline; \
> +		j=index(l,":"); \
> +		print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
> +		}' <Makefile | sort | while read category target text; \
> +	do \
> +		test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
> +		currcat="$$category"; \
> +		printf "    %-20s%s\n" "$$target" "$$text"; \
> +	done
> -- 
> 1.7.3.98.g5ad7d
> 

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCHv2] Makefile: implement help target

[Brandon Casey]

On 09/28/2010 03:38 PM, Michael J Gruber wrote:
> with automatic help text collection from lines starting with "# Help: " and
> preceding a make target.
> 
> Suggested-by: Stephen Boyd <bebarino@gmail.com>
> Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> Now how's this for portability and such? New output:
> 
> Build targets:
>     all:                Build the Git suite
>     dist:               Build git-$(GIT_VERSION).tar.gz source
>     dist-doc:           Build $(manpages).tar.gz and $(htmldocs).tar.gz
<snip>

>  Makefile |   43 +++++++++++++++++++++++++++++++++++++++++--
>  1 files changed, 41 insertions(+), 2 deletions(-)


Very nice.  Too bad we have more targets than fit in my 33-line terminal.

/bikeshed

How about this micro-tweak:

  1) Remove the colon from the targets so they sort correctly.
     i.e. so "dist" sorts before "dist-doc" and "install" sorts
          before "install-*"
  2) Add " - " prefix to description strings and reduce target
     width accordingly so we still have just as much room for
     the description string.

So the output looks like this:

Build targets:
    all                - Build the Git suite
    dist               - Build git-$(GIT_VERSION).tar.gz source
    dist-doc           - Build $(manpages).tar.gz and $(htmldocs).tar.gz
    doc                - Build man pages and HTML docs
    html               - Build HTML doc
    info               - Build info docs
    man                - Build man pages
    pdf                - Build PDF docs
    rpm                - Build source and binary RPM packages
Clean targets:
    clean              - Remove generated files but keep the configure script
    distclean          - Remove generated files and the configure script
Develop targets:
    TAGS               - Generate tags using etags
    cscope             - Generate cscope index
    tags               - Generate tags using ctags
Help targets:
    help               - Show help for main make targets
Install targets:
    install            - Install the Git suite
    install-doc        - Install man pages
    install-html       - Install HTML docs
    install-info       - Install info docs
    install-man        - Install man pages
    install-pdf        - Install PDF docs
    quick-install-doc  - Install pregenerated man pages from origin/man
    quick-install-html - Install pregenerated HTML pages from origin/html
    quick-install-man  - Install pregenerated man pages from origin/man
Test targets:
    check-docs         - Check documentation coverage
    cover_db_html      - Check test coverage and create HTML report
    coverage           - Check test coverage
    test               - Check the build by running the test suite


(Warning: copy/pasted):

diff --git a/Makefile b/Makefile
index c7f0bb7..2803aa1 100644
--- a/Makefile
+++ b/Makefile
@@ -2398,10 +2398,10 @@ help:
        @awk '/^# Help:/ { l=substr($$0,8); \
                getline; \
                j=index(l,":"); \
-               print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
+               print substr(l,1,j-1), substr($$0,1,index($$0,":")-1), substr(l,j+2); \
                }' <Makefile | sort | while read category target text; \
        do \
                test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
                currcat="$$category"; \
-               printf "    %-20s%s\n" "$$target" "$$text"; \
+               printf "    %-18s - %s\n" "$$target" "$$text"; \
        done


Oh, by the way, tested and works on Solaris 10 and IRIX 6.5.

-Brandon

Re: [PATCHv2] Makefile: implement help target

[Jeff King]

On Tue, Sep 28, 2010 at 10:38:04PM +0200, Michael J Gruber wrote:

> +help:
> +	@awk '/^# Help:/ { l=substr($$0,8); \
> +		getline; \
> +		j=index(l,":"); \
> +		print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
> +		}' <Makefile | sort | while read category target text; \
> +	do \
> +		test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
> +		currcat="$$category"; \
> +		printf "    %-20s%s\n" "$$target" "$$text"; \
> +	done

Surely this is why we have perl?

help:
	@perl -n0777 \
	  -e 'push @{$$h{$$1}}, [$$3, $$2] while /^# Help: (.*?): (.*)\n(.*?):/mg;' \
	  -e 'for (sort keys(%h)) {' \
	  -e '  print "$$_:\n";' \
	  -e '  printf("    %-20s%s\n", @$$_) for (@{$$h{$$_}});' \
	  -e '}' Makefile

Note that mine will actually print the targets in a heading in the order
in which they appear in the Makefile, which I consider slightly more
useful (especially in that we can tweak the order easily). It would also
be easy to sort the headers in some more meaningful way, but here I just
did it lexically.

-Peff

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.

Re: [PATCHv2] Makefile: implement help target

[Michael J Gruber]

Jeff King venit, vidit, dixit 29.09.2010 07:16:
> On Tue, Sep 28, 2010 at 10:38:04PM +0200, Michael J Gruber wrote:
> 
>> +help:
>> +	@awk '/^# Help:/ { l=substr($$0,8); \
>> +		getline; \
>> +		j=index(l,":"); \
>> +		print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
>> +		}' <Makefile | sort | while read category target text; \
>> +	do \
>> +		test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
>> +		currcat="$$category"; \
>> +		printf "    %-20s%s\n" "$$target" "$$text"; \
>> +	done
> 
> Surely this is why we have perl?

I don't speak perl.

Honestly, this is slowly going on my nerves. Maybe it's because I'm
reading too many "can't we do it this way" responses in one go and
without being coffeinated, and without seeing how "different" is better.
[I've been heeding all advise on portability and readability, as you can
see.]

So far we've been using neither awk nor perl in the Makefile, but sed.

> help:
> 	@perl -n0777 \
> 	  -e 'push @{$$h{$$1}}, [$$3, $$2] while /^# Help: (.*?): (.*)\n(.*?):/mg;' \

On top of everything else, you're even slashing mg! (See, I'm less
grumpy already...)

> 	  -e 'for (sort keys(%h)) {' \
> 	  -e '  print "$$_:\n";' \
> 	  -e '  printf("    %-20s%s\n", @$$_) for (@{$$h{$$_}});' \
> 	  -e '}' Makefile
> 

How portable are the regexps and the array/dictionary push?

> Note that mine will actually print the targets in a heading in the order
> in which they appear in the Makefile, which I consider slightly more
> useful (especially in that we can tweak the order easily).

I don't think Makefile order would be useful. If you know exactly what
you're looking for you need no sorting, you can just search for that
term. (I would do a 'grep -A20 "^target:" Makefile' or hit "/^target" in
my vim but I'm sure there's a different way of doing it in perl...)

If you're trying to find your way around you guess a generic term and
look for that, and that's easier to do when the categories are sorted
alphabetically.

Michael

Re: [PATCHv2] Makefile: implement help target

[Jeff King]

On Wed, Sep 29, 2010 at 09:03:35AM +0200, Michael J Gruber wrote:

> > Surely this is why we have perl?
> 
> I don't speak perl.
> 
> Honestly, this is slowly going on my nerves. Maybe it's because I'm
> reading too many "can't we do it this way" responses in one go and
> without being coffeinated, and without seeing how "different" is better.
> [I've been heeding all advise on portability and readability, as you can
> see.]

I should have been more clear about my motivations. It was mainly "I
wonder how short I can make this in perl?" The alternate sorting was
something that happened incidentally, though it did make more sense to
me.

So you can just ignore me if you like. :)

> > 	  -e 'for (sort keys(%h)) {' \
> > 	  -e '  print "$$_:\n";' \
> > 	  -e '  printf("    %-20s%s\n", @$$_) for (@{$$h{$$_}});' \
> > 	  -e '}' Makefile
> > 
> 
> How portable are the regexps and the array/dictionary push?

AFAIK, it should work with any perl5. I don't have any ancient versions
handy to test these days, though.

> > Note that mine will actually print the targets in a heading in the order
> > in which they appear in the Makefile, which I consider slightly more
> > useful (especially in that we can tweak the order easily).
> 
> I don't think Makefile order would be useful. If you know exactly what
> you're looking for you need no sorting, you can just search for that
> term. (I would do a 'grep -A20 "^target:" Makefile' or hit "/^target" in
> my vim but I'm sure there's a different way of doing it in perl...)

What I was trying to say was more that alphabetical is not necessarily
the most useful order to present things in the help screen. Probably
there is some hand-selected order that presents the entries in the least
confusing way. And one way of representing that is to have the topics in
that order in the Makefile, which in theory probably makes reading the
Makefile itself simpler.

But yeah, this is way over-thinking the issue. It's a fricking list of
Makefile targets. I am happy with your original patch.

-Peff

Re: [PATCHv2] Makefile: implement help target

[Michael J Gruber]

Brandon Casey venit, vidit, dixit 29.09.2010 00:00:
> On 09/28/2010 03:38 PM, Michael J Gruber wrote:
>> with automatic help text collection from lines starting with "# Help: " and
>> preceding a make target.
>>
>> Suggested-by: Stephen Boyd <bebarino@gmail.com>
>> Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> Now how's this for portability and such? New output:
>>
>> Build targets:
>>     all:                Build the Git suite
>>     dist:               Build git-$(GIT_VERSION).tar.gz source
>>     dist-doc:           Build $(manpages).tar.gz and $(htmldocs).tar.gz
> <snip>
> 
>>  Makefile |   43 +++++++++++++++++++++++++++++++++++++++++--
>>  1 files changed, 41 insertions(+), 2 deletions(-)
> 
> 
> Very nice.  Too bad we have more targets than fit in my 33-line terminal.
> 
> /bikeshed
> 
> How about this micro-tweak:
> 
>   1) Remove the colon from the targets so they sort correctly.
>      i.e. so "dist" sorts before "dist-doc" and "install" sorts
>           before "install-*"
>   2) Add " - " prefix to description strings and reduce target
>      width accordingly so we still have just as much room for
>      the description string.
> 
> So the output looks like this:
> 
....
> Install targets:
>     install            - Install the Git suite
>     install-doc        - Install man pages
>     install-html       - Install HTML docs
>     install-info       - Install info docs
>     install-man        - Install man pages
>     install-pdf        - Install PDF docs
>     quick-install-doc  - Install pregenerated man pages from origin/man
>     quick-install-html - Install pregenerated HTML pages from origin/html
>     quick-install-man  - Install pregenerated man pages from origin/man

Sounds good, although the sort order depends on the locale. "LANG=C
sort" takes care of that.

> Oh, by the way, tested and works on Solaris 10 and IRIX 6.5.

Thanks!
Michael

Re: [PATCHv2] Makefile: implement help target

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> What I was trying to say was more that alphabetical is not necessarily
> the most useful order to present things in the help screen. Probably
> there is some hand-selected order that presents the entries in the least
> confusing way. And one way of representing that is to have the topics in
> that order in the Makefile, which in theory probably makes reading the
> Makefile itself simpler.

I agree with this, even though I do not feel _too_ strongly about it.

By the way, while we are at adding "make help" support...

With help annotations in the Makefile like this:

        # Help: install everything
        # - the user visible commands go to $(bindir)
        # - helper programs go to $(gitexec_instdir)
        # - templates go to $(template_instdir)
        install: all
                $(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'

I imagine it would be really cool if "make help" said something like this:

    $ make help
    ...
    install:
      install everything
      - the user visible commands go to $(bindir) = /home/junio/bin
      - helper commands go to $(gitexec_instdir) = /home/junio/libexec/git-core
      - templates go to $(template_instdir) = /home/junio/share/git-core/templates

to help the builder figuring out what make variable(s) to tweak.  To be useful,
I think you would need to show the expansion, though.  E.g.

    - the user visible commands go to $(bindir) = /home/junio/bin
        bindir = $(prefix)/$(bindir_relative)
        prefix = $HOME
        HOME = /home/junio
        bindir_relative = bin

But again, I do not feel strongly about it either.

[PATCHv3] Makefile: implement help target

[Michael J Gruber]

with automatic help text collection from "help-X::" targets, where X
denotes a category for the target. This has the advantage (over a
comment based solution) that we can use make's variable expansion inside
the help text. Further exploitation of this feature is left for a future
patch.

With this, "make help" produces:

Help:
    help               - Show help for main make targets
    help-X             - Show help for category X (Build, Test, Install, Clean, Develop)
Build Git and the documentation:
    all                - Build the Git suite
    doc                - Build man pages and HTML docs
    man                - Build man pages
    html               - Build HTML doc
    info               - Build info docs
    pdf                - Build PDF docs
    dist               - Build git-1.7.3.99.gacf23.dirty.tar.gz source archive
    rpm                - Build source and binary RPM packages
    dist-doc           - Build git-manpages-1.7.3.99.gacf23.dirty.tar.gz and git-htmldocs-1.7.3.99.gacf23.dirty.tar.gz
Testing source and build:
    test               - Check the build by running the test suite
    check-docs         - Check documentation coverage
    coverage           - Check test coverage
    cover_db_html      - Check test coverage and create HTML report
Installing the Git suite and documentation:
    install            - Install the Git suite
    install-doc        - Install man pages
    install-man        - Install man pages
    install-html       - Install HTML docs
    install-info       - Install info docs
    install-pdf        - Install PDF docs
    quick-install-doc  - Install pregenerated man pages from origin/man
    quick-install-man  - Install pregenerated man pages from origin/man
    quick-install-html - Install pregenerated HTML pages from origin/html
Cleaning up after a build:
    distclean          - Remove generated files and the configure script
    clean              - Remove generated files but keep the configure script
Making development easier:
    TAGS               - Generate tags using etags
    tags               - Generate tags using ctags
    cscope             - Generate cscope index

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
Does it seem as if I can't let this go?

Anyhow, here's a make based variant which is a bit more chatty in the Makefile
itself but has a ton of advantages, such as make variable expansion. Making
good use of this for the install targets is left for another patch.

 Makefile |  109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 108 insertions(+), 1 deletions(-)

diff --git a/Makefile b/Makefile
index db2efd6..371214d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,10 @@
 # The default target of this Makefile is...
+help-Build::
+	$(H) 'Build Git and the documentation'
+
+help-Build::
+	$(HH) all 'Build the Git suite'
+
 all::
 
 # Define V=1 to have a more verbose compile.
@@ -1952,29 +1958,56 @@ $(XDIFF_LIB): $(XDIFF_OBJS)
 $(VCSSVN_LIB): $(VCSSVN_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)
 
+help-Build::
+	$(HH) doc 'Build man pages and HTML docs'
+
 doc:
 	$(MAKE) -C Documentation all
 
+help-Build::
+	$(HH) man 'Build man pages'
+
 man:
 	$(MAKE) -C Documentation man
 
+help-Build::
+	$(HH) html 'Build HTML doc'
+
 html:
 	$(MAKE) -C Documentation html
 
+help-Build::
+	$(HH) info 'Build info docs'
+
 info:
 	$(MAKE) -C Documentation info
 
+help-Build::
+	$(HH) pdf 'Build PDF docs'
+
 pdf:
 	$(MAKE) -C Documentation pdf
 
+help-Develop::
+	$(H) 'Making development easier'
+
+help-Develop::
+	$(HH) TAGS 'Generate tags using etags'
+
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
 
+help-Develop::
+	$(HH) tags 'Generate tags using ctags'
+
 tags:
 	$(RM) tags
 	$(FIND) . -name '*.[hcS]' -print | xargs ctags -a
 
+help-Develop::
+	$(HH) cscope 'Generate cscope index'
+
 cscope:
 	$(RM) cscope*
 	$(FIND) . -name '*.[hcS]' -print | xargs cscope -b
@@ -2040,6 +2073,12 @@ export NO_SVN_TESTS
 
 ### Testing rules
 
+help-Test::
+	$(H) 'Testing source and build'
+
+help-Test::
+	$(HH) test 'Check the build by running the test suite'
+
 test: all
 	$(MAKE) -C t/ all
 
@@ -2099,6 +2138,12 @@ export gitexec_instdir
 
 install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)
 
+help-Install::
+	$(H) 'Installing the Git suite and documentation'
+
+help-Install::
+	$(HH) install 'Install the Git suite'
+
 install: all
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'
@@ -2155,27 +2200,51 @@ endif
 install-gitweb:
 	$(MAKE) -C gitweb install
 
+help-Install::
+	$(HH) install-doc 'Install man pages'
+
 install-doc:
 	$(MAKE) -C Documentation install
 
+help-Install::
+	$(HH) install-man 'Install man pages'
+
 install-man:
 	$(MAKE) -C Documentation install-man
 
+help-Install::
+	$(HH) install-html 'Install HTML docs'
+
 install-html:
 	$(MAKE) -C Documentation install-html
 
+help-Install::
+	$(HH) install-info 'Install info docs'
+
 install-info:
 	$(MAKE) -C Documentation install-info
 
+help-Install::
+	$(HH) install-pdf 'Install PDF docs'
+
 install-pdf:
 	$(MAKE) -C Documentation install-pdf
 
+help-Install::
+	$(HH) quick-install-doc 'Install pregenerated man pages from origin/man'
+
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
+help-Install::
+	$(HH) quick-install-man 'Install pregenerated man pages from origin/man'
+
 quick-install-man:
 	$(MAKE) -C Documentation quick-install-man
 
+help-Install::
+	$(HH) quick-install-html 'Install pregenerated HTML pages from origin/html'
+
 quick-install-html:
 	$(MAKE) -C Documentation quick-install-html
 
@@ -2188,6 +2257,9 @@ git.spec: git.spec.in
 	mv $@+ $@
 
 GIT_TARNAME=git-$(GIT_VERSION)
+help-Build::
+	$(HH) dist 'Build git-$(GIT_VERSION).tar.gz source archive'
+
 dist: git.spec git-archive$(X) configure
 	./git-archive --format=tar \
 		--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar
@@ -2203,6 +2275,9 @@ dist: git.spec git-archive$(X) configure
 	@$(RM) -r $(GIT_TARNAME)
 	gzip -f -9 $(GIT_TARNAME).tar
 
+help-Build::
+	$(HH) rpm 'Build source and binary RPM packages'
+
 rpm: dist
 	$(RPMBUILD) \
 		--define "_source_filedigest_algorithm md5" \
@@ -2211,6 +2286,10 @@ rpm: dist
 
 htmldocs = git-htmldocs-$(GIT_VERSION)
 manpages = git-manpages-$(GIT_VERSION)
+
+help-Build::
+	$(HH) dist-doc 'Build $(manpages).tar.gz and $(htmldocs).tar.gz'
+
 dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir .doc-tmp-dir
@@ -2230,10 +2309,18 @@ dist-doc:
 	$(RM) -r .doc-tmp-dir
 
 ### Cleaning rules
+help-Clean::
+	$(H) 'Cleaning up after a build'
+
+help-Clean::
+	$(HH) distclean 'Remove generated files and the configure script'
 
 distclean: clean
 	$(RM) configure
 
+help-Clean::
+	$(HH) clean 'Remove generated files but keep the configure script'
+
 clean:
 	$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \
 		builtin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)
@@ -2268,7 +2355,9 @@ endif
 .PHONY: FORCE TAGS tags cscope
 
 ### Check documentation
-#
+help-Test::
+	$(HH) check-docs 'Check documentation coverage'
+
 check-docs::
 	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \
 	do \
@@ -2335,6 +2424,9 @@ check-builtins::
 #
 .PHONY: coverage coverage-clean coverage-build coverage-report
 
+help-Test::
+	$(HH) coverage 'Check test coverage'
+
 coverage:
 	$(MAKE) coverage-build
 	$(MAKE) coverage-report
@@ -2370,5 +2462,20 @@ coverage-untested-functions: coverage-report
 cover_db: coverage-report
 	gcov2perl -db cover_db *.gcov
 
+help-Test::
+	$(HH) cover_db_html 'Check test coverage and create HTML report'
+
 cover_db_html: cover_db
 	cover -report html -outputdir cover_db_html cover_db
+
+H=@printf "%s:\n"
+HH=@printf "    %-18s - %s\n"
+
+help-Help::
+	$(H) Help
+
+help-Help::
+	$(HH) help 'Show help for main make targets'
+	$(HH) help-X 'Show help for category X (Build, Test, Install, Clean, Develop)'
+
+help: help-Help help-Build help-Test help-Install help-Clean help-Develop
-- 
1.7.3.98.g5ad7d

Re: [PATCHv3] Makefile: implement help target

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> diff --git a/Makefile b/Makefile
> index db2efd6..371214d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1,4 +1,10 @@
>  # The default target of this Makefile is...
> +help-Build::

Heh, no way.  The default target of this Makefile should remain "all".

Even though letting phony double-colon rules to implicitly collect members
of groups and showing them is a neat idea, I do not think "make -j help"
would do what you are expecting ;-)

Re: [PATCHv3] Makefile: implement help target

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 09/29/2010 10:39 PM:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> diff --git a/Makefile b/Makefile
>> index db2efd6..371214d 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -1,4 +1,10 @@
>>  # The default target of this Makefile is...
>> +help-Build::
> 
> Heh, no way.  The default target of this Makefile should remain "all".

Damnit, that wasn't intended.... But that's solved by a simple
reordering, of course.

> Even though letting phony double-colon rules to implicitly collect members
> of groups and showing them is a neat idea, I do not think "make -j help"
> would do what you are expecting ;-)

I expect a randomly ordered mess, and "make -j help" fully meets those
expectations! Can "-j" be set in the environment or config.mak somehow?
Otherwise I think that explicitly shooting yourself in the foot should
be allowed...

Anyway, this topic is (only) about help on our Makefile, and I think
that as long as we don't want to go several extra miles, we have to
decide between two app roaches :)

* comment based:
  + readable
  + -j safe
  - no var expansion (that I know of, at least without recursive make)
  +- single line comments (unless more perl/awk foo is invested)
  +- either in Makefile order or lexically sorted (or more perl lines)

* phony :: rules based:
  +- somewhat less readable
  - not -j safe
  + var expansion
  + multi line comments (could easily add a 3rd level also)
  + categories can be ordered freely (targets in Makefile order within)

Michael