GNUmakefile: add "help" target (#4390)

Example output:

$ make help
clean                           Remove build directory
fmt                             Reformat source
fmt-check                       Warn if any source needs reformatting
gen-device                      Generate microcontroller-specific sources
llvm-source                     Get LLVM sources
llvm-build                      Build LLVM
lint                            Lint source tree
spell                           Spellcheck source tree

Might even work on windows, since git for windows comes with awk.

BUILDING.md

@@ -28,6 +28,21 @@ build tools to be built. Go is of course necessary to build TinyGo itself.
 The rest of this guide assumes you're running Linux, but it should be equivalent
 on a different system like Mac.
 
+## Using GNU Make
+
+The static build of TinyGo is driven by GNUmakefile, which provides a help target for quick reference:
+
+    % make help
+    clean                           Remove build directory
+    fmt                             Reformat source
+    fmt-check                       Warn if any source needs reformatting
+    gen-device                      Generate microcontroller-specific sources
+    llvm-source                     Get LLVM sources
+    llvm-build                      Build LLVM
+    tinygo                          Build the TinyGo compiler
+    lint                            Lint source tree
+    spell                           Spellcheck source tree
+
 ## Download the source
 
 The first step is to download the TinyGo sources (use `--recursive` if you clone

GNUmakefile

@@ -175,17 +175,17 @@ ifneq ("$(wildcard $(LLVM_BUILDDIR)/bin/llvm-config*)","")
     CGO_LDFLAGS+=-L$(abspath $(LLVM_BUILDDIR)/lib) -lclang $(CLANG_LIBS) $(LLD_LIBS) $(shell $(LLVM_CONFIG_PREFIX) $(LLVM_BUILDDIR)/bin/llvm-config --ldflags --libs --system-libs $(LLVM_COMPONENTS)) -lstdc++ $(CGO_LDFLAGS_EXTRA)
 endif
 
-clean:
+clean: ## Remove build directory
 	@rm -rf build
 
 FMT_PATHS = ./*.go builder cgo/*.go compiler interp loader src transform
-fmt:
+fmt: ## Reformat source
 	@gofmt -l -w $(FMT_PATHS)
-fmt-check:
+fmt-check: ## Warn if any source needs reformatting
 	@unformatted=$$(gofmt -l $(FMT_PATHS)); [ -z "$$unformatted" ] && exit 0; echo "Unformatted:"; for fn in $$unformatted; do echo "  $$fn"; done; exit 1
 
 
-gen-device: gen-device-avr gen-device-esp gen-device-nrf gen-device-sam gen-device-sifive gen-device-kendryte gen-device-nxp gen-device-rp
+gen-device: gen-device-avr gen-device-esp gen-device-nrf gen-device-sam gen-device-sifive gen-device-kendryte gen-device-nxp gen-device-rp ## Generate microcontroller-specific sources
 ifneq ($(STM32), 0)
 gen-device: gen-device-stm32
 endif
@@ -237,18 +237,16 @@ gen-device-renesas: build/gen-device-svd
 	./build/gen-device-svd -source=https://github.com/tinygo-org/renesas-svd lib/renesas-svd/ src/device/renesas/
 	GO111MODULE=off $(GO) fmt ./src/device/renesas
 
-# Get LLVM sources.
 $(LLVM_PROJECTDIR)/llvm:
 	git clone -b tinygo_xtensa_release_18.1.2 --depth=1 https://github.com/tinygo-org/llvm-project $(LLVM_PROJECTDIR)
-llvm-source: $(LLVM_PROJECTDIR)/llvm
+llvm-source: $(LLVM_PROJECTDIR)/llvm ## Get LLVM sources
 
 # Configure LLVM.
 TINYGO_SOURCE_DIR=$(shell pwd)
 $(LLVM_BUILDDIR)/build.ninja:
 	mkdir -p $(LLVM_BUILDDIR) && cd $(LLVM_BUILDDIR) && cmake -G Ninja $(TINYGO_SOURCE_DIR)/$(LLVM_PROJECTDIR)/llvm "-DLLVM_TARGETS_TO_BUILD=X86;ARM;AArch64;AVR;Mips;RISCV;WebAssembly" "-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=Xtensa" -DCMAKE_BUILD_TYPE=Release -DLIBCLANG_BUILD_STATIC=ON -DLLVM_ENABLE_TERMINFO=OFF -DLLVM_ENABLE_ZLIB=OFF -DLLVM_ENABLE_ZSTD=OFF -DLLVM_ENABLE_LIBEDIT=OFF -DLLVM_ENABLE_Z3_SOLVER=OFF -DLLVM_ENABLE_OCAMLDOC=OFF -DLLVM_ENABLE_LIBXML2=OFF -DLLVM_ENABLE_PROJECTS="clang;lld" -DLLVM_TOOL_CLANG_TOOLS_EXTRA_BUILD=OFF -DCLANG_ENABLE_STATIC_ANALYZER=OFF -DCLANG_ENABLE_ARCMT=OFF $(LLVM_OPTION)
 
-# Build LLVM.
-$(LLVM_BUILDDIR): $(LLVM_BUILDDIR)/build.ninja
+$(LLVM_BUILDDIR): $(LLVM_BUILDDIR)/build.ninja ## Build LLVM
 	cd $(LLVM_BUILDDIR) && ninja $(NINJA_BUILD_TARGETS)
 
 ifneq ($(USE_SYSTEM_BINARYEN),1)
@@ -291,8 +289,7 @@ ifeq (, $(shell which node))
 endif
 	@if [ $(NODEJS_VERSION) -lt $(MIN_NODEJS_VERSION) ]; then echo "Install NodeJS version 18+ to run tests."; exit 1; fi
 
-# Build the Go compiler.
-tinygo:
+tinygo: ## Build the TinyGo compiler
 	@if [ ! -f "$(LLVM_BUILDDIR)/bin/llvm-config" ]; then echo "Fetch and build LLVM first by running:"; echo "  $(MAKE) llvm-source"; echo "  $(MAKE) $(LLVM_BUILDDIR)"; exit 1; fi
 	CGO_CPPFLAGS="$(CGO_CPPFLAGS)" CGO_CXXFLAGS="$(CGO_CXXFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GOENVFLAGS) $(GO) build -buildmode exe -o build/tinygo$(EXE) -tags "byollvm osusergo" -ldflags="-X github.com/tinygo-org/tinygo/goenv.GitSha1=`git rev-parse --short HEAD`" .
 test: wasi-libc check-nodejs-version
@@ -955,7 +952,7 @@ tools:
 	go generate -C ./internal/tools -tags tools  ./
 
 .PHONY: lint
-lint:
+lint: ## Lint source tree
 	go run github.com/mgechev/revive -version
 	# TODO: lint more directories!
 	# revive.toml isn't flexible enough to filter out just one kind of error from a checker, so do it with grep here.
@@ -964,6 +961,14 @@ lint:
 	go run github.com/mgechev/revive -config revive.toml compiler/... src/{os,reflect}/*.go | grep -v "should have comment or be unexported" | grep '.' | awk '{print}; END {exit NR>0}'
 
 .PHONY: spell
-spell:
-	# Check for typos in comments. Skip git submodules etc.
+spell: ## Spellcheck source tree
 	go run github.com/client9/misspell/cmd/misspell -i 'ackward,devided,extint,inbetween,programmmer,rela' $$( find . -depth 1 -type d  | egrep -w -v 'lib|llvm|src/net' )
+
+# https://www.client9.com/self-documenting-makefiles/
+.PHONY: help
+help:
+	@awk -F ':|##' '/^[^\t].+?:.*?##/ {\
+	gsub(/\$$\(LLVM_BUILDDIR\)/, "$(LLVM_BUILDDIR)"); \
+        printf "\033[36m%-30s\033[0m %s\n", $$1, $$NF \
+        }' $(MAKEFILE_LIST)
+#.DEFAULT_GOAL=help