build(Makefile): add documentation (make help)

Makefile

@@ -33,8 +33,8 @@ export LOGSIZE ?= 1024
 # 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'.
+# If you want to do so anyway please use 'make -- [--target]' to avoid
+# '[--target]' being treated as option to 'make'.
 # 
 # 
 # Targets meant to be used by humans are:
@@ -55,14 +55,13 @@ help:
 .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-work .stack-work-build .stack-work-run .stack-work-test .stack-work-doc || :
-	-rm -rf bin .Dockerfile develop || :
+	-rm -rf node_modules .npm .cache assets/icons assets/favicons static well-known
+	-rm -rf .stack-work .stack-work-build .stack-work-run .stack-work-test .stack-work-doc
+	-rm -rf bin .Dockerfile develop
 .PHONY: clean-all
 # HELP: like clean but with container and image prune
-clean-all:
-	$(MAKE) clean
-	-rm -rf .stack || :
+clean-all: clean
+	-rm -rf .stack
 	-$(CONTAINER_COMMAND) system prune --all --force --volumes
 	-$(CONTAINER_COMMAND) image prune --all --force
 	-$(CONTAINER_COMMAND) volume prune --force
@@ -280,7 +279,7 @@ serve-database: --containerized-database;
 	$(MAKE) -- --image-run-$*-database
 
 .PHONY: image-rebuild
-# HELP: rebuild the stated docker image (frontend, backend, database instead of %)
+# HELP(image-rebuild-{backend,frontend,database,memcached,minio}): force-rebuild the stated docker image
 image-rebuild-%:
 	$(MAKE) -- --image-build FRADRIVE_SERVICE=$* NO_CACHE=--no-cache
 --image-build:
@@ -330,21 +329,26 @@ image-rebuild-%:
 #	DEV_PORT_HTTPS=`grep 'https:' develop/$(DATE)/backend/$(CONTAINER_ID) | sed 's/.*://'`; \
 #	./utils/watchrun.sh develop/ ./start.sh
 
-
-#CURRENT_DEVELOP = $(shell mkdir -p develop && (ls -1 develop | tail -n1))
-CURRENT_DEVELOP = $(shell if [[ ! -e develop ]] ; then mkdir develop; $(MAKE) develop ; fi && (ls -1 develop | tail -n1))
-DEVELOP      = develop/$(CURRENT_DEVELOP)
 DATE    := $(shell date +'%Y-%m-%dT%H-%M-%S')
-SET_DEVELOP = $(eval DEVELOP=develop/$$(DATE))
 
-.PHONY: develop
-develop:
-	$(SET_DEVELOP)
-	mkdir -p develop/$(DATE)
---ensure-develop:
+SET_DEVELOP = $(eval DEVELOP=develop/`ls -1 develop | tail -n1`)
+NEW_DEVELOP = $(eval DEVELOP=develop/$$(DATE))
+
+.PHONY: new-develop
+new-develop:
+	$(NEW_DEVELOP)
+	mkdir -p $(DEVELOP)
+	$(MAKE) .current-develop
+.PHONY: --develop
+--develop:
 	if ! [[ -e develop ]]; then \
-	  $(MAKE) develop; \
+	  $(MAKE) new-develop; \
 	fi
+	$(MAKE) .current-develop
+.PHONY: .current-develop
+.current-develop:
+	$(SET_DEVELOP)
+	echo "$(DEVELOP)" > .current-develop
 
 start: develop start-database start-memcached start-minio start-frontend start-backend;
 
@@ -365,8 +369,15 @@ start-hoogle:    BASE_PORTS = "HOOGLE_PORT=8081"
 start-hoogle:    SINGLETON=true
 
 start-frontend:  SINGLETON = false
-start-frontend:  WATCH = true
+start-frontend:  WATCH = false
 
+# HELP(start-database): start postgres server
+# HELP(start-memcached): start memcached server
+# HELP(start-minio): start minio server
+# HELP(start-backend): serve yesod development site
+# HELP(start-frontend): start frontend watcher. Watches frontend source files for changes and recompiles on change. (TODO: watcher functionality currently broken!)
+# HELP(start-hoogle): serve local hoogle instance
+# TODO: abort with error if a singleton service is already running
 start-%: FRADRIVE_SERVICE = %
 start-%: PORTS = $(foreach PORT,$(BASE_PORTS),$(shell utils/next_free_port.pl $(PORT)))
 start-%: --ensure-develop
@@ -406,10 +417,12 @@ start-%: --ensure-develop
 #	CONTAINER_ID=`$(CONTAINER_RUN) -v $(PWD):/mnt/fradrive --file docker/minio/Dockerfile -- (server $${MINIO_DIR})` ; \
 #	echo "CONTAINER_ID=$${CONTAINER_ID}" >> $(DEVELOP)/minio
 
-# TODO: work in progress
-# - kill container and remove file from .develop
-# TODO: find way to stop a single container, e.g. by removing the file
+.PHONY: stop
+# HELP: stop all currently running develop instances
+stop:
+	rm -rf develop
 .PHONY: stop-%
+# HELP(stop-{database,memcached,minio,backend,frontend,hoogle}): stop all currently running develop instances of a given type
 stop-%: --stop-%
 	rm -rf $(DEVELOP)/$*
 stop-container-by-file:
@@ -420,6 +433,7 @@ stop-container-by-id:
 #	$(MAKE) stop-container-by-id CONTAINER_ID=$${CONTAINER_ID}
 
 .PHONY: log-%
+# HELP(log-{database,memcached,minio,backend,frontend,hoogle}): inspect output of a given (currently running) service. When a service supports multiple running instances in one develop (i.e. backend), you need to specify the exact instance by its associated file (e.g. backend-1, backend-2, etc.), please check the contents of the develop/ directory for a list of running instances.
 log-%:
 	$(CONTAINER_COMMAND) logs --follow --tail=$(LOGSIZE) `cat develop/$(CURRENT_DEVELOP)/$* | grep CONTAINER_ID= | sed 's/^CONTAINER_ID=//'`
 
@@ -430,6 +444,8 @@ log-%:
 # TODO: move targets below to better location
 
 # Some convenience aliases:
+.PHONY: hoogle
+# HELP: alias for start-hoogle
 hoogle: start-hoogle;
 
 .PHONY: i18n-check