From b6f7e8af5f215fe4ec4f12216cbb109f141bf0d7 Mon Sep 17 00:00:00 2001
From: Sarah Vaupel <sarah.vaupel@uniworx.de>
Date: Thu, 17 Oct 2024 04:59:03 +0200
Subject: [PATCH] build(Makefile): add documentation (make help)

---
 Makefile | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index c9f92d2b1..73e4c0063 100644
--- a/Makefile
+++ b/Makefile
@@ -279,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:
@@ -335,7 +335,6 @@ SET_DEVELOP = $(eval DEVELOP=develop/`ls -1 develop | tail -n1`)
 NEW_DEVELOP = $(eval DEVELOP=develop/$$(DATE))
 
 .PHONY: new-develop
-# HELP: 
 new-develop:
 	$(NEW_DEVELOP)
 	mkdir -p $(DEVELOP)
@@ -370,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
@@ -411,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:
@@ -425,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=//'`
 
@@ -435,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