Add help command to makefile (#1210)

This changes sorts the makefile a bit and adds a help command to list a commands / targets and what they are doing.

Makefile

@@ -50,91 +50,49 @@ else
 
 # Proceed with normal make
 
-all: build
+##@ General
+
+all: help
+
+.PHONY: version
+version: ## Print the current version
+	@echo ${BUILD_VERSION}
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk commands is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
 .PHONY: vendor
-vendor:
+vendor: ## Update the vendor directory
 	go mod tidy
 	go mod vendor
 
-format: install-tools
+format: install-tools ## Format source code
 	@gofumpt -extra -w ${GOFILES_NOVENDOR}
 
-.PHONY: docs
-docs:
-	go generate cmd/cli/app.go
-
 .PHONY: clean
-clean:
+clean: ## Clean build artifacts
 	go clean -i ./...
 	rm -rf build
 	@[ "1" != "$(shell docker image ls woodpecker/make:local -a | wc -l)" ] && docker image rm woodpecker/make:local || echo no docker image to clean
 
-.PHONY: lint
+check-xgo: ## Check if xgo is installed
-lint: install-tools
-	@echo "Running golangci-lint"
-	golangci-lint run --timeout 10m
-	@echo "Running zerolog linter"
-	lint github.com/woodpecker-ci/woodpecker/cmd/agent
-	lint github.com/woodpecker-ci/woodpecker/cmd/cli
-	lint github.com/woodpecker-ci/woodpecker/cmd/server
-
-frontend-dependencies:
-	(cd web/; yarn install --frozen-lockfile)
-
-lint-frontend:
-	(cd web/; yarn)
-	(cd web/; yarn lesshint)
-	(cd web/; yarn lint --quiet)
-
-test-agent:
-	go test -race -cover -coverprofile agent-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/agent github.com/woodpecker-ci/woodpecker/agent/...
-
-test-server:
-	go test -race -cover -coverprofile server-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/server $(shell go list github.com/woodpecker-ci/woodpecker/server/... | grep -v '/store')
-
-test-cli:
-	go test -race -cover -coverprofile cli-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/cli github.com/woodpecker-ci/woodpecker/cli/...
-
-test-server-datastore:
-	go test -race -timeout 30s github.com/woodpecker-ci/woodpecker/server/store/...
-
-test-server-datastore-coverage:
-	go test -race -cover -coverprofile datastore-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/server/store/...
-
-test-frontend: frontend-dependencies
-	(cd web/; yarn run lint)
-	(cd web/; yarn run formatcheck)
-	(cd web/; yarn run typecheck)
-	(cd web/; yarn run test)
-
-test-lib:
-	go test -race -cover -coverprofile coverage.out -timeout 30s $(shell go list ./... | grep -v '/cmd\|/agent\|/cli\|/server')
-
-test: test-agent test-server test-server-datastore test-cli test-lib test-frontend
-
-build-frontend:
-	(cd web/; yarn install --frozen-lockfile; yarn build)
-
-build-server: build-frontend
-	CGO_ENABLED=1 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-server github.com/woodpecker-ci/woodpecker/cmd/server
-
-build-agent:
-	CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-agent github.com/woodpecker-ci/woodpecker/cmd/agent
-
-build-cli:
-	CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-cli github.com/woodpecker-ci/woodpecker/cmd/cli
-
-build: build-agent build-server build-cli
-
-release-frontend: build-frontend
-
-check-xgo:
 	@hash xgo > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		$(GO) install src.techknowlogick.com/xgo@latest; \
 	fi
 
-install-tools:
+install-tools: ## Install development tools
 	@hash golangci-lint > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest; \
 	fi ; \
@@ -145,7 +103,70 @@ install-tools:
 		go install mvdan.cc/gofumpt@latest; \
 	fi
 
-cross-compile-server:
+ui-dependencies: ## Install UI dependencies
+	(cd web/; yarn install --frozen-lockfile)
+
+##@ Test
+
+.PHONY: lint
+lint: install-tools ## Lint code
+	@echo "Running golangci-lint"
+	golangci-lint run --timeout 10m
+	@echo "Running zerolog linter"
+	lint github.com/woodpecker-ci/woodpecker/cmd/agent
+	lint github.com/woodpecker-ci/woodpecker/cmd/cli
+	lint github.com/woodpecker-ci/woodpecker/cmd/server
+
+lint-ui: ## Lint UI code
+	(cd web/; yarn)
+	(cd web/; yarn lesshint)
+	(cd web/; yarn lint --quiet)
+
+test-agent: ## Test agent code
+	go test -race -cover -coverprofile agent-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/agent github.com/woodpecker-ci/woodpecker/agent/...
+
+test-server: ## Test server code
+	go test -race -cover -coverprofile server-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/server $(shell go list github.com/woodpecker-ci/woodpecker/server/... | grep -v '/store')
+
+test-cli: ## Test cli code
+	go test -race -cover -coverprofile cli-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/cmd/cli github.com/woodpecker-ci/woodpecker/cli/...
+
+test-server-datastore: ## Test server datastore
+	go test -race -timeout 30s github.com/woodpecker-ci/woodpecker/server/store/...
+
+test-server-datastore-coverage: ## Test server datastore with coverage report
+	go test -race -cover -coverprofile datastore-coverage.out -timeout 30s github.com/woodpecker-ci/woodpecker/server/store/...
+
+test-ui: ui-dependencies ## Test UI code
+	(cd web/; yarn run lint)
+	(cd web/; yarn run formatcheck)
+	(cd web/; yarn run typecheck)
+	(cd web/; yarn run test)
+
+test-lib: ## Test lib code
+	go test -race -cover -coverprofile coverage.out -timeout 30s $(shell go list ./... | grep -v '/cmd\|/agent\|/cli\|/server')
+
+test: test-agent test-server test-server-datastore test-cli test-lib test-ui ## Run all tests
+
+##@ Build
+
+build-ui: ## Build UI
+	(cd web/; yarn install --frozen-lockfile; yarn build)
+
+build-server: build-ui ## Build server
+	CGO_ENABLED=1 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-server github.com/woodpecker-ci/woodpecker/cmd/server
+
+build-agent: ## Build agent
+	CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-agent github.com/woodpecker-ci/woodpecker/cmd/agent
+
+build-cli: ## Build cli
+	CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags '${LDFLAGS}' -o dist/woodpecker-cli github.com/woodpecker-ci/woodpecker/cmd/cli
+
+build: build-agent build-server build-cli ## Build all binaries
+
+release-frontend: build-frontend ## Build frontend
+
+cross-compile-server: ## Cross compile the server
 	$(foreach platform,$(subst ;, ,$(PLATFORMS)),\
 		TARGETOS=$(firstword $(subst |, ,$(platform))) \
 		TARGETARCH_XGO=$(subst arm64/v8,arm64,$(subst arm/v7,arm-7,$(word 2,$(subst |, ,$(platform))))) \
@@ -154,7 +175,7 @@ cross-compile-server:
 	)
 	tree dist
 
-release-server-xgo: check-xgo
+release-server-xgo: check-xgo ## Create server binaries for release using xgo
 	@echo "Building for:"
 	@echo "os:$(TARGETOS)"
 	@echo "arch orgi:$(TARGETARCH)"
@@ -165,13 +186,13 @@ release-server-xgo: check-xgo
 	mkdir -p ./dist/server/$(TARGETOS)/$(TARGETARCH_BUILDX)
 	mv /build/woodpecker-server-$(TARGETOS)-$(TARGETARCH_XGO) ./dist/server/$(TARGETOS)/$(TARGETARCH_BUILDX)/woodpecker-server
 
-release-server:
+release-server: ## Create server binaries for release
 	# compile
 	GOOS=linux GOARCH=amd64 CGO_ENABLED=1 go build -ldflags '${LDFLAGS}' -o dist/server/linux_amd64/woodpecker-server github.com/woodpecker-ci/woodpecker/cmd/server
 	# tar binary files
 	tar -cvzf dist/woodpecker-server_linux_amd64.tar.gz   -C dist/server/linux_amd64 woodpecker-server
 
-release-agent:
+release-agent: ## Create agent binaries for release
 	# compile
 	GOOS=linux   GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -o dist/agent/linux_amd64/woodpecker-agent   github.com/woodpecker-ci/woodpecker/cmd/agent
 	GOOS=linux   GOARCH=arm64 CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -o dist/agent/linux_arm64/woodpecker-agent   github.com/woodpecker-ci/woodpecker/cmd/agent
@@ -187,7 +208,7 @@ release-agent:
 	tar -cvzf dist/woodpecker-agent_darwin_amd64.tar.gz  -C dist/agent/darwin_amd64  woodpecker-agent
 	tar -cvzf dist/woodpecker-agent_darwin_arm64.tar.gz  -C dist/agent/darwin_arm64  woodpecker-agent
 
-release-cli:
+release-cli: ## Create cli binaries for release
 	# compile
 	GOOS=linux   GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -o dist/cli/linux_amd64/woodpecker-cli   github.com/woodpecker-ci/woodpecker/cmd/cli
 	GOOS=linux   GOARCH=arm64 CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -o dist/cli/linux_arm64/woodpecker-cli   github.com/woodpecker-ci/woodpecker/cmd/cli
@@ -203,7 +224,7 @@ release-cli:
 	tar -cvzf dist/woodpecker-cli_darwin_amd64.tar.gz  -C dist/cli/darwin_amd64  woodpecker-cli
 	tar -cvzf dist/woodpecker-cli_darwin_arm64.tar.gz  -C dist/cli/darwin_arm64  woodpecker-cli
 
-release-tarball:
+release-tarball: ## Create tarball for release
 	tar -cvzf dist/woodpecker-src-$(BUILD_VERSION).tar.gz \
 		agent \
 		cli \
@@ -228,31 +249,32 @@ release-tarball:
 		web/yarn.lock \
 		web/web.go
 
-release-checksums:
+release-checksums: ## Create checksums for all release files
 	# generate shas for tar files
 	(cd dist/; sha256sum *.* > checksums.txt)
 
-release: release-frontend release-server release-agent release-cli
+release: release-frontend release-server release-agent release-cli ## Release all binaries
 
-bundle-prepare:
+bundle-prepare: ## Prepare the bundles
 	go install github.com/goreleaser/nfpm/v2/cmd/nfpm@v2.6.0
 
-bundle-agent: bundle-prepare
+bundle-agent: bundle-prepare ## Create bundles for agent
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-agent.yml --target ./dist --packager deb
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-agent.yml --target ./dist --packager rpm
 
-bundle-server: bundle-prepare
+bundle-server: bundle-prepare ## Create bundles for server
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-server.yml --target ./dist --packager deb
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-server.yml --target ./dist --packager rpm
 
-bundle-cli: bundle-prepare
+bundle-cli: bundle-prepare ## Create bundles for cli
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager deb
 	VERSION_NUMBER=$(VERSION_NUMBER) nfpm package --config ./nfpm/nfpm-cli.yml --target ./dist --packager rpm
 
-bundle: bundle-agent bundle-server bundle-cli
+bundle: bundle-agent bundle-server bundle-cli ## Create all bundles
 
-.PHONY: version
+##@ Docs
-version:
+.PHONY: docs
-	@echo ${BUILD_VERSION}
+docs: ## Generate docs (currently only for the cli)
+	go generate cmd/cli/app.go
 
 endif