{"thread":{"id":"57694","subject":"[PATCH] Makefile: add help target","startedAt":"2022-04-08T07:45:38Z","lastAt":"2022-04-08T18:58:31Z","messageCount":5,"participants":["Elia Pinto","Philip Oakley","Taylor Blau","Ævar Arnfjörð Bjarmason","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"453314","messageId":"20220408074524.156165-1-gitter.spiros@gmail.com","threadId":"57694","inReplyTo":null,"subject":"[PATCH] Makefile: add help target","fromName":"Elia Pinto","fromEmail":"gitter.spiros@gmail.com","sentAt":"2022-04-08T07:45:24Z","receivedAt":"2022-04-08T07:45:38Z","isPatch":true,"sender":{"key":"gitter.spiros@gmail.com","avatar":"https://avatars.githubusercontent.com/u/158490?v=4"},"body":"Add a help target to the Makefile to be able to run make help, in the same way\ndoes the Makefiles self-generated by some build systems.\n\nThe target list has been statically extracted from the git Makefile with a\nscript and the results have been filtered in an essentially arbitrary way to\nleave the ones that i imagines most interesting and frequent for a developer.\n\nSigned-off-by: Elia Pinto <gitter.spiros@gmail.com>\n---\nThe toy script I used is here\nhttps://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh\n Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 63 insertions(+)\n\ndiff --git a/Makefile b/Makefile\nindex e8aba291d7..f6d6de2eb9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all\n \t\t$(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@\n \n fuzz-all: $(FUZZ_PROGRAMS)\n+\n+# Help Target\n+help:\n+\t@echo \"The following are some of the valid targets for this Makefile:\"\n+\t@echo \"... all (the default if no target is provided)\"\n+\t@echo \"... build-perl-script\"\n+\t@echo \"... build-python-script\"\n+\t@echo \"... build-sh-script\"\n+\t@echo \"... check\"\n+\t@echo \"... check-builtins\"\n+\t@echo \"... check-docs\"\n+\t@echo \"... check-sha1\"\n+\t@echo \"... clean\"\n+\t@echo \"... clean-perl-script\"\n+\t@echo \"... clean-python-script\"\n+\t@echo \"... clean-sh-script\"\n+\t@echo \"... coccicheck\"\n+\t@echo \"... coccicheck-pending\"\n+\t@echo \"... cocciclean\"\n+\t@echo \"... configure\"\n+\t@echo \"... coverage\"\n+\t@echo \"... coverage-clean\"\n+\t@echo \"... coverage-clean-results\"\n+\t@echo \"... coverage-compile\"\n+\t@echo \"... coverage-prove\"\n+\t@echo \"... coverage-report\"\n+\t@echo \"... coverage-test\"\n+\t@echo \"... coverage-untested-functions\"\n+\t@echo \"... cover_db\"\n+\t@echo \"... cover_db_html\"\n+\t@echo \"... cscope\"\n+\t@echo \"... dist\"\n+\t@echo \"... distclean\"\n+\t@echo \"... dist-doc\"\n+\t@echo \"... doc\"\n+\t@echo \"... fuzz-all\"\n+\t@echo \"... fuzz-commit-graph\"\n+\t@echo \"... fuzz-objs\"\n+\t@echo \"... fuzz-pack-headers\"\n+\t@echo \"... fuzz-pack-idx\"\n+\t@echo \"... html\"\n+\t@echo \"... info\"\n+\t@echo \"... install\"\n+\t@echo \"... man\"\n+\t@echo \"... pdf\"\n+\t@echo \"... perf\"\n+\t@echo \"... profile\"\n+\t@echo \"... profile-clean\"\n+\t@echo \"... profile-fast\"\n+\t@echo \"... profile-fast-install\"\n+\t@echo \"... profile-install\"\n+\t@echo \"... quick-install-doc\"\n+\t@echo \"... quick-install-html\"\n+\t@echo \"... quick-install-man\"\n+\t@echo \"... reconfigure\"\n+\t@echo \"... rpm\"\n+\t@echo \"... sparse\"\n+\t@echo \"... strip\"\n+\t@echo \"... style\"\n+\t@echo \"... tags\"\n+\t@echo \"... TAGS\"\n+\t@echo \"... test\"\n+.PHONY : help\n-- \n2.35.1\n\n"},{"id":"453324","messageId":"c141359f-651f-8fea-4c95-5881c597f33c@iee.email","threadId":"57694","inReplyTo":"20220408074524.156165-1-gitter.spiros@gmail.com","subject":"Re: [PATCH] Makefile: add help target","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-04-08T09:32:16Z","receivedAt":"2022-04-08T09:32:26Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 08/04/2022 08:45, Elia Pinto wrote:\n> Add a help target to the Makefile to be able to run make help, in the same way\n> does the Makefiles self-generated by some build systems.\n>\n> The target list has been statically extracted from the git Makefile with a\n> script and the results have been filtered in an essentially arbitrary way to\n> leave the ones that i imagines most interesting and frequent for a developer.\n>\n> Signed-off-by: Elia Pinto <gitter.spiros@gmail.com>\n> ---\n> The toy script I used is here\n> https://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh\n>  Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n>  1 file changed, 63 insertions(+)\n>\n> diff --git a/Makefile b/Makefile\n> index e8aba291d7..f6d6de2eb9 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all\n>  \t\t$(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@\n>  \n>  fuzz-all: $(FUZZ_PROGRAMS)\n> +\n> +# Help Target\n> +help:\n> +\t@echo \"The following are some of the valid targets for this Makefile:\"\n> +\t@echo \"... all (the default if no target is provided)\"\n> +\t@echo \"... build-perl-script\"\n> +\t@echo \"... build-python-script\"\n> +\t@echo \"... build-sh-script\"\n> +\t@echo \"... check\"\n> +\t@echo \"... check-builtins\"\n> +\t@echo \"... check-docs\"\n> +\t@echo \"... check-sha1\"\n> +\t@echo \"... clean\"\n> +\t@echo \"... clean-perl-script\"\n> +\t@echo \"... clean-python-script\"\n> +\t@echo \"... clean-sh-script\"\n> +\t@echo \"... coccicheck\"\n> +\t@echo \"... coccicheck-pending\"\n> +\t@echo \"... cocciclean\"\n> +\t@echo \"... configure\"\n> +\t@echo \"... coverage\"\n> +\t@echo \"... coverage-clean\"\n> +\t@echo \"... coverage-clean-results\"\n> +\t@echo \"... coverage-compile\"\n> +\t@echo \"... coverage-prove\"\n> +\t@echo \"... coverage-report\"\n> +\t@echo \"... coverage-test\"\n> +\t@echo \"... coverage-untested-functions\"\n> +\t@echo \"... cover_db\"\n> +\t@echo \"... cover_db_html\"\n> +\t@echo \"... cscope\"\n> +\t@echo \"... dist\"\n> +\t@echo \"... distclean\"\n> +\t@echo \"... dist-doc\"\n> +\t@echo \"... doc\"\n> +\t@echo \"... fuzz-all\"\n> +\t@echo \"... fuzz-commit-graph\"\n> +\t@echo \"... fuzz-objs\"\n> +\t@echo \"... fuzz-pack-headers\"\n> +\t@echo \"... fuzz-pack-idx\"\n> +\t@echo \"... html\"\n> +\t@echo \"... info\"\n> +\t@echo \"... install\"\n> +\t@echo \"... man\"\n> +\t@echo \"... pdf\"\n> +\t@echo \"... perf\"\n> +\t@echo \"... profile\"\n> +\t@echo \"... profile-clean\"\n> +\t@echo \"... profile-fast\"\n> +\t@echo \"... profile-fast-install\"\n> +\t@echo \"... profile-install\"\n> +\t@echo \"... quick-install-doc\"\n> +\t@echo \"... quick-install-html\"\n> +\t@echo \"... quick-install-man\"\n> +\t@echo \"... reconfigure\"\n> +\t@echo \"... rpm\"\n> +\t@echo \"... sparse\"\n> +\t@echo \"... strip\"\n> +\t@echo \"... style\"\n> +\t@echo \"... tags\"\n> +\t@echo \"... TAGS\"\n> +\t@echo \"... test\"\n> +.PHONY : help\n\nMakes me realise how many areas I'm unfamiliar with, .. which is a help. ;-)\n--\nPhilip\n"},{"id":"453335","messageId":"YlBVBlwNVc8mEjn5@nand.local","threadId":"57694","inReplyTo":"20220408074524.156165-1-gitter.spiros@gmail.com","subject":"Re: [PATCH] Makefile: add help target","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-04-08T15:30:14Z","receivedAt":"2022-04-08T15:30:17Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote:\n> Add a help target to the Makefile to be able to run make help, in the same way\n> does the Makefiles self-generated by some build systems.\n>\n> The target list has been statically extracted from the git Makefile with a\n> script and the results have been filtered in an essentially arbitrary way to\n> leave the ones that i imagines most interesting and frequent for a developer.\n\nI could definitely see something like \"make help\" being helpful, since\nmake itself doesn't have a convenient way to list all of a Makefile's\ntargets.\n\nI worry about this list getting stale, though. If we add a new target,\nwill we remember to update the \"help\" list here? It would be nice if we\ncould dynamically generate this list, but I think that loses out on the\nfiltering you've done here.\n\nThanks,\nTaylor\n"},{"id":"453337","messageId":"220408.86a6cvbme0.gmgdl@evledraar.gmail.com","threadId":"57694","inReplyTo":"YlBVBlwNVc8mEjn5@nand.local","subject":"Re: [PATCH] Makefile: add help target","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-04-08T15:44:44Z","receivedAt":"2022-04-08T15:55:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Apr 08 2022, Taylor Blau wrote:\n\n> On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote:\n>> Add a help target to the Makefile to be able to run make help, in the same way\n>> does the Makefiles self-generated by some build systems.\n>>\n>> The target list has been statically extracted from the git Makefile with a\n>> script and the results have been filtered in an essentially arbitrary way to\n>> leave the ones that i imagines most interesting and frequent for a developer.\n>\n> I could definitely see something like \"make help\" being helpful, since\n> make itself doesn't have a convenient way to list all of a Makefile's\n> targets.\n>\n> I worry about this list getting stale, though. If we add a new target,\n> will we remember to update the \"help\" list here? It would be nice if we\n> could dynamically generate this list, but I think that loses out on the\n> filtering you've done here.\n\nThere's some nice suggestions at:\nhttps://stackoverflow.com/questions/4219255/how-do-you-get-the-list-of-targets-in-a-makefile\n\nI managed to get pretty close to this by massaging the various parsers\nthat were suggested there.\n\nBut I wonder if defining help as we go along wouldn't be the best and\nleast likely to break, and most likely to be kept up-to-date. I.e. some\nvariant of the comments added there.\n\nOr better (maybe it's discussed in that SO thing, I didn't skim it all),\nsomething like:\n\n    HELP_all = the default target\n    all::\n    [...]\n\nWe could then even print a heading showing what target(s) we're running\nby looking at MAKECMDGOALS.\n\nAlso, Elia's ad-hoc script here copied from StackOverflow looks awfully\nsimilar to what I have in /usr/share/bash-completion/completions/make\ninstalled with my OS. Available here:\nhttps://github.com/scop/bash-completion/blob/master/completions/make\n\nSo maybe we could just make this an optional target that depended on\nthat widely-available bash completion?\n\nThat would also have the nice benefit that to the extent that the output\nsucked we could maybe massage our Makefile a bit to make it better, and\nthen we'd not only benefit \"make help\" users, but anyone doing \"make\n<TAB>\".\n"},{"id":"453348","messageId":"xmqq1qy7mmgf.fsf@gitster.g","threadId":"57694","inReplyTo":"YlBVBlwNVc8mEjn5@nand.local","subject":"Re: [PATCH] Makefile: add help target","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-08T18:58:24Z","receivedAt":"2022-04-08T18:58:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau <me@ttaylorr.com> writes:\n\n> I could definitely see something like \"make help\" being helpful, since\n> make itself doesn't have a convenient way to list all of a Makefile's\n> targets.\n\nBut is listing all useful to begin with?  I doubt it.\n\nMost useful targets are all .PHONYs, so a possible approach is to\nmake them double-colon rules, and have a section at the top, next to\nwhere we explain \"# The default target of this Makefile is...\", that\nlists all of them there, and have a rule\n\n\t# The default target of this Makefile is...\n\tall::\n\t+# Common targets\n\t+test::\n\t+doc::\n\t+...\n        +help::\n        +        sed -e '/help::/q' Makefile\n        # Import tree-wide shared Makefile behavior and libraries\n        include shared.mak\n\nperhaps?\n\n> I worry about this list getting stale, though.\n\nAbsolutely.\n\nA well-curated list of common targets, maybe, but I find nothing\ninteresting in the posted patch that lists way too many.\n\nI also suspect that a well-curated list at the top would eliminate\nthe need for the \"help\" target in the first place.  Between \"make\nhelp\" and \"less Makefile\", the latter is much more intuitive.\n\nThanks.\n\n"}]}