build: introduce make help

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
cockroachdb · Jul 17, 2017 · 702d726 · 702d726
1 parent a1af558
commit 702d726
Showing 1 changed file with 29 additions and 7 deletions.
diff --git a/Makefile b/Makefile
@@ -21,15 +21,15 @@
 #   make test PKG=./pkg/storage TESTFLAGS=--vmodule=raft=1
 #
 # Note that environment variable overrides are intentionally ignored.
-PKG          := ./pkg/...
+PKG          := ./pkg/...                           ## Which package to run tests against, e.g. "./pkg/storage".
 TAGS         :=
-TESTS        := .
-BENCHES      :=
-FILES        :=
+TESTS        := .                                   ## Regexp to pass to the -run argument of the go test runner. See go help testflag.
+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.
 TESTTIMEOUT  := 4m
 RACETIMEOUT  := 15m
 BENCHTIMEOUT := 5m
-TESTFLAGS    :=
+TESTFLAGS    :=                                     ## Extra flags to pass to the go test runner, e.g. "-v --vmodule=raft=1"
 STRESSFLAGS  :=
 DUPLFLAGS    := -t 100
 GOFLAGS      :=
@@ -42,6 +42,16 @@ INSTALL      := install
 prefix       := /usr/local
 bindir       := $(prefix)/bin
 
+help: ## Print help for targets with comments.
+	@echo "Usage:"
+	@echo "  make [target] [FLAG=foo FLAG2=bar...]"
+	@echo ""
+	@echo "Available commands:"
+	@grep -Eh '^[a-zA-Z._-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-30s %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Available flags:"
+	@grep -Eh '^[a-zA-Z._-]+ *:=.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":=.*?## "}; {printf "  %-30s %s\n", $$1, $$2}'
+
 # Possible values:
 # <empty>: use the default toolchain
 # release-linux-gnu:  target Linux 2.6.32, dynamically link GLIBC 2.12.2
@@ -157,6 +167,7 @@ $(COCKROACH) build buildoss go-install: $(C_LIBS) $(CGO_FLAGS_FILES) $(BOOTSTRAP
 	 $(XGO) $(BUILDMODE) -v $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' $(BUILDTARGET)
 
 .PHONY: install
+install: ## Install CockroachDB binary.
 install: $(COCKROACH)
 	$(INSTALL) -d -m 755 $(DESTDIR)$(bindir)
 	$(INSTALL) -m 755 $(COCKROACH) $(DESTDIR)$(bindir)/cockroach
@@ -180,6 +191,7 @@ gotestdashi: $(C_LIBS) $(CGO_FLAGS_FILES) $(BOOTSTRAP_TARGET)
 
 testshort: override TESTFLAGS += -short
 
+testrace: ## Run tests with the Go race detector enabled.
 testrace: override GOFLAGS += -race
 testrace: export GORACE := halt_on_error=1
 testrace: TESTTIMEOUT := $(RACETIMEOUT)
@@ -194,6 +206,7 @@ bin/logictest.test: main.go $(shell $(FIND_RELEVANT) ! -name 'zcgo_flags.go' -na
 	$(MAKE) gotestdashi GOFLAGS='$(GOFLAGS)' TAGS='$(TAGS)' LINKFLAGS='$(LINKFLAGS)' PKG='$(PKG)'
 	$(XGO) test $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' -c -o bin/logictest.test $(PKG)
 
+bench: ## Run benchmarks.
 bench: BENCHES := .
 bench: TESTS := -
 bench: TESTTIMEOUT := $(BENCHTIMEOUT)
@@ -204,6 +217,7 @@ check test testshort testrace bench: gotestdashi
 
 # Run make testlogic to run all of the logic tests. Specify test files to run
 # with make testlogic FILES="foo bar".
+testlogic: ## Run SQL Logic Tests.
 testlogic: TESTS := $(if $(FILES),TestLogic$$//^$(subst $(space),$$|^,$(FILES))$$,TestLogic)
 testlogic: TESTFLAGS := -test.v $(if $(FILES),-show-sql)
 testlogic: bin/logictest.test
@@ -230,6 +244,8 @@ stressrace: TESTTIMEOUT := $(RACETIMEOUT)
 # - PKG may not contain any tests! This is handled with an `if` statement that
 # checks for the presence of a test binary before running `stress` on it.
 .PHONY: stress stressrace
+stress: ## Run tests under stress.
+stressrace: ## Run tests under stress with the race detector enabled.
 stress stressrace: $(C_LIBS) $(CGO_FLAGS_FILES) $(BOOTSTRAP_TARGET)
 	$(GO) list -tags '$(TAGS)' -f '$(XGO) test -v $(GOFLAGS) -tags '\''$(TAGS)'\'' -ldflags '\''$(LINKFLAGS)'\'' -i -c {{.ImportPath}} -o '\''{{.Dir}}'\''/stress.test && (cd '\''{{.Dir}}'\'' && if [ -f stress.test ]; then COCKROACH_STRESS=true stress $(STRESSFLAGS) ./stress.test -test.run '\''$(TESTS)'\'' $(if $(BENCHES),-test.bench '\''$(BENCHES)'\'') -test.timeout $(TESTTIMEOUT) $(TESTFLAGS); fi)' $(PKG) | $(SHELL)
 
@@ -240,7 +256,7 @@ upload-coverage: $(BOOTSTRAP_TARGET)
 	@build/upload-coverage.sh
 
 .PHONY: acceptance
-acceptance:
+acceptance: ## Run acceptance tests.
 	@pkg/acceptance/run.sh
 
 .PHONY: dupl
@@ -262,34 +278,39 @@ dupl: $(BOOTSTRAP_TARGET)
 # `go generate` uses stringer and so must depend on gotestdashi per the above
 # comment. See https://github.com/golang/go/issues/10249 for details.
 .PHONY: generate
+generate: ## Regenerate generated code.
 generate: gotestdashi
 	$(GO) generate $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' $(PKG)
 
 # The style checks depend on `go vet` and so must depend on gotestdashi per the
 # above comment. See https://github.com/golang/go/issues/16086 for details.
 .PHONY: lint
+lint: ## Run all style checkers and linters.
 lint: override TAGS += lint
 lint: gotestdashi
 	$(XGO) test ./build -v $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' -run 'TestStyle/$(TESTS)'
 
 .PHONY: lintshort
+lintshort: ## Run a fast subset of the style checkers and linters.
 lintshort: override TAGS += lint
 lintshort: gotestdashi
 	$(XGO) test ./build -v $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' -short -run 'TestStyle/$(TESTS)'
 
 .PHONY: clean
+clean: ## Clean all build artifacts.
 clean: clean-c-deps
 	$(GO) clean $(GOFLAGS) -tags '$(TAGS)' -ldflags '$(LINKFLAGS)' -i github.com/cockroachdb/...
 	$(FIND_RELEVANT) -type f \( -name 'zcgo_flags*.go' -o -name '*.test' \) -exec rm {} +
 	rm -f $(BOOTSTRAP_TARGET) $(ARCHIVE)
 
 .PHONY: protobuf
-protobuf:
+protobuf: ## Regenerate generated code for protobuf definitions.
 	$(MAKE) -C $(ORG_ROOT) -f cockroach/build/protobuf.mk
 
 # pre-push locally runs most of the checks CI will run. Notably, it doesn't run
 # the acceptance tests.
 .PHONY: pre-push
+pre-push: ## Run generate, lint, and test.
 pre-push: generate lint test
 	$(MAKE) -C $(REPO_ROOT)/pkg/ui lint test
 	! git status --porcelain | read || (git status; git --no-pager diff -a 1>&2; exit 1)
@@ -300,6 +321,7 @@ pre-push: generate lint test
 # $(ARCHIVE_BASE)/src/github.com/cockroachdb/cockroach to allow the extracted
 # archive to serve directly as a GOPATH root.
 .PHONY: archive
+archive: ## Build a source tarball from this repository.
 archive: $(ARCHIVE)
 
 $(ARCHIVE): $(ARCHIVE).tmp