build: introduce make help

[jordanlewis]

Add a help target to the Makefile that prints available Makefile
targets along with a brief help text for each.

Prints all targets that have an end-of-line comment starting with ##,
and all FLAG= variables with the same kind of end-of-line comment.

Example output:

Usage:
  make [target] [FLAG=foo FLAG2=bar...]

Available commands:
  acceptance                     Run acceptance tests.
  archive                        Build a source tarball from this repository.
  bench                          Run benchmarks.
  clean                          Clean all build artifacts.
  generate                       Regenerate generated code.
  help                           Print help for targets with comments.
  install                        Install CockroachDB binary.
  lint                           Run all style checkers and linters.
  lintshort                      Run a fast subset of the style checkers and linters.
  pre-push                       Run generate, lint, and test.
  protobuf                       Regenerate generated code for protobuf definitions.
  stress                         Run tests under stress.
  stressrace                     Run tests under stress with the race detector enabled.
  testlogic                      Run SQL Logic Tests.
  testrace                       Run tests with the Go race detector enabled.

Available flags:
  BENCHES                        Regexp to pass to the -run argument of the go benchmark runner.
  FILES                          Space delimited list of logic test files to run, for make testlogic.
  PKG                            Which package to run tests against, e.g. "./pkg/storage".
  TESTFLAGS                      Extra flags to pass to the go test runner, e.g. "-v --vmodule=raft=1"
  TESTS                          Regexp to pass to the -run argument of the go test runner. See go help testflag.

Approach cribbed from https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html

[cockroach-teamcity]

This change is 

[knz]

The idea is fine - the implementation is... overboard :) I don't like the idea of sending colors on terminals that may not support these codes. either "%-30s %s\n" or make the color coding conditional on known values of $TERM.

[benesch]

This is awesome. Thanks, @jordanlewis. You might want to mention make help in CONTRIBUTING.md while you're here.

[benesch]

I think I'd prefer if this were on its own line, like

testrace: ## Run tests with the Go race detector enabled

to minimize diff noise.

[jordanlewis]

Good point, done for all.

[benesch]

To address @knz's feedback, you could do something like the following:

TERM_CYAN = $(shell tput setaf 1 2> /dev/null)
TERM_RESET = $(shell tput sgr0 2> /dev/null)
awk "$(TERM_CYAN)%-30s$(TERM_RESET)" ...

[benesch]

Or, better yet, do it in the recipe to avoid the two extra shell invocations on every Make:

help:
    cyan=$$(tput setaf 1 2> /dev/null) && reset=$$(tput sgr0 2> /dev/null) && awk "$cyan%-30s$reset"

[knz]

👍 on nikhil's suggestion, but please check the output is not borked if tput doesn't exist. Not sure whether the /dev/null redirect is sufficient in that case.

[benesch]

Woohoo! Love it.

[benesch]

We should document build and buildoss too, but feel free to leave for a follow up/me.

[benesch]

Annnnnnd I just caused a conflict. Sorry! Since you'll have to rebase anyway, two optional nits:

1. These might be better described as "Useful {commands|flags}", since they're not exhaustive.
2. I'd write make [target...] [VAR=foo VAR2=bar] and "useful variables" since they're not technically flags, but perhaps I'm too deep in Make-land to know what would be more useful to users.

[jordanlewis]

Rebased, added back colors with @benesch's technique, added help for build/buildoss.

[benesch]

❤️

[irfansharif]

nice!