diff --git a/Makefile b/Makefile index b8ee9647e..3381e0754 100644 --- a/Makefile +++ b/Makefile @@ -10,29 +10,44 @@ export db ?= -cf export DEV_PORT_HTTP export DEV_PORT_HTTPS +# HELP HEADER START +# To see the definition of all available targets, take a look into the Makefile. +# Targets starting with '--' are not meant to be directly called. +# If you want to do so anyway please use 'make -- [--target]' to not +# have '[--target]' to be treated as option to 'make'. +# +# +# Targets meant to be used by humans are: +# HELP HEADER END + ########################### ##### GENERAL TARGETS ##### .PHONY: help +# HELP: print out this help message help: @echo "Nothing to see here, go away" .PHONY: all +# HELP: unfinished all: @echo "TODO" .PHONY: clean +# HELP: remove all compilation results in the directory but leave containers and images unharmed clean: rm -rf node_modules .npm .cache assets/icons assets/favicons static well-known rm -rf .stack .stack-work .stack-work-build .stack-work-run .stack-work-test .stack-work-doc rm -rf bin/ .Dockerfile .dev-port-http .dev-port-https .PHONY: clean-all +# HELP: like clean but with container and image prune clean-all: clean $(CONTAINER_COMMAND) system prune --all --force --volumes $(CONTAINER_COMMAND) image prune --all --force $(CONTAINER_COMMAND) volume prune --force .PHONY: release +# HELP: unfinished release: ./.gitlab-ci/version.pl -changelog CHANGELOG.md git add CHANGELOG.md @@ -56,6 +71,7 @@ release: ##### UNIFIED FRONTEND/BACKEND TARGETS ##### .PHONY: serve +# HELP: serve frontend, backend, and database serve: CONTAINER_INTERACTIVE=-it serve: $(MAKE) serve-database & @@ -63,12 +79,15 @@ serve: $(MAKE) serve-backend .PHONY: compile +# HELP: compile frontend and backend compile: compile-frontend compile-backend .PHONY: lint +# HELP: lint frontend and backend lint: lint-frontend lint-backend .PHONY: test +# HELP: test frontend, backend, and check internationalization test: test-frontend test-backend i18n-check ##### UNIFIED FRONTEND/BACKEND TARGETS ##### @@ -85,11 +104,13 @@ test: test-frontend test-backend i18n-check .PHONY: --%-frontend --%-frontend: --containerized---frontend-dependencies-frontend; +# HELP(compile-frontend): compile frontend .PHONY: --compile-frontend --compile-frontend: --frontend-dependencies npx -- webpack --progress $(WATCH) .PHONY: serve-frontend +# HELP: serve frontend (watch file changes) serve-frontend: CONTAINER_INTERACTIVE=-it serve-frontend: $(MAKE) -- --containerized---compile-frontend WATCH=--watch @@ -98,11 +119,13 @@ serve-frontend: # --serve-frontend: WATCH=--watch # --serve-frontend: --compile-frontend; +# HELP(lint-frontend): lint frontend .PHONY: --lint-frontend --lint-frontend: eslint.config.js npx -- eslint frontend/src $(FIX) @echo Hooray! There are no hints. +# HELP(test-frontend): test frontend .PHONY: --test-frontend --test-frontend: karma.conf.cjs @echo Karma frontend tests are currently broken after npm update and have therefor been temporarily disabled. @@ -153,6 +176,7 @@ well-known: node_modules assets --%-prod-backend: --image-build --containerized-%-backend; .PHONY: serve-backend +# HELP: serve backend serve-backend: CONTAINER_INTERACTIVE=-it serve-backend: DEV_PORT_HTTP=`docker/backend/dev_port.pl 3000 | tee .dev-port-http`; \ @@ -164,19 +188,23 @@ serve-backend: DEV_PORT_HTTPS=`cat .dev-port-https`; \ ./start.sh +# HELP(compile-backend): compile backend .PHONY: --compile-backend --compile-backend: stack build --fast --profile --library-profiling --executable-profiling --flag uniworx:-library-only --local-bin-path $$(pwd)/bin $(stackopts) +# HELP(lint-backend): lint backend .PHONY: --lint-backend --lint-backend: stack build --test --fast --flag uniworx:library-only uniworx:test:hlint $(stackopts) +# HELP(test-backend): test backend .PHONY: --test-backend --test-backend: stack build --test --coverage --fast --flag uniworx:library-only $(stackopts) .PHONY: serve-database +# HELP: serve database serve-database: CONTAINER_INTERACTIVE=-it serve-database: --containerized-database @@ -230,6 +258,7 @@ serve-database: --containerized-database $(MAKE) -- --image-run-$*-backend .PHONY: image-rebuild +# HELP: rebuild the stated docker image (frontend, backend, database instead of %) image-rebuild-%: $(MAKE) -- --image-build FRADRIVE_SERVICE=$* NO_CACHE=--no-cache .PHONY: --image-build @@ -259,6 +288,7 @@ image-rebuild-%: .PHONY: i18n-check +# HELP: check internationalization i18n-check: --image-run---i18n-check .PHONY: --i18n-check --i18n-check: diff --git a/utils/makehelp.pl b/utils/makehelp.pl new file mode 100755 index 000000000..d3a81b3b8 --- /dev/null +++ b/utils/makehelp.pl @@ -0,0 +1,40 @@ +#!/usr/bin/env perl + +use strict; +use warnings; + +my %msg = (); +my @start = (); + +READ: while(<>) { + if(m/^# HELP HEADER START/) { + while(<>) { + next READ if m/^# HELP HEADER END/; + if(m/# (.*)/) { + push @start, $1 + } else { + die "$0: Invalid HELP HEADER section in Makefile!\n"; + } + } + next READ + } + if(m/# HELP((?:\([^\(\)]+\))?):\s*(.*)/) { + my ($target, $message) = ($1, $2); + if($target=~m/\((.*)\)/) { + $target = $1; + } else { + my $line = <>; + die "$0: Unexpected end of file, target expected!\n" if not defined $line; + $line=~m/^([^:]+):/ or die "$0: HELP marker expects target but no target found!\n"; + $target = $1 + } + $msg{$target} .= $message + } +} + +print "$_\n" for @start; +print "\n" if @start; +for my $tar(sort keys %msg) { + print "$tar\n $msg{$tar}\n\n" +} +