* [PATCH] Makefile: Add help target @ 2010-09-28 8:13 Stephen Boyd 2010-09-28 9:45 ` Junio C Hamano 0 siblings, 1 reply; 24+ messages in thread From: Stephen Boyd @ 2010-09-28 8:13 UTC (permalink / raw) To: git; +Cc: Junio C Hamano 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 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: Add help target 2010-09-28 8:13 [PATCH] Makefile: Add help target Stephen Boyd @ 2010-09-28 9:45 ` Junio C Hamano 2010-09-28 11:37 ` Sverre Rabbelier 2010-09-29 6:10 ` [PATCH] Makefile: Add " yj2133011 0 siblings, 2 replies; 24+ messages in thread From: Junio C Hamano @ 2010-09-28 9:45 UTC (permalink / raw) To: Stephen Boyd; +Cc: git 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: Add help target 2010-09-28 9:45 ` Junio C Hamano @ 2010-09-28 11:37 ` Sverre Rabbelier 2010-09-28 12:35 ` Andreas Ericsson 2010-09-29 6:10 ` [PATCH] Makefile: Add " yj2133011 1 sibling, 1 reply; 24+ messages in thread From: Sverre Rabbelier @ 2010-09-28 11:37 UTC (permalink / raw) To: Junio C Hamano; +Cc: Stephen Boyd, git 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: Add help target 2010-09-28 11:37 ` Sverre Rabbelier @ 2010-09-28 12:35 ` Andreas Ericsson 2010-09-28 14:44 ` [PATCH] Makefile: implement " Michael J Gruber 0 siblings, 1 reply; 24+ messages in thread From: Andreas Ericsson @ 2010-09-28 12:35 UTC (permalink / raw) To: Sverre Rabbelier; +Cc: Junio C Hamano, Stephen Boyd, git 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCH] Makefile: implement help target 2010-09-28 12:35 ` Andreas Ericsson @ 2010-09-28 14:44 ` Michael J Gruber 2010-09-28 14:48 ` Sverre Rabbelier ` (2 more replies) 0 siblings, 3 replies; 24+ messages in thread From: Michael J Gruber @ 2010-09-28 14:44 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier 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 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 14:44 ` [PATCH] Makefile: implement " Michael J Gruber @ 2010-09-28 14:48 ` Sverre Rabbelier 2010-09-28 14:57 ` Zbyszek Szmek 2010-09-28 14:54 ` Ævar Arnfjörð Bjarmason 2010-09-28 15:33 ` Junio C Hamano 2 siblings, 1 reply; 24+ messages in thread From: Sverre Rabbelier @ 2010-09-28 14:48 UTC (permalink / raw) To: Michael J Gruber; +Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 14:48 ` Sverre Rabbelier @ 2010-09-28 14:57 ` Zbyszek Szmek 0 siblings, 0 replies; 24+ messages in thread From: Zbyszek Szmek @ 2010-09-28 14:57 UTC (permalink / raw) To: Sverre Rabbelier Cc: Michael J Gruber, git, Junio C Hamano, Stephen Boyd, Andreas Ericsson 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 14:44 ` [PATCH] Makefile: implement " Michael J Gruber 2010-09-28 14:48 ` Sverre Rabbelier @ 2010-09-28 14:54 ` Ævar Arnfjörð Bjarmason 2010-09-28 15:33 ` Junio C Hamano 2 siblings, 0 replies; 24+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2010-09-28 14:54 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 14:44 ` [PATCH] Makefile: implement " Michael J Gruber 2010-09-28 14:48 ` Sverre Rabbelier 2010-09-28 14:54 ` Ævar Arnfjörð Bjarmason @ 2010-09-28 15:33 ` Junio C Hamano 2010-09-28 15:47 ` Michael J Gruber 2 siblings, 1 reply; 24+ messages in thread From: Junio C Hamano @ 2010-09-28 15:33 UTC (permalink / raw) To: Michael J Gruber; +Cc: git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 15:33 ` Junio C Hamano @ 2010-09-28 15:47 ` Michael J Gruber 2010-09-28 16:04 ` Ævar Arnfjörð Bjarmason 0 siblings, 1 reply; 24+ messages in thread From: Michael J Gruber @ 2010-09-28 15:47 UTC (permalink / raw) To: Junio C Hamano; +Cc: git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: implement help target 2010-09-28 15:47 ` Michael J Gruber @ 2010-09-28 16:04 ` Ævar Arnfjörð Bjarmason 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber 0 siblings, 1 reply; 24+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2010-09-28 16:04 UTC (permalink / raw) To: Michael J Gruber Cc: Junio C Hamano, git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCHv2] Makefile: implement help target 2010-09-28 16:04 ` Ævar Arnfjörð Bjarmason @ 2010-09-28 20:38 ` Michael J Gruber 2010-09-28 20:51 ` Sverre Rabbelier ` (3 more replies) 0 siblings, 4 replies; 24+ messages in thread From: Michael J Gruber @ 2010-09-28 20:38 UTC (permalink / raw) To: git Cc: Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber @ 2010-09-28 20:51 ` Sverre Rabbelier 2010-09-28 21:24 ` Jakub Narebski ` (2 subsequent siblings) 3 siblings, 0 replies; 24+ messages in thread From: Sverre Rabbelier @ 2010-09-28 20:51 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber 2010-09-28 20:51 ` Sverre Rabbelier @ 2010-09-28 21:24 ` Jakub Narebski 2010-09-28 22:00 ` Brandon Casey 2010-09-29 5:16 ` Jeff King 3 siblings, 0 replies; 24+ messages in thread From: Jakub Narebski @ 2010-09-28 21:24 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber 2010-09-28 20:51 ` Sverre Rabbelier 2010-09-28 21:24 ` Jakub Narebski @ 2010-09-28 22:00 ` Brandon Casey 2010-09-29 8:06 ` Michael J Gruber 2010-09-29 5:16 ` Jeff King 3 siblings, 1 reply; 24+ messages in thread From: Brandon Casey @ 2010-09-28 22:00 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-28 22:00 ` Brandon Casey @ 2010-09-29 8:06 ` Michael J Gruber 0 siblings, 0 replies; 24+ messages in thread From: Michael J Gruber @ 2010-09-29 8:06 UTC (permalink / raw) To: Brandon Casey Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber ` (2 preceding siblings ...) 2010-09-28 22:00 ` Brandon Casey @ 2010-09-29 5:16 ` Jeff King 2010-09-29 7:03 ` Michael J Gruber 3 siblings, 1 reply; 24+ messages in thread From: Jeff King @ 2010-09-29 5:16 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-29 5:16 ` Jeff King @ 2010-09-29 7:03 ` Michael J Gruber 2010-09-29 7:34 ` Jeff King 0 siblings, 1 reply; 24+ messages in thread From: Michael J Gruber @ 2010-09-29 7:03 UTC (permalink / raw) To: Jeff King Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason, Jakub Narebski 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-29 7:03 ` Michael J Gruber @ 2010-09-29 7:34 ` Jeff King 2010-09-29 15:41 ` Junio C Hamano 0 siblings, 1 reply; 24+ messages in thread From: Jeff King @ 2010-09-29 7:34 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason, Jakub Narebski 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv2] Makefile: implement help target 2010-09-29 7:34 ` Jeff King @ 2010-09-29 15:41 ` Junio C Hamano 2010-09-29 20:15 ` [PATCHv3] " Michael J Gruber 0 siblings, 1 reply; 24+ messages in thread From: Junio C Hamano @ 2010-09-29 15:41 UTC (permalink / raw) To: Jeff King Cc: Michael J Gruber, git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason, Jakub Narebski 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCHv3] Makefile: implement help target 2010-09-29 15:41 ` Junio C Hamano @ 2010-09-29 20:15 ` Michael J Gruber 2010-09-29 20:39 ` Junio C Hamano 0 siblings, 1 reply; 24+ messages in thread From: Michael J Gruber @ 2010-09-29 20:15 UTC (permalink / raw) To: git Cc: Junio C Hamano, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCHv3] Makefile: implement help target 2010-09-29 20:15 ` [PATCHv3] " Michael J Gruber @ 2010-09-29 20:39 ` Junio C Hamano 2010-09-30 7:08 ` Michael J Gruber 0 siblings, 1 reply; 24+ messages in thread From: Junio C Hamano @ 2010-09-29 20:39 UTC (permalink / raw) To: Michael J Gruber Cc: git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ;-) ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCHv3] Makefile: implement help target 2010-09-29 20:39 ` Junio C Hamano @ 2010-09-30 7:08 ` Michael J Gruber 0 siblings, 0 replies; 24+ messages in thread From: Michael J Gruber @ 2010-09-30 7:08 UTC (permalink / raw) To: Junio C Hamano Cc: git, Stephen Boyd, Andreas Ericsson, Sverre Rabbelier, Ævar Arnfjörð Bjarmason 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 ^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH] Makefile: Add help target 2010-09-28 9:45 ` Junio C Hamano 2010-09-28 11:37 ` Sverre Rabbelier @ 2010-09-29 6:10 ` yj2133011 1 sibling, 0 replies; 24+ messages in thread From: yj2133011 @ 2010-09-29 6:10 UTC (permalink / raw) To: git 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. ^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2010-09-30 7:08 UTC | newest] Thread overview: 24+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-09-28 8:13 [PATCH] Makefile: Add help target Stephen Boyd 2010-09-28 9:45 ` Junio C Hamano 2010-09-28 11:37 ` Sverre Rabbelier 2010-09-28 12:35 ` Andreas Ericsson 2010-09-28 14:44 ` [PATCH] Makefile: implement " Michael J Gruber 2010-09-28 14:48 ` Sverre Rabbelier 2010-09-28 14:57 ` Zbyszek Szmek 2010-09-28 14:54 ` Ævar Arnfjörð Bjarmason 2010-09-28 15:33 ` Junio C Hamano 2010-09-28 15:47 ` Michael J Gruber 2010-09-28 16:04 ` Ævar Arnfjörð Bjarmason 2010-09-28 20:38 ` [PATCHv2] " Michael J Gruber 2010-09-28 20:51 ` Sverre Rabbelier 2010-09-28 21:24 ` Jakub Narebski 2010-09-28 22:00 ` Brandon Casey 2010-09-29 8:06 ` Michael J Gruber 2010-09-29 5:16 ` Jeff King 2010-09-29 7:03 ` Michael J Gruber 2010-09-29 7:34 ` Jeff King 2010-09-29 15:41 ` Junio C Hamano 2010-09-29 20:15 ` [PATCHv3] " Michael J Gruber 2010-09-29 20:39 ` Junio C Hamano 2010-09-30 7:08 ` Michael J Gruber 2010-09-29 6:10 ` [PATCH] Makefile: Add " yj2133011
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).