{"thread":{"id":"25266","subject":"[PATCH] Makefile: Add help target","startedAt":"2010-09-28T08:13:58Z","lastAt":"2010-09-30T07:08:21Z","messageCount":24,"participants":["Stephen Boyd","Junio C Hamano","Sverre Rabbelier","Andreas Ericsson","Michael J Gruber","Ævar Arnfjörð Bjarmason","Zbyszek Szmek","Jakub Narebski","Brandon Casey","Jeff King","yj2133011"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"151883","messageId":"1285661638-27741-1-git-send-email-bebarino@gmail.com","threadId":"25266","inReplyTo":null,"subject":"[PATCH] Makefile: Add help target","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2010-09-28T08:13:58Z","receivedAt":"2010-09-28T08:13:58Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"Today I forgot whether the target was quick-install-doc or\ninstall-quick-doc and had to open the Makefile again to find out. I'd\nrather not do that and just use:\n\n\t$ make help\n\nto get a quick summary of the interesting targets when my brain fails to\nrefresh. Add a help target, but don't add uninteresting things like\nstrip, install-gitweb, or targets which alias (install-man).\n\nSigned-off-by: Stephen Boyd \n---\n Makefile | 40 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 40 insertions(+), 0 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex b7a62cf..8c8fcb0 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2366,3 +2366,43 @@ cover_db: coverage-report\n \n cover_db_html: cover_db\n \tcover -report html -outputdir cover_db_html cover_db\n+\n+help:\n+\t@echo 'Cleaning targets:'\n+\t@echo ' clean - Remove generated files but keep the configure script'\n+\t@echo ' distclean - Remove generated files and the configure script'\n+\t@echo\n+\t@echo 'Packaging targets:'\n+\t@echo ' dist - Build git-$(GIT_VERSION).tar.gz source tarball'\n+\t@echo ' rpm - Build source and binary RPM packages'\n+\t@echo ' dist-doc - Build $(manpages).tar.gz and $(htmldocs).tar.gz'\n+\t@echo\n+\t@echo 'Documentation targets:'\n+\t@echo ' doc - Build man pages and HTML docs'\n+\t@echo ' man - Build man pages'\n+\t@echo ' html - Build HTML docs'\n+\t@echo ' info - Build info docs'\n+\t@echo ' pdf - Build PDF docs'\n+\t@echo\n+\t@echo 'Installation targets:'\n+\t@echo ' install - Install the git suite'\n+\t@echo ' install-doc - Install man pages'\n+\t@echo ' install-html - Install HTML docs'\n+\t@echo ' install-info - Install info docs'\n+\t@echo ' install-pdf - Install PDF docs'\n+\t@echo ' quick-install-doc - Install pregenerated man pages from origin/man'\n+\t@echo ' quick-install-html - Install pregenerated HTML pages from origin/html'\n+\t@echo\n+\t@echo 'Common targets:'\n+\t@echo ' all - Build the git suite'\n+\t@echo ' test - Run the git test suite'\n+\t@echo\n+\t@echo 'Other targets:'\n+\t@echo ' tags/TAGS - Generate tags for editors'\n+\t@echo ' cscope - Generate cscope index'\n+\t@echo ' coverage - Build git with gcov support and run the test suite'\n+\t@echo ' cover_db_html - Generate HTML coverage report of the test suite coverage'\n+\t@echo ' check - Check C sources with sparse'\n+\t@echo\n+\t@echo ' make V=1 [targets] verbose build'\n+\t@echo\n-- \n1.7.3.16.g5d4d9\n"},{"id":"151887","messageId":"7v39suurpw.fsf@alter.siamese.dyndns.org","threadId":"25266","inReplyTo":"1285661638-27741-1-git-send-email-bebarino@gmail.com","subject":"Re: [PATCH] Makefile: Add help target","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-09-28T09:45:15Z","receivedAt":"2010-09-28T09:45:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Not interested, at least in the current form.\n\nI do not look forward to having to maintain a large number of lines that\nare doomed to go stale, and every time we need to touch we need to deal\nwith a lot of noise \"@echo '\"? No thanks.\n\nIt might be a bit less distasteful if it were plain text additions at the\nend of INSTALL file, though.\n"},{"id":"151900","messageId":"AANLkTi=beUW5j4WSGOB__LNP7o60Wep_Y9n4YXOZUMtU@mail.gmail.com","threadId":"25266","inReplyTo":"7v39suurpw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Makefile: Add help target","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-09-28T11:37:56Z","receivedAt":"2010-09-28T11:37:56Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Tue, Sep 28, 2010 at 11:45, Junio C Hamano wrote:\n> I do not look forward to having to maintain a large number of lines that\n> are doomed to go stale\n\nHow often have we changed makefile targets recently? The most recent\none that I can find is Jakub adding \"install-gitweb\" in 152d94348f,\nwhich was back in May 1st. The next one before that is the addition of\n'gitweb' in 62331ef1637f which was back in January 30th. Besides,\n'make help' doesn't have to contain _all_ Makefile targets, just the\nimportant ones that a user is most likely to need. Similar to 'git\nhelp' itself.\n\n> and every time we need to touch we need to deal\n> with a lot of noise \"@echo '\"?\n\nI don't understand what is particularly bothersome about the leading\n\"@echo\" lines. Adding or removing a target is still very easy even\nwith the leading @echo's, the only thing that would be a PITA is\nreflowing paragraphs, currently, there _are_ no paragraphs, everything\nfits on one line.\n\n> It might be a bit less distasteful if it were plain text additions at the\n> end of INSTALL file, though.\n\nThat does not help me nearly as much when I want to know how a\nmakefile target is called. Am I wrong in asserting that having a \"make\nhelp\" target is an accepted \"good practice\" in the unix world?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"151905","messageId":"4CA1E10F.4080906@op5.se","threadId":"25266","inReplyTo":"AANLkTi=beUW5j4WSGOB__LNP7o60Wep_Y9n4YXOZUMtU@mail.gmail.com","subject":"Re: [PATCH] Makefile: Add help target","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2010-09-28T12:35:27Z","receivedAt":"2010-09-28T12:35:27Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"On 09/28/2010 01:37 PM, Sverre Rabbelier wrote:\n> Heya,\n> \n> On Tue, Sep 28, 2010 at 11:45, Junio C Hamano wrote:\n>> I do not look forward to having to maintain a large number of lines that\n>> are doomed to go stale\n> \n> How often have we changed makefile targets recently? The most recent\n> one that I can find is Jakub adding \"install-gitweb\" in 152d94348f,\n> which was back in May 1st. The next one before that is the addition of\n> 'gitweb' in 62331ef1637f which was back in January 30th. Besides,\n> 'make help' doesn't have to contain _all_ Makefile targets, just the\n> important ones that a user is most likely to need. Similar to 'git\n> help' itself.\n> \n>> and every time we need to touch we need to deal\n>> with a lot of noise \"@echo '\"?\n> \n> I don't understand what is particularly bothersome about the leading\n> \"@echo\" lines. Adding or removing a target is still very easy even\n> with the leading @echo's, the only thing that would be a PITA is\n> reflowing paragraphs, currently, there _are_ no paragraphs, everything\n> fits on one line.\n> \n>> It might be a bit less distasteful if it were plain text additions at the\n>> end of INSTALL file, though.\n> \n> That does not help me nearly as much when I want to know how a\n> makefile target is called. Am I wrong in asserting that having a \"make\n> help\" target is an accepted \"good practice\" in the unix world?\n> \n\nhelp:\n @echo Available make targets:\n @echo -----------------------\n @$(MAKE) --print-data-base --question | \\\n\tsed -n -e '/^Makefile/d' -e 's/^\\([a-z0-9_-]*\\):.*/\\1/p' | \\\n\tsort | uniq | grep -v -e ^git -e ^test-\n\nAutomatically self-managing and seems to print most sensible targets.\nAdjust to taste with whatever's appropriate.\n\nUsers with a too-old make program (pre 3.67, I think), won't be able\nto use the help target, but that's perfectly acceptable imo.\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n\nConsidering the successes of the wars on alcohol, poverty, drugs and\nterror, I think we should give some serious thought to declaring war\non peace.\n"},{"id":"151917","messageId":"c16e8df7c8e9b562ce0e6cd6e543a83779cd2b25.1285684868.git.git@drmicha.warpmail.net","threadId":"25266","inReplyTo":"4CA1E10F.4080906@op5.se","subject":"[PATCH] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-28T14:44:20Z","receivedAt":"2010-09-28T14:44:20Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"with automatic help text collection from lines starting with \"#H# \" and\npreceding a make target.\n\nSuggested-by: Stephen Boyd \nHelped-by: Andreas Ericsson \nSigned-off-by: Michael J Gruber \n---\nHow's this for a version without maintenance issues?\nWe could sort differently, of course, or at a category key (build, doc, etc.)\nbut let's not go too far. Currently, the output of make help is:\n\nGIT_VERSION = 1.7.3.99.gc16e8\ndist : Build git-$(GIT_VERSION).tar.gz source\nhtml : Build HTML doc\ninfo : Build info docs\nman : Build man pages\ndoc : Build man pages and HTML docs\ndist-doc : Build $(manpages).tar.gz and $(htmldocs).tar.gz\npdf : Build PDF docs\nrpm : Build source and binary RPM packages\ncheck-docs : Check documentation coverage\ncoverage : Check test coverage\ncover_db_html : Check test coverage and create HTMl report\ntest : Check the build by running the test suite\ncscope : Generate cscope index\ntags : Generate tags using ctags\ninstall-html : Install HTML docs\ninstall-info : Install info docs\ninstall-doc : Install man pages\ninstall-man : Install man pages\ninstall-pdf : Install PDF docs\nquick-install-html : Install pregenerated HTML pages from origin/html\nquick-install-doc : Install pregenerated man pages from origin/man\nquick-install-man : Install pregenerated man pages from origin/man\ninstall : Install the git suite\ndistclean : Remove generated files and the configure script\nclean : Remove generated files but keep the configure script\nhelp : Show help for main make targets\n\n Makefile | 38 ++++++++++++++++++++++++++++++++++++--\n 1 files changed, 36 insertions(+), 2 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex db2efd6..187a8a2 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1952,29 +1952,37 @@ $(XDIFF_LIB): $(XDIFF_OBJS)\n $(VCSSVN_LIB): $(VCSSVN_OBJS)\n \t$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)\n \n+#H# Build man pages and HTML docs\n doc:\n \t$(MAKE) -C Documentation all\n \n+#H# Build man pages\n man:\n \t$(MAKE) -C Documentation man\n \n+#H# Build HTML doc\n html:\n \t$(MAKE) -C Documentation html\n \n+#H# Build info docs\n info:\n \t$(MAKE) -C Documentation info\n \n+#H# Build PDF docs\n pdf:\n \t$(MAKE) -C Documentation pdf\n \n+#H# Generate tags using etags\n TAGS:\n \t$(RM) TAGS\n \t$(FIND) . -name '*.[hcS]' -print | xargs etags -a\n \n+#H# Generate tags using ctags\n tags:\n \t$(RM) tags\n \t$(FIND) . -name '*.[hcS]' -print | xargs ctags -a\n \n+#H# Generate cscope index\n cscope:\n \t$(RM) cscope*\n \t$(FIND) . -name '*.[hcS]' -print | xargs cscope -b\n@@ -2040,6 +2048,7 @@ export NO_SVN_TESTS\n \n ### Testing rules\n \n+#H# Check the build by running the test suite\n test: all\n \t$(MAKE) -C t/ all\n \n@@ -2099,6 +2108,7 @@ export gitexec_instdir\n \n install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)\n \n+#H# Install the git suite\n install: all\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'\n@@ -2155,27 +2165,35 @@ endif\n install-gitweb:\n \t$(MAKE) -C gitweb install\n \n+#H# Install man pages\n install-doc:\n \t$(MAKE) -C Documentation install\n \n+#H# Install man pages\n install-man:\n \t$(MAKE) -C Documentation install-man\n \n+#H# Install HTML docs\n install-html:\n \t$(MAKE) -C Documentation install-html\n \n+#H# Install info docs\n install-info:\n \t$(MAKE) -C Documentation install-info\n \n+#H# Install PDF docs\n install-pdf:\n \t$(MAKE) -C Documentation install-pdf\n \n+#H# Install pregenerated man pages from origin/man\n quick-install-doc:\n \t$(MAKE) -C Documentation quick-install\n \n+#H# Install pregenerated man pages from origin/man\n quick-install-man:\n \t$(MAKE) -C Documentation quick-install-man\n \n+#H# Install pregenerated HTML pages from origin/html\n quick-install-html:\n \t$(MAKE) -C Documentation quick-install-html\n \n@@ -2188,6 +2206,7 @@ git.spec: git.spec.in\n \tmv $@+ $@\n \n GIT_TARNAME=git-$(GIT_VERSION)\n+#H# Build git-$(GIT_VERSION).tar.gz source\n dist: git.spec git-archive$(X) configure\n \t./git-archive --format=tar \\\n \t\t--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar\n@@ -2203,6 +2222,7 @@ dist: git.spec git-archive$(X) configure\n \t@$(RM) -r $(GIT_TARNAME)\n \tgzip -f -9 $(GIT_TARNAME).tar\n \n+#H# Build source and binary RPM packages\n rpm: dist\n \t$(RPMBUILD) \\\n \t\t--define \"_source_filedigest_algorithm md5\" \\\n@@ -2211,6 +2231,8 @@ rpm: dist\n \n htmldocs = git-htmldocs-$(GIT_VERSION)\n manpages = git-manpages-$(GIT_VERSION)\n+\n+#H# Build $(manpages).tar.gz and $(htmldocs).tar.gz\n dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \tmkdir .doc-tmp-dir\n@@ -2230,10 +2252,11 @@ dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \n ### Cleaning rules\n-\n+#H# Remove generated files and the configure script\n distclean: clean\n \t$(RM) configure\n \n+#H# Remove generated files but keep the configure script\n clean:\n \t$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \\\n \t\tbuiltin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)\n@@ -2268,7 +2291,7 @@ endif\n .PHONY: FORCE TAGS tags cscope\n \n ### Check documentation\n-#\n+#H# Check documentation coverage\n check-docs::\n \t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \\\n \tdo \\\n@@ -2335,6 +2358,7 @@ check-builtins::\n #\n .PHONY: coverage coverage-clean coverage-build coverage-report\n \n+#H# Check test coverage\n coverage:\n \t$(MAKE) coverage-build\n \t$(MAKE) coverage-report\n@@ -2370,5 +2394,15 @@ coverage-untested-functions: coverage-report\n cover_db: coverage-report\n \tgcov2perl -db cover_db *.gcov\n \n+#H# Check test coverage and create HTMl report\n cover_db_html: cover_db\n \tcover -report html -outputdir cover_db_html cover_db\n+\n+#H# Show help for main make targets\n+help:\n+\t@sed -n -e '/^#H#/ {N'\\\n+\t\t-e 's/^#H# \\(.*\\)\\n\\([a-z0-9_-]*\\):.*/\\2 \\1/p'\\\n+\t\t-e '}' wrote:\n> with automatic help text collection from lines starting with \"#H# \" and\n> preceding a make target.\n\nI don't know about the \"#H#\" in particular, but documenting what each\ntarget does is a Good Thing (tm) in the first place, re-using that\ndocumentation for 'make help' is even better.\n\n> We could sort differently, of course, or at a category key (build, doc, etc.)\n\nI think just sorting alphabetically would be a good start. Maybe pipe\nthe whole thing through sort?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"151920","messageId":"AANLkTi=Z1HZDS=Cb4+zx7h95cgbOz7_KyTc5LGTD1jvw@mail.gmail.com","threadId":"25266","inReplyTo":"c16e8df7c8e9b562ce0e6cd6e543a83779cd2b25.1285684868.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] Makefile: implement help target","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-09-28T14:54:49Z","receivedAt":"2010-09-28T14:54:49Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, Sep 28, 2010 at 14:44, Michael J Gruber\n wrote:\n\n> +#H# Check test coverage and create HTMl report\n\nHTML, not HTMl\n\n>  cover_db_html: cover_db\n>        cover -report html -outputdir cover_db_html cover_db\n> +\n> +#H# Show help for main make targets\n\nHow about something less opaque, like \"# Help: Show help [...]\" or \"#\nAbout:\". It would serve the same purpose as #H#, without the reader\nwondering what that odd string means.\n\n> +help:\n> +       @sed -n  -e '/^#H#/ {N'\\\n> +               -e 's/^#H# \\(.*\\)\\n\\([a-z0-9_-]*\\):.*/\\2 \\1/p'\\\n> +               -e '}' +       do \\\n> +               printf \"%-20s: %s\\n\" \"$$target\" \"$$txt\"; \\\n> +       done\n\nLooks good, but --key=2 isn't in POSIX.\n"},{"id":"151921","messageId":"20100928145713.GE6756@in.waw.pl","threadId":"25266","inReplyTo":"AANLkTin9JZ1CErBaZjyLXBuBaX4Da7-2dgzotex+bu8X@mail.gmail.com","subject":"Re: [PATCH] Makefile: implement help target","fromName":"Zbyszek Szmek","fromEmail":"zbyszek@in.waw.pl","sentAt":"2010-09-28T14:57:13Z","receivedAt":"2010-09-28T14:57:13Z","isPatch":true,"sender":{"key":"zbyszek@in.waw.pl","avatar":"https://avatars.githubusercontent.com/u/349618?v=4"},"body":"Hi,\nthe original output (divided into documentation, building, cleaning, etc.)\nseems to be much more readable. Maybe a sort key could be added to the\nbegging of the help message and then stripped before output?\nSomething like:\n # Help: Building: compile everything\n all:\n \n # Help: Cleaning: remove things\n clean:\n\nBest,\nZbyszek\n"},{"id":"151923","messageId":"7vpqvxubl5.fsf@alter.siamese.dyndns.org","threadId":"25266","inReplyTo":"c16e8df7c8e9b562ce0e6cd6e543a83779cd2b25.1285684868.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] Makefile: implement help target","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-09-28T15:33:42Z","receivedAt":"2010-09-28T15:33:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> How's this for a version without maintenance issues?\n\nSomething along these lines would be closer to what I had in mind,\nactually.\n\nTraditionally a multi-line sed command embed in Makefile has been\nportability nightmare, which is a bit worrysome.\n\nIsn't there a \"makedoc\" ala \"perldoc\" or \"javadoc\", by the way?\n\n> ...\n> +#H# Show help for main make targets\n> +help:\n> +\t@sed -n -e '/^#H#/ {N'\\\n> +\t\t-e 's/^#H# \\(.*\\)\\n\\([a-z0-9_-]*\\):.*/\\2 \\1/p'\\\n> +\t\t-e '}' +\tdo \\\n> +\t\tprintf \"%-20s: %s\\n\" \"$$target\" \"$$txt\"; \\\n> +\tdone\n> -- \n> 1.7.3.98.g5ad7d\n"},{"id":"151925","messageId":"4CA20E24.90509@drmicha.warpmail.net","threadId":"25266","inReplyTo":"7vpqvxubl5.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-28T15:47:48Z","receivedAt":"2010-09-28T15:47:48Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 28.09.2010 17:33:\n> Michael J Gruber writes:\n> \n>> How's this for a version without maintenance issues?\n> \n> Something along these lines would be closer to what I had in mind,\n> actually.\n> \n> Traditionally a multi-line sed command embed in Makefile has been\n> portability nightmare, which is a bit worrysome.\n\nYes, but I thought for \"make help\" it's not such problem if it works on\nmost platforms only - others can read inline ;)\n\nIf portability is an issue one can work around it - is \"grep -A 1\"\nportable? I'd also have to get rid of sort --key=2.\n\n> Isn't there a \"makedoc\" ala \"perldoc\" or \"javadoc\", by the way?\n\nThere is a \"makedoc\" but that's something different...\n\nMichael\n"},{"id":"151928","messageId":"AANLkTikx2tL73gJQnqjG7yp3btcZJprKLf0z9QwcAUC1@mail.gmail.com","threadId":"25266","inReplyTo":"4CA20E24.90509@drmicha.warpmail.net","subject":"Re: [PATCH] Makefile: implement help target","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-09-28T16:04:12Z","receivedAt":"2010-09-28T16:04:12Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, Sep 28, 2010 at 15:47, Michael J Gruber\n wrote:\n> If portability is an issue one can work around it - is \"grep -A 1\"\n> portable? I'd also have to get rid of sort --key=2.\n\nNo says http://man.cx/grep(1posix)\n\nOn the other hand I don't think portability is that important here.\n\nBut if you want to make it portable using awk to do most of the work\nis probably easiest.\n"},{"id":"151954","messageId":"4fd8b490b4badd13c0ea46408e44dc7b317dc0ed.1285706151.git.git@drmicha.warpmail.net","threadId":"25266","inReplyTo":"AANLkTikx2tL73gJQnqjG7yp3btcZJprKLf0z9QwcAUC1@mail.gmail.com","subject":"[PATCHv2] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-28T20:38:04Z","receivedAt":"2010-09-28T20:38:04Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"with automatic help text collection from lines starting with \"# Help: \" and\npreceding a make target.\n\nSuggested-by: Stephen Boyd \nHelped-by: Andreas Ericsson \nSigned-off-by: Michael J Gruber \n---\nNow how's this for portability and such? New output:\n\nBuild targets:\n all: Build the Git suite\n dist: Build git-$(GIT_VERSION).tar.gz source\n dist-doc: Build $(manpages).tar.gz and $(htmldocs).tar.gz\n doc: Build man pages and HTML docs\n html: Build HTML doc\n info: Build info docs\n man: Build man pages\n pdf: Build PDF docs\n rpm: Build source and binary RPM packages\nClean targets:\n clean: Remove generated files but keep the configure script\n distclean: Remove generated files and the configure script\nDevelop targets:\n cscope: Generate cscope index\n tags: Generate tags using ctags\n TAGS: Generate tags using etags\nHelp targets:\n help: Show help for main make targets\nInstall targets:\n install-doc: Install man pages\n install-html: Install HTML docs\n install-info: Install info docs\n install: Install the Git suite\n install-man: Install man pages\n install-pdf: Install PDF docs\n quick-install-doc: Install pregenerated man pages from origin/man\n quick-install-html: Install pregenerated HTML pages from origin/html\n quick-install-man: Install pregenerated man pages from origin/man\nTest targets:\n check-docs: Check documentation coverage\n coverage: Check test coverage\n cover_db_html: Check test coverage and create HTML report\n test: Check the build by running the test suite\n\n Makefile | 43 +++++++++++++++++++++++++++++++++++++++++--\n 1 files changed, 41 insertions(+), 2 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex db2efd6..497dd92 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1,4 +1,5 @@\n # The default target of this Makefile is...\n+# Help: Build: Build the Git suite\n all::\n \n # Define V=1 to have a more verbose compile.\n@@ -1952,29 +1953,37 @@ $(XDIFF_LIB): $(XDIFF_OBJS)\n $(VCSSVN_LIB): $(VCSSVN_OBJS)\n \t$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)\n \n+# Help: Build: Build man pages and HTML docs\n doc:\n \t$(MAKE) -C Documentation all\n \n+# Help: Build: Build man pages\n man:\n \t$(MAKE) -C Documentation man\n \n+# Help: Build: Build HTML doc\n html:\n \t$(MAKE) -C Documentation html\n \n+# Help: Build: Build info docs\n info:\n \t$(MAKE) -C Documentation info\n \n+# Help: Build: Build PDF docs\n pdf:\n \t$(MAKE) -C Documentation pdf\n \n+# Help: Develop: Generate tags using etags\n TAGS:\n \t$(RM) TAGS\n \t$(FIND) . -name '*.[hcS]' -print | xargs etags -a\n \n+# Help: Develop: Generate tags using ctags\n tags:\n \t$(RM) tags\n \t$(FIND) . -name '*.[hcS]' -print | xargs ctags -a\n \n+# Help: Develop: Generate cscope index\n cscope:\n \t$(RM) cscope*\n \t$(FIND) . -name '*.[hcS]' -print | xargs cscope -b\n@@ -2040,6 +2049,7 @@ export NO_SVN_TESTS\n \n ### Testing rules\n \n+# Help: Test: Check the build by running the test suite\n test: all\n \t$(MAKE) -C t/ all\n \n@@ -2099,6 +2109,7 @@ export gitexec_instdir\n \n install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)\n \n+# Help: Install: Install the Git suite\n install: all\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'\n@@ -2155,27 +2166,35 @@ endif\n install-gitweb:\n \t$(MAKE) -C gitweb install\n \n+# Help: Install: Install man pages\n install-doc:\n \t$(MAKE) -C Documentation install\n \n+# Help: Install: Install man pages\n install-man:\n \t$(MAKE) -C Documentation install-man\n \n+# Help: Install: Install HTML docs\n install-html:\n \t$(MAKE) -C Documentation install-html\n \n+# Help: Install: Install info docs\n install-info:\n \t$(MAKE) -C Documentation install-info\n \n+# Help: Install: Install PDF docs\n install-pdf:\n \t$(MAKE) -C Documentation install-pdf\n \n+# Help: Install: Install pregenerated man pages from origin/man\n quick-install-doc:\n \t$(MAKE) -C Documentation quick-install\n \n+# Help: Install: Install pregenerated man pages from origin/man\n quick-install-man:\n \t$(MAKE) -C Documentation quick-install-man\n \n+# Help: Install: Install pregenerated HTML pages from origin/html\n quick-install-html:\n \t$(MAKE) -C Documentation quick-install-html\n \n@@ -2188,6 +2207,7 @@ git.spec: git.spec.in\n \tmv $@+ $@\n \n GIT_TARNAME=git-$(GIT_VERSION)\n+# Help: Build: Build git-$(GIT_VERSION).tar.gz source\n dist: git.spec git-archive$(X) configure\n \t./git-archive --format=tar \\\n \t\t--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar\n@@ -2203,6 +2223,7 @@ dist: git.spec git-archive$(X) configure\n \t@$(RM) -r $(GIT_TARNAME)\n \tgzip -f -9 $(GIT_TARNAME).tar\n \n+# Help: Build: Build source and binary RPM packages\n rpm: dist\n \t$(RPMBUILD) \\\n \t\t--define \"_source_filedigest_algorithm md5\" \\\n@@ -2211,6 +2232,8 @@ rpm: dist\n \n htmldocs = git-htmldocs-$(GIT_VERSION)\n manpages = git-manpages-$(GIT_VERSION)\n+\n+# Help: Build: Build $(manpages).tar.gz and $(htmldocs).tar.gz\n dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \tmkdir .doc-tmp-dir\n@@ -2230,10 +2253,11 @@ dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \n ### Cleaning rules\n-\n+# Help: Clean: Remove generated files and the configure script\n distclean: clean\n \t$(RM) configure\n \n+# Help: Clean: Remove generated files but keep the configure script\n clean:\n \t$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \\\n \t\tbuiltin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)\n@@ -2268,7 +2292,7 @@ endif\n .PHONY: FORCE TAGS tags cscope\n \n ### Check documentation\n-#\n+# Help: Test: Check documentation coverage\n check-docs::\n \t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \\\n \tdo \\\n@@ -2335,6 +2359,7 @@ check-builtins::\n #\n .PHONY: coverage coverage-clean coverage-build coverage-report\n \n+# Help: Test: Check test coverage\n coverage:\n \t$(MAKE) coverage-build\n \t$(MAKE) coverage-report\n@@ -2370,5 +2395,19 @@ coverage-untested-functions: coverage-report\n cover_db: coverage-report\n \tgcov2perl -db cover_db *.gcov\n \n+# Help: Test: Check test coverage and create HTML report\n cover_db_html: cover_db\n \tcover -report html -outputdir cover_db_html cover_db\n+\n+# Help: Help: Show help for main make targets\n+help:\n+\t@awk '/^# Help:/ { l=substr($$0,8); \\\n+\t\tgetline; \\\n+\t\tj=index(l,\":\"); \\\n+\t\tprint substr(l,1,j-1), substr($$0,1,index($$0,\":\")), substr(l,j+2); \\\n+\t\t}' wrote:\n> Now how's this for portability and such?\n\nI applaud your leet awk skills :).\n\n> Clean targets:\n>    clean:              Remove generated files but keep the configure script\n>    distclean:          Remove generated files and the configure script\n> Develop targets:\n>    cscope:             Generate cscope index\n>    tags:               Generate tags using ctags\n>    TAGS:               Generate tags using etags\n\nPerhaps an extra newline after the end of a category? Otherwise, looks nice.\n\nI haven't looked at the awk script itself wrt portability though.\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"151966","messageId":"m3vd5pftox.fsf@localhost.localdomain","threadId":"25266","inReplyTo":"4fd8b490b4badd13c0ea46408e44dc7b317dc0ed.1285706151.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-09-28T21:24:52Z","receivedAt":"2010-09-28T21:24:52Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"I'm sorry for duplicated post; I made mistake that made vger anti-SPAM\nfilter stop it.\n\nMichael J Gruber writes:\n\n> with automatic help text collection from lines starting with \"# Help: \" and\n> preceding a make target.\n> \n> Suggested-by: Stephen Boyd \n> Helped-by: Andreas Ericsson \n> Signed-off-by: Michael J Gruber \n> ---\n> Now how's this for portability and such? New output:\n> \n> Build targets:\n> all: Build the Git suite\n> dist: Build git-$(GIT_VERSION).tar.gz source\n> dist-doc: Build $(manpages).tar.gz and $(htmldocs).tar.gz\n> doc: Build man pages and HTML docs\n> html: Build HTML doc\n> info: Build info docs\n> man: Build man pages\n> pdf: Build PDF docs\n> rpm: Build source and binary RPM packages\n> Clean targets:\n> clean: Remove generated files but keep the configure script\n> distclean: Remove generated files and the configure script\n[...]\n\nShouldn't some excerpt of this be put in the commit message as example\noutput fragment?\n\n\n> Makefile | 43 +++++++++++++++++++++++++++++++++++++++++--\n> 1 files changed, 41 insertions(+), 2 deletions(-)\n> \n> diff --git a/Makefile b/Makefile\n> index db2efd6..497dd92 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -1,4 +1,5 @@\n> # The default target of this Makefile is...\n> +# Help: Build: Build the Git suite\n> all::\n[...]\n\n> ### Testing rules\n\nWhy can't you use existing headers in Makefile, like the one above, to\ndivide list of targets in \"make help\" output into categories of\ntargets?\n\n> +\n> +# Help: Help: Show help for main make targets\n> +help:\n> +\t@awk '/^# Help:/ { l=substr($$0,8); \\\n\nDoesn't it need to be $(AWK) not awk?\n\n> +\t\tgetline; \\\n> +\t\tj=index(l,\":\"); \\\n> +\t\tprint substr(l,1,j-1), substr($$0,1,index($$0,\":\")), substr(l,j+2); \\\n> +\t\t}' +\tdo \\\n> +\t\ttest \"$$category\" = \"$$currcat\" || printf \"$$category targets:\\n\"; \\\n> +\t\tcurrcat=\"$$category\"; \\\n> +\t\tprintf \" %-20s%s\\n\" \"$$target\" \"$$text\"; \\\n> +\tdone\n> -- \n> 1.7.3.98.g5ad7d\n> \n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"151969","messageId":"r6bnW3ubJQeOuXWFRPisJu1hXBq3kXeHCvNe10M00ZM@cipher.nrlssc.navy.mil","threadId":"25266","inReplyTo":"4fd8b490b4badd13c0ea46408e44dc7b317dc0ed.1285706151.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Brandon Casey","fromEmail":"brandon.casey.ctr@nrlssc.navy.mil","sentAt":"2010-09-28T22:00:25Z","receivedAt":"2010-09-28T22:00:25Z","isPatch":false,"sender":{"key":"brandon.casey.ctr@nrlssc.navy.mil","avatar":null},"body":"On 09/28/2010 03:38 PM, Michael J Gruber wrote:\n> with automatic help text collection from lines starting with \"# Help: \" and\n> preceding a make target.\n> \n> Suggested-by: Stephen Boyd \n> Helped-by: Andreas Ericsson \n> Signed-off-by: Michael J Gruber \n> ---\n> Now how's this for portability and such? New output:\n> \n> Build targets:\n> all: Build the Git suite\n> dist: Build git-$(GIT_VERSION).tar.gz source\n> dist-doc: Build $(manpages).tar.gz and $(htmldocs).tar.gz\n\n\n> Makefile | 43 +++++++++++++++++++++++++++++++++++++++++--\n> 1 files changed, 41 insertions(+), 2 deletions(-)\n\n\nVery nice. Too bad we have more targets than fit in my 33-line terminal.\n\n/bikeshed\n\nHow about this micro-tweak:\n\n 1) Remove the colon from the targets so they sort correctly.\n i.e. so \"dist\" sorts before \"dist-doc\" and \"install\" sorts\n before \"install-*\"\n 2) Add \" - \" prefix to description strings and reduce target\n width accordingly so we still have just as much room for\n the description string.\n\nSo the output looks like this:\n\nBuild targets:\n all - Build the Git suite\n dist - Build git-$(GIT_VERSION).tar.gz source\n dist-doc - Build $(manpages).tar.gz and $(htmldocs).tar.gz\n doc - Build man pages and HTML docs\n html - Build HTML doc\n info - Build info docs\n man - Build man pages\n pdf - Build PDF docs\n rpm - Build source and binary RPM packages\nClean targets:\n clean - Remove generated files but keep the configure script\n distclean - Remove generated files and the configure script\nDevelop targets:\n TAGS - Generate tags using etags\n cscope - Generate cscope index\n tags - Generate tags using ctags\nHelp targets:\n help - Show help for main make targets\nInstall targets:\n install - Install the Git suite\n install-doc - Install man pages\n install-html - Install HTML docs\n install-info - Install info docs\n install-man - Install man pages\n install-pdf - Install PDF docs\n quick-install-doc - Install pregenerated man pages from origin/man\n quick-install-html - Install pregenerated HTML pages from origin/html\n quick-install-man - Install pregenerated man pages from origin/man\nTest targets:\n check-docs - Check documentation coverage\n cover_db_html - Check test coverage and create HTML report\n coverage - Check test coverage\n test - Check the build by running the test suite\n\n\n(Warning: copy/pasted):\n\ndiff --git a/Makefile b/Makefile\nindex c7f0bb7..2803aa1 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2398,10 +2398,10 @@ help:\n @awk '/^# Help:/ { l=substr($$0,8); \\\n getline; \\\n j=index(l,\":\"); \\\n- print substr(l,1,j-1), substr($$0,1,index($$0,\":\")), substr(l,j+2); \\\n+ print substr(l,1,j-1), substr($$0,1,index($$0,\":\")-1), substr(l,j+2); \\\n }' +help:\n> +\t@awk '/^# Help:/ { l=substr($$0,8); \\\n> +\t\tgetline; \\\n> +\t\tj=index(l,\":\"); \\\n> +\t\tprint substr(l,1,j-1), substr($$0,1,index($$0,\":\")), substr(l,j+2); \\\n> +\t\t}' +\tdo \\\n> +\t\ttest \"$$category\" = \"$$currcat\" || printf \"$$category targets:\\n\"; \\\n> +\t\tcurrcat=\"$$category\"; \\\n> +\t\tprintf \" %-20s%s\\n\" \"$$target\" \"$$text\"; \\\n> +\tdone\n\nSurely this is why we have perl?\n\nhelp:\n\t@perl -n0777 \\\n\t -e 'push @{$$h{$$1}}, [$$3, $$2] while /^# Help: (.*?): (.*)\\n(.*?):/mg;' \\\n\t -e 'for (sort keys(%h)) {' \\\n\t -e ' print \"$$_:\\n\";' \\\n\t -e ' printf(\" %-20s%s\\n\", @$$_) for (@{$$h{$$_}});' \\\n\t -e '}' Makefile\n\nNote that mine will actually print the targets in a heading in the order\nin which they appear in the Makefile, which I consider slightly more\nuseful (especially in that we can tweak the order easily). It would also\nbe easy to sort the headers in some more meaningful way, but here I just\ndid it lexically.\n\n-Peff\n"},{"id":"152018","messageId":"1285740659664-5582616.post@n2.nabble.com","threadId":"25266","inReplyTo":"7v39suurpw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Makefile: Add help target","fromName":"yj2133011","fromEmail":"274040551@qq.com","sentAt":"2010-09-29T06:10:59Z","receivedAt":"2010-09-29T06:10:59Z","isPatch":true,"sender":{"key":"274040551@qq.com","avatar":null},"body":"\nNot interested, at least in the current form.\n\nI do not look forward to having to maintain a large number of lines that\nare doomed to go stale, and every time we need to touch we need to deal\nwith a lot of noise \"@echo '\"? No thanks.\n\nIt might be a bit less distasteful if it were plain text additions at the\nend of INSTALL file, though. \n\n-----\nThe voice input and output is very good in this \nhttp://www.tomtop.com/black-ps3-wireless-bluetooth-headset-for-playstation-3.html?aid=z\nWireless PS3 Headset . It is compatible with all PS3 games.Buy from Reliable \nhttp://www.tomtop.com/google-android-7-notebook-3g-tablet-pc-umpc-wifi-mid-pda.html?aid=z\nGoogle Android PC apad Wholesalers.\n-- \nView this message in context: http://git.661346.n2.nabble.com/PATCH-Makefile-Add-help-target-tp5578369p5582616.html\nSent from the git mailing list archive at Nabble.com.\n"},{"id":"152023","messageId":"4CA2E4C7.305@drmicha.warpmail.net","threadId":"25266","inReplyTo":"20100929051640.GA26324@sigill.intra.peff.net","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-29T07:03:35Z","receivedAt":"2010-09-29T07:03:35Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 29.09.2010 07:16:\n> On Tue, Sep 28, 2010 at 10:38:04PM +0200, Michael J Gruber wrote:\n> \n>> +help:\n>> +\t@awk '/^# Help:/ { l=substr($$0,8); \\\n>> +\t\tgetline; \\\n>> +\t\tj=index(l,\":\"); \\\n>> +\t\tprint substr(l,1,j-1), substr($$0,1,index($$0,\":\")), substr(l,j+2); \\\n>> +\t\t}' > +\tdo \\\n>> +\t\ttest \"$$category\" = \"$$currcat\" || printf \"$$category targets:\\n\"; \\\n>> +\t\tcurrcat=\"$$category\"; \\\n>> +\t\tprintf \" %-20s%s\\n\" \"$$target\" \"$$text\"; \\\n>> +\tdone\n> \n> Surely this is why we have perl?\n\nI don't speak perl.\n\nHonestly, this is slowly going on my nerves. Maybe it's because I'm\nreading too many \"can't we do it this way\" responses in one go and\nwithout being coffeinated, and without seeing how \"different\" is better.\n[I've been heeding all advise on portability and readability, as you can\nsee.]\n\nSo far we've been using neither awk nor perl in the Makefile, but sed.\n\n> help:\n> \t@perl -n0777 \\\n> \t -e 'push @{$$h{$$1}}, [$$3, $$2] while /^# Help: (.*?): (.*)\\n(.*?):/mg;' \\\n\nOn top of everything else, you're even slashing mg! (See, I'm less\ngrumpy already...)\n\n> \t -e 'for (sort keys(%h)) {' \\\n> \t -e ' print \"$$_:\\n\";' \\\n> \t -e ' printf(\" %-20s%s\\n\", @$$_) for (@{$$h{$$_}});' \\\n> \t -e '}' Makefile\n> \n\nHow portable are the regexps and the array/dictionary push?\n\n> Note that mine will actually print the targets in a heading in the order\n> in which they appear in the Makefile, which I consider slightly more\n> useful (especially in that we can tweak the order easily).\n\nI don't think Makefile order would be useful. If you know exactly what\nyou're looking for you need no sorting, you can just search for that\nterm. (I would do a 'grep -A20 \"^target:\" Makefile' or hit \"/^target\" in\nmy vim but I'm sure there's a different way of doing it in perl...)\n\nIf you're trying to find your way around you guess a generic term and\nlook for that, and that's easier to do when the categories are sorted\nalphabetically.\n\nMichael\n"},{"id":"152026","messageId":"20100929073400.GA28010@sigill.intra.peff.net","threadId":"25266","inReplyTo":"4CA2E4C7.305@drmicha.warpmail.net","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-09-29T07:34:01Z","receivedAt":"2010-09-29T07:34:01Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Sep 29, 2010 at 09:03:35AM +0200, Michael J Gruber wrote:\n\n> > Surely this is why we have perl?\n> \n> I don't speak perl.\n> \n> Honestly, this is slowly going on my nerves. Maybe it's because I'm\n> reading too many \"can't we do it this way\" responses in one go and\n> without being coffeinated, and without seeing how \"different\" is better.\n> [I've been heeding all advise on portability and readability, as you can\n> see.]\n\nI should have been more clear about my motivations. It was mainly \"I\nwonder how short I can make this in perl?\" The alternate sorting was\nsomething that happened incidentally, though it did make more sense to\nme.\n\nSo you can just ignore me if you like. :)\n\n> > \t -e 'for (sort keys(%h)) {' \\\n> > \t -e ' print \"$$_:\\n\";' \\\n> > \t -e ' printf(\" %-20s%s\\n\", @$$_) for (@{$$h{$$_}});' \\\n> > \t -e '}' Makefile\n> > \n> \n> How portable are the regexps and the array/dictionary push?\n\nAFAIK, it should work with any perl5. I don't have any ancient versions\nhandy to test these days, though.\n\n> > Note that mine will actually print the targets in a heading in the order\n> > in which they appear in the Makefile, which I consider slightly more\n> > useful (especially in that we can tweak the order easily).\n> \n> I don't think Makefile order would be useful. If you know exactly what\n> you're looking for you need no sorting, you can just search for that\n> term. (I would do a 'grep -A20 \"^target:\" Makefile' or hit \"/^target\" in\n> my vim but I'm sure there's a different way of doing it in perl...)\n\nWhat I was trying to say was more that alphabetical is not necessarily\nthe most useful order to present things in the help screen. Probably\nthere is some hand-selected order that presents the entries in the least\nconfusing way. And one way of representing that is to have the topics in\nthat order in the Makefile, which in theory probably makes reading the\nMakefile itself simpler.\n\nBut yeah, this is way over-thinking the issue. It's a fricking list of\nMakefile targets. I am happy with your original patch.\n\n-Peff\n"},{"id":"152029","messageId":"4CA2F36D.2010901@drmicha.warpmail.net","threadId":"25266","inReplyTo":"r6bnW3ubJQeOuXWFRPisJu1hXBq3kXeHCvNe10M00ZM@cipher.nrlssc.navy.mil","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-29T08:06:05Z","receivedAt":"2010-09-29T08:06:05Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Brandon Casey venit, vidit, dixit 29.09.2010 00:00:\n> On 09/28/2010 03:38 PM, Michael J Gruber wrote:\n>> with automatic help text collection from lines starting with \"# Help: \" and\n>> preceding a make target.\n>>\n>> Suggested-by: Stephen Boyd \n>> Helped-by: Andreas Ericsson \n>> Signed-off-by: Michael J Gruber \n>> ---\n>> Now how's this for portability and such? New output:\n>>\n>> Build targets:\n>> all: Build the Git suite\n>> dist: Build git-$(GIT_VERSION).tar.gz source\n>> dist-doc: Build $(manpages).tar.gz and $(htmldocs).tar.gz\n> \n> \n>> Makefile | 43 +++++++++++++++++++++++++++++++++++++++++--\n>> 1 files changed, 41 insertions(+), 2 deletions(-)\n> \n> \n> Very nice. Too bad we have more targets than fit in my 33-line terminal.\n> \n> /bikeshed\n> \n> How about this micro-tweak:\n> \n> 1) Remove the colon from the targets so they sort correctly.\n> i.e. so \"dist\" sorts before \"dist-doc\" and \"install\" sorts\n> before \"install-*\"\n> 2) Add \" - \" prefix to description strings and reduce target\n> width accordingly so we still have just as much room for\n> the description string.\n> \n> So the output looks like this:\n> \n....\n> Install targets:\n> install - Install the Git suite\n> install-doc - Install man pages\n> install-html - Install HTML docs\n> install-info - Install info docs\n> install-man - Install man pages\n> install-pdf - Install PDF docs\n> quick-install-doc - Install pregenerated man pages from origin/man\n> quick-install-html - Install pregenerated HTML pages from origin/html\n> quick-install-man - Install pregenerated man pages from origin/man\n\nSounds good, although the sort order depends on the locale. \"LANG=C\nsort\" takes care of that.\n\n> Oh, by the way, tested and works on Solaris 10 and IRIX 6.5.\n\nThanks!\nMichael\n"},{"id":"152066","messageId":"7vhbh8r1zj.fsf@alter.siamese.dyndns.org","threadId":"25266","inReplyTo":"20100929073400.GA28010@sigill.intra.peff.net","subject":"Re: [PATCHv2] Makefile: implement help target","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-09-29T15:41:36Z","receivedAt":"2010-09-29T15:41:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> What I was trying to say was more that alphabetical is not necessarily\n> the most useful order to present things in the help screen. Probably\n> there is some hand-selected order that presents the entries in the least\n> confusing way. And one way of representing that is to have the topics in\n> that order in the Makefile, which in theory probably makes reading the\n> Makefile itself simpler.\n\nI agree with this, even though I do not feel _too_ strongly about it.\n\nBy the way, while we are at adding \"make help\" support...\n\nWith help annotations in the Makefile like this:\n\n # Help: install everything\n # - the user visible commands go to $(bindir)\n # - helper programs go to $(gitexec_instdir)\n # - templates go to $(template_instdir)\n install: all\n $(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'\n\nI imagine it would be really cool if \"make help\" said something like this:\n\n $ make help\n ...\n install:\n install everything\n - the user visible commands go to $(bindir) = /home/junio/bin\n - helper commands go to $(gitexec_instdir) = /home/junio/libexec/git-core\n - templates go to $(template_instdir) = /home/junio/share/git-core/templates\n\nto help the builder figuring out what make variable(s) to tweak. To be useful,\nI think you would need to show the expansion, though. E.g.\n\n - the user visible commands go to $(bindir) = /home/junio/bin\n bindir = $(prefix)/$(bindir_relative)\n prefix = $HOME\n HOME = /home/junio\n bindir_relative = bin\n\nBut again, I do not feel strongly about it either.\n"},{"id":"152081","messageId":"d2da07fe51a3aba727165b0a0de299c266097145.1285791283.git.git@drmicha.warpmail.net","threadId":"25266","inReplyTo":"7vhbh8r1zj.fsf@alter.siamese.dyndns.org","subject":"[PATCHv3] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-29T20:15:55Z","receivedAt":"2010-09-29T20:15:55Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"with automatic help text collection from \"help-X::\" targets, where X\ndenotes a category for the target. This has the advantage (over a\ncomment based solution) that we can use make's variable expansion inside\nthe help text. Further exploitation of this feature is left for a future\npatch.\n\nWith this, \"make help\" produces:\n\nHelp:\n help - Show help for main make targets\n help-X - Show help for category X (Build, Test, Install, Clean, Develop)\nBuild Git and the documentation:\n all - Build the Git suite\n doc - Build man pages and HTML docs\n man - Build man pages\n html - Build HTML doc\n info - Build info docs\n pdf - Build PDF docs\n dist - Build git-1.7.3.99.gacf23.dirty.tar.gz source archive\n rpm - Build source and binary RPM packages\n dist-doc - Build git-manpages-1.7.3.99.gacf23.dirty.tar.gz and git-htmldocs-1.7.3.99.gacf23.dirty.tar.gz\nTesting source and build:\n test - Check the build by running the test suite\n check-docs - Check documentation coverage\n coverage - Check test coverage\n cover_db_html - Check test coverage and create HTML report\nInstalling the Git suite and documentation:\n install - Install the Git suite\n install-doc - Install man pages\n install-man - Install man pages\n install-html - Install HTML docs\n install-info - Install info docs\n install-pdf - Install PDF docs\n quick-install-doc - Install pregenerated man pages from origin/man\n quick-install-man - Install pregenerated man pages from origin/man\n quick-install-html - Install pregenerated HTML pages from origin/html\nCleaning up after a build:\n distclean - Remove generated files and the configure script\n clean - Remove generated files but keep the configure script\nMaking development easier:\n TAGS - Generate tags using etags\n tags - Generate tags using ctags\n cscope - Generate cscope index\n\nSigned-off-by: Michael J Gruber \n---\nDoes it seem as if I can't let this go?\n\nAnyhow, here's a make based variant which is a bit more chatty in the Makefile\nitself but has a ton of advantages, such as make variable expansion. Making\ngood use of this for the install targets is left for another patch.\n\n Makefile | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-\n 1 files changed, 108 insertions(+), 1 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex db2efd6..371214d 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -1,4 +1,10 @@\n # The default target of this Makefile is...\n+help-Build::\n+\t$(H) 'Build Git and the documentation'\n+\n+help-Build::\n+\t$(HH) all 'Build the Git suite'\n+\n all::\n \n # Define V=1 to have a more verbose compile.\n@@ -1952,29 +1958,56 @@ $(XDIFF_LIB): $(XDIFF_OBJS)\n $(VCSSVN_LIB): $(VCSSVN_OBJS)\n \t$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)\n \n+help-Build::\n+\t$(HH) doc 'Build man pages and HTML docs'\n+\n doc:\n \t$(MAKE) -C Documentation all\n \n+help-Build::\n+\t$(HH) man 'Build man pages'\n+\n man:\n \t$(MAKE) -C Documentation man\n \n+help-Build::\n+\t$(HH) html 'Build HTML doc'\n+\n html:\n \t$(MAKE) -C Documentation html\n \n+help-Build::\n+\t$(HH) info 'Build info docs'\n+\n info:\n \t$(MAKE) -C Documentation info\n \n+help-Build::\n+\t$(HH) pdf 'Build PDF docs'\n+\n pdf:\n \t$(MAKE) -C Documentation pdf\n \n+help-Develop::\n+\t$(H) 'Making development easier'\n+\n+help-Develop::\n+\t$(HH) TAGS 'Generate tags using etags'\n+\n TAGS:\n \t$(RM) TAGS\n \t$(FIND) . -name '*.[hcS]' -print | xargs etags -a\n \n+help-Develop::\n+\t$(HH) tags 'Generate tags using ctags'\n+\n tags:\n \t$(RM) tags\n \t$(FIND) . -name '*.[hcS]' -print | xargs ctags -a\n \n+help-Develop::\n+\t$(HH) cscope 'Generate cscope index'\n+\n cscope:\n \t$(RM) cscope*\n \t$(FIND) . -name '*.[hcS]' -print | xargs cscope -b\n@@ -2040,6 +2073,12 @@ export NO_SVN_TESTS\n \n ### Testing rules\n \n+help-Test::\n+\t$(H) 'Testing source and build'\n+\n+help-Test::\n+\t$(HH) test 'Check the build by running the test suite'\n+\n test: all\n \t$(MAKE) -C t/ all\n \n@@ -2099,6 +2138,12 @@ export gitexec_instdir\n \n install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)\n \n+help-Install::\n+\t$(H) 'Installing the Git suite and documentation'\n+\n+help-Install::\n+\t$(HH) install 'Install the Git suite'\n+\n install: all\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'\n \t$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'\n@@ -2155,27 +2200,51 @@ endif\n install-gitweb:\n \t$(MAKE) -C gitweb install\n \n+help-Install::\n+\t$(HH) install-doc 'Install man pages'\n+\n install-doc:\n \t$(MAKE) -C Documentation install\n \n+help-Install::\n+\t$(HH) install-man 'Install man pages'\n+\n install-man:\n \t$(MAKE) -C Documentation install-man\n \n+help-Install::\n+\t$(HH) install-html 'Install HTML docs'\n+\n install-html:\n \t$(MAKE) -C Documentation install-html\n \n+help-Install::\n+\t$(HH) install-info 'Install info docs'\n+\n install-info:\n \t$(MAKE) -C Documentation install-info\n \n+help-Install::\n+\t$(HH) install-pdf 'Install PDF docs'\n+\n install-pdf:\n \t$(MAKE) -C Documentation install-pdf\n \n+help-Install::\n+\t$(HH) quick-install-doc 'Install pregenerated man pages from origin/man'\n+\n quick-install-doc:\n \t$(MAKE) -C Documentation quick-install\n \n+help-Install::\n+\t$(HH) quick-install-man 'Install pregenerated man pages from origin/man'\n+\n quick-install-man:\n \t$(MAKE) -C Documentation quick-install-man\n \n+help-Install::\n+\t$(HH) quick-install-html 'Install pregenerated HTML pages from origin/html'\n+\n quick-install-html:\n \t$(MAKE) -C Documentation quick-install-html\n \n@@ -2188,6 +2257,9 @@ git.spec: git.spec.in\n \tmv $@+ $@\n \n GIT_TARNAME=git-$(GIT_VERSION)\n+help-Build::\n+\t$(HH) dist 'Build git-$(GIT_VERSION).tar.gz source archive'\n+\n dist: git.spec git-archive$(X) configure\n \t./git-archive --format=tar \\\n \t\t--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar\n@@ -2203,6 +2275,9 @@ dist: git.spec git-archive$(X) configure\n \t@$(RM) -r $(GIT_TARNAME)\n \tgzip -f -9 $(GIT_TARNAME).tar\n \n+help-Build::\n+\t$(HH) rpm 'Build source and binary RPM packages'\n+\n rpm: dist\n \t$(RPMBUILD) \\\n \t\t--define \"_source_filedigest_algorithm md5\" \\\n@@ -2211,6 +2286,10 @@ rpm: dist\n \n htmldocs = git-htmldocs-$(GIT_VERSION)\n manpages = git-manpages-$(GIT_VERSION)\n+\n+help-Build::\n+\t$(HH) dist-doc 'Build $(manpages).tar.gz and $(htmldocs).tar.gz'\n+\n dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \tmkdir .doc-tmp-dir\n@@ -2230,10 +2309,18 @@ dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \n ### Cleaning rules\n+help-Clean::\n+\t$(H) 'Cleaning up after a build'\n+\n+help-Clean::\n+\t$(HH) distclean 'Remove generated files and the configure script'\n \n distclean: clean\n \t$(RM) configure\n \n+help-Clean::\n+\t$(HH) clean 'Remove generated files but keep the configure script'\n+\n clean:\n \t$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \\\n \t\tbuiltin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)\n@@ -2268,7 +2355,9 @@ endif\n .PHONY: FORCE TAGS tags cscope\n \n ### Check documentation\n-#\n+help-Test::\n+\t$(HH) check-docs 'Check documentation coverage'\n+\n check-docs::\n \t@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \\\n \tdo \\\n@@ -2335,6 +2424,9 @@ check-builtins::\n #\n .PHONY: coverage coverage-clean coverage-build coverage-report\n \n+help-Test::\n+\t$(HH) coverage 'Check test coverage'\n+\n coverage:\n \t$(MAKE) coverage-build\n \t$(MAKE) coverage-report\n@@ -2370,5 +2462,20 @@ coverage-untested-functions: coverage-report\n cover_db: coverage-report\n \tgcov2perl -db cover_db *.gcov\n \n+help-Test::\n+\t$(HH) cover_db_html 'Check test coverage and create HTML report'\n+\n cover_db_html: cover_db\n \tcover -report html -outputdir cover_db_html cover_db\n+\n+H=@printf \"%s:\\n\"\n+HH=@printf \" %-18s - %s\\n\"\n+\n+help-Help::\n+\t$(H) Help\n+\n+help-Help::\n+\t$(HH) help 'Show help for main make targets'\n+\t$(HH) help-X 'Show help for category X (Build, Test, Install, Clean, Develop)'\n+\n+help: help-Help help-Build help-Test help-Install help-Clean help-Develop\n-- \n1.7.3.98.g5ad7d\n"},{"id":"152089","messageId":"7vbp7gmggy.fsf@alter.siamese.dyndns.org","threadId":"25266","inReplyTo":"d2da07fe51a3aba727165b0a0de299c266097145.1285791283.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv3] Makefile: implement help target","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-09-29T20:39:57Z","receivedAt":"2010-09-29T20:39:57Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> diff --git a/Makefile b/Makefile\n> index db2efd6..371214d 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -1,4 +1,10 @@\n> # The default target of this Makefile is...\n> +help-Build::\n\nHeh, no way. The default target of this Makefile should remain \"all\".\n\nEven though letting phony double-colon rules to implicitly collect members\nof groups and showing them is a neat idea, I do not think \"make -j help\"\nwould do what you are expecting ;-)\n"},{"id":"152116","messageId":"4CA43765.5010804@drmicha.warpmail.net","threadId":"25266","inReplyTo":"7vbp7gmggy.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv3] Makefile: implement help target","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-09-30T07:08:21Z","receivedAt":"2010-09-30T07:08:21Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 09/29/2010 10:39 PM:\n> Michael J Gruber writes:\n> \n>> diff --git a/Makefile b/Makefile\n>> index db2efd6..371214d 100644\n>> --- a/Makefile\n>> +++ b/Makefile\n>> @@ -1,4 +1,10 @@\n>> # The default target of this Makefile is...\n>> +help-Build::\n> \n> Heh, no way. The default target of this Makefile should remain \"all\".\n\nDamnit, that wasn't intended.... But that's solved by a simple\nreordering, of course.\n\n> Even though letting phony double-colon rules to implicitly collect members\n> of groups and showing them is a neat idea, I do not think \"make -j help\"\n> would do what you are expecting ;-)\n\nI expect a randomly ordered mess, and \"make -j help\" fully meets those\nexpectations! Can \"-j\" be set in the environment or config.mak somehow?\nOtherwise I think that explicitly shooting yourself in the foot should\nbe allowed...\n\nAnyway, this topic is (only) about help on our Makefile, and I think\nthat as long as we don't want to go several extra miles, we have to\ndecide between two app roaches :)\n\n* comment based:\n + readable\n + -j safe\n - no var expansion (that I know of, at least without recursive make)\n +- single line comments (unless more perl/awk foo is invested)\n +- either in Makefile order or lexically sorted (or more perl lines)\n\n* phony :: rules based:\n +- somewhat less readable\n - not -j safe\n + var expansion\n + multi line comments (could easily add a 3rd level also)\n + categories can be ordered freely (targets in Makefile order within)\n\nMichael\n"}]}