| Message ID | 20220408074524.156165-1-gitter.spiros@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Makefile: add help target | expand |
On 08/04/2022 08:45, Elia Pinto wrote: > Add a help target to the Makefile to be able to run make help, in the same way > does the Makefiles self-generated by some build systems. > > The target list has been statically extracted from the git Makefile with a > script and the results have been filtered in an essentially arbitrary way to > leave the ones that i imagines most interesting and frequent for a developer. > > Signed-off-by: Elia Pinto <gitter.spiros@gmail.com> > --- > The toy script I used is here > https://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh > Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 63 insertions(+) > > diff --git a/Makefile b/Makefile > index e8aba291d7..f6d6de2eb9 100644 > --- a/Makefile > +++ b/Makefile > @@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all > $(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@ > > fuzz-all: $(FUZZ_PROGRAMS) > + > +# Help Target > +help: > + @echo "The following are some of the valid targets for this Makefile:" > + @echo "... all (the default if no target is provided)" > + @echo "... build-perl-script" > + @echo "... build-python-script" > + @echo "... build-sh-script" > + @echo "... check" > + @echo "... check-builtins" > + @echo "... check-docs" > + @echo "... check-sha1" > + @echo "... clean" > + @echo "... clean-perl-script" > + @echo "... clean-python-script" > + @echo "... clean-sh-script" > + @echo "... coccicheck" > + @echo "... coccicheck-pending" > + @echo "... cocciclean" > + @echo "... configure" > + @echo "... coverage" > + @echo "... coverage-clean" > + @echo "... coverage-clean-results" > + @echo "... coverage-compile" > + @echo "... coverage-prove" > + @echo "... coverage-report" > + @echo "... coverage-test" > + @echo "... coverage-untested-functions" > + @echo "... cover_db" > + @echo "... cover_db_html" > + @echo "... cscope" > + @echo "... dist" > + @echo "... distclean" > + @echo "... dist-doc" > + @echo "... doc" > + @echo "... fuzz-all" > + @echo "... fuzz-commit-graph" > + @echo "... fuzz-objs" > + @echo "... fuzz-pack-headers" > + @echo "... fuzz-pack-idx" > + @echo "... html" > + @echo "... info" > + @echo "... install" > + @echo "... man" > + @echo "... pdf" > + @echo "... perf" > + @echo "... profile" > + @echo "... profile-clean" > + @echo "... profile-fast" > + @echo "... profile-fast-install" > + @echo "... profile-install" > + @echo "... quick-install-doc" > + @echo "... quick-install-html" > + @echo "... quick-install-man" > + @echo "... reconfigure" > + @echo "... rpm" > + @echo "... sparse" > + @echo "... strip" > + @echo "... style" > + @echo "... tags" > + @echo "... TAGS" > + @echo "... test" > +.PHONY : help Makes me realise how many areas I'm unfamiliar with, .. which is a help. ;-) -- Philip
On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote: > Add a help target to the Makefile to be able to run make help, in the same way > does the Makefiles self-generated by some build systems. > > The target list has been statically extracted from the git Makefile with a > script and the results have been filtered in an essentially arbitrary way to > leave the ones that i imagines most interesting and frequent for a developer. I could definitely see something like "make help" being helpful, since make itself doesn't have a convenient way to list all of a Makefile's targets. I worry about this list getting stale, though. If we add a new target, will we remember to update the "help" list here? It would be nice if we could dynamically generate this list, but I think that loses out on the filtering you've done here. Thanks, Taylor
On Fri, Apr 08 2022, Taylor Blau wrote: > On Fri, Apr 08, 2022 at 07:45:24AM +0000, Elia Pinto wrote: >> Add a help target to the Makefile to be able to run make help, in the same way >> does the Makefiles self-generated by some build systems. >> >> The target list has been statically extracted from the git Makefile with a >> script and the results have been filtered in an essentially arbitrary way to >> leave the ones that i imagines most interesting and frequent for a developer. > > I could definitely see something like "make help" being helpful, since > make itself doesn't have a convenient way to list all of a Makefile's > targets. > > I worry about this list getting stale, though. If we add a new target, > will we remember to update the "help" list here? It would be nice if we > could dynamically generate this list, but I think that loses out on the > filtering you've done here. There's some nice suggestions at: https://stackoverflow.com/questions/4219255/how-do-you-get-the-list-of-targets-in-a-makefile I managed to get pretty close to this by massaging the various parsers that were suggested there. But I wonder if defining help as we go along wouldn't be the best and least likely to break, and most likely to be kept up-to-date. I.e. some variant of the comments added there. Or better (maybe it's discussed in that SO thing, I didn't skim it all), something like: HELP_all = the default target all:: [...] We could then even print a heading showing what target(s) we're running by looking at MAKECMDGOALS. Also, Elia's ad-hoc script here copied from StackOverflow looks awfully similar to what I have in /usr/share/bash-completion/completions/make installed with my OS. Available here: https://github.com/scop/bash-completion/blob/master/completions/make So maybe we could just make this an optional target that depended on that widely-available bash completion? That would also have the nice benefit that to the extent that the output sucked we could maybe massage our Makefile a bit to make it better, and then we'd not only benefit "make help" users, but anyone doing "make <TAB>".
Taylor Blau <me@ttaylorr.com> writes: > I could definitely see something like "make help" being helpful, since > make itself doesn't have a convenient way to list all of a Makefile's > targets. But is listing all useful to begin with? I doubt it. Most useful targets are all .PHONYs, so a possible approach is to make them double-colon rules, and have a section at the top, next to where we explain "# The default target of this Makefile is...", that lists all of them there, and have a rule # The default target of this Makefile is... all:: +# Common targets +test:: +doc:: +... +help:: + sed -e '/help::/q' Makefile # Import tree-wide shared Makefile behavior and libraries include shared.mak perhaps? > I worry about this list getting stale, though. Absolutely. A well-curated list of common targets, maybe, but I find nothing interesting in the posted patch that lists way too many. I also suspect that a well-curated list at the top would eliminate the need for the "help" target in the first place. Between "make help" and "less Makefile", the latter is much more intuitive. Thanks.
diff --git a/Makefile b/Makefile index e8aba291d7..f6d6de2eb9 100644 --- a/Makefile +++ b/Makefile @@ -3448,3 +3448,66 @@ $(FUZZ_PROGRAMS): all $(XDIFF_OBJS) $(EXTLIBS) git.o $@.o $(LIB_FUZZING_ENGINE) -o $@ fuzz-all: $(FUZZ_PROGRAMS) + +# Help Target +help: + @echo "The following are some of the valid targets for this Makefile:" + @echo "... all (the default if no target is provided)" + @echo "... build-perl-script" + @echo "... build-python-script" + @echo "... build-sh-script" + @echo "... check" + @echo "... check-builtins" + @echo "... check-docs" + @echo "... check-sha1" + @echo "... clean" + @echo "... clean-perl-script" + @echo "... clean-python-script" + @echo "... clean-sh-script" + @echo "... coccicheck" + @echo "... coccicheck-pending" + @echo "... cocciclean" + @echo "... configure" + @echo "... coverage" + @echo "... coverage-clean" + @echo "... coverage-clean-results" + @echo "... coverage-compile" + @echo "... coverage-prove" + @echo "... coverage-report" + @echo "... coverage-test" + @echo "... coverage-untested-functions" + @echo "... cover_db" + @echo "... cover_db_html" + @echo "... cscope" + @echo "... dist" + @echo "... distclean" + @echo "... dist-doc" + @echo "... doc" + @echo "... fuzz-all" + @echo "... fuzz-commit-graph" + @echo "... fuzz-objs" + @echo "... fuzz-pack-headers" + @echo "... fuzz-pack-idx" + @echo "... html" + @echo "... info" + @echo "... install" + @echo "... man" + @echo "... pdf" + @echo "... perf" + @echo "... profile" + @echo "... profile-clean" + @echo "... profile-fast" + @echo "... profile-fast-install" + @echo "... profile-install" + @echo "... quick-install-doc" + @echo "... quick-install-html" + @echo "... quick-install-man" + @echo "... reconfigure" + @echo "... rpm" + @echo "... sparse" + @echo "... strip" + @echo "... style" + @echo "... tags" + @echo "... TAGS" + @echo "... test" +.PHONY : help
Add a help target to the Makefile to be able to run make help, in the same way does the Makefiles self-generated by some build systems. The target list has been statically extracted from the git Makefile with a script and the results have been filtered in an essentially arbitrary way to leave the ones that i imagines most interesting and frequent for a developer. Signed-off-by: Elia Pinto <gitter.spiros@gmail.com> --- The toy script I used is here https://gist.github.com/devzero2000/cb887a6ba2764f7234191e560b64b7c8#file-list_targets_makefile-sh Makefile | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+)