doc

make/def.mk

@@ -11,7 +11,7 @@ BRANCH                          ?= $(shell git rev-parse --abbrev-ref HEAD 2>/de
 CMDS                            ?= exec exec:% exec@% run run:% run@%
 COMMIT                          ?= $(shell git rev-parse $(BRANCH) 2>/dev/null)
 CONTEXT                         ?= $(if $(APP),APP BRANCH VERSION) $(shell awk 'BEGIN {FS="="}; $$1 !~ /^(\#|$$)/ {print $$1}' .env.dist 2>/dev/null)
-CONTEXT_DEBUG                   ?= APPS GIT_AUTHOR_EMAIL GIT_AUTHOR_NAME MAKEFILE_LIST MAKE_DIR MAKE_SUBDIRS MAKE_CMD_ARGS MAKE_ENV_ARGS MONOREPO_DIR UID USER env
+CONTEXT_DEBUG                   ?= MAKEFILE_LIST env APPS GIT_AUTHOR_EMAIL GIT_AUTHOR_NAME LOG_LEVEL MAKE_DIR MAKE_SUBDIRS MAKE_CMD_ARGS MAKE_ENV_ARGS MONOREPO_DIR UID USER
 DEBUG                           ?= false
 DOCKER                          ?= true
 DOMAIN                          ?= localhost
@@ -32,6 +32,7 @@ GIT_REPOSITORY                  ?= $(if $(SUBREPO),$(shell awk -F ' = ' '$$1 ~ /
 GIT_UPSTREAM_REPOSITORY         ?= $(if $(findstring ://,$(GIT_REPOSITORY)),$(call pop,$(call pop,$(GIT_REPOSITORY)))/,$(call pop,$(GIT_REPOSITORY),:):)$(GIT_UPSTREAM_USER)/$(lastword $(subst /, ,$(GIT_REPOSITORY)))
 GIT_UPSTREAM_USER               ?= $(or $(MONOREPO),$(USER))
 HOSTNAME                        ?= $(shell hostname 2>/dev/null |sed 's/\..*//')
+LOG_LEVEL                       ?= $(if $(filter false,$(VERBOSE)),error,$(if $(filter true,$(DEBUG)),debug))
 MAKE_ARGS                       ?= $(foreach var,$(MAKE_VARS),$(if $($(var)),$(var)='$($(var))'))
 MAKE_SUBDIRS                    ?= $(if $(filter myos,$(MYOS)),monorepo,$(if $(APP),apps $(foreach type,$(APP_TYPE),$(if $(wildcard $(MAKE_DIR)/apps/$(type)),apps/$(type)))))
 MAKE_CMD_ARGS                   ?= $(foreach var,$(MAKE_CMD_VARS),$(var)='$($(var))')
@@ -55,7 +56,7 @@ SUBREPO                         ?= $(if $(wildcard .gitrepo),$(notdir $(CURDIR))
 TAG                             ?= $(shell git tag -l --points-at $(BRANCH) 2>/dev/null)
 UID                             ?= $(shell id -u 2>/dev/null)
 USER                            ?= $(shell id -nu 2>/dev/null)
-VERBOSE                         ?= true
+VERBOSE                         ?= false
 VERSION                         ?= $(shell git describe --tags $(BRANCH) 2>/dev/null || git rev-parse $(BRANCH) 2>/dev/null)
 
 ifeq ($(DOCKER), true)
@@ -100,6 +101,8 @@ SED_SUFFIX                      := '\'\''
 endif
 endif
 
+# function conf: Extract variable=value line from configuration files
+## it prints the line with variable 3 definition from block 2 in file 1
 define conf
 	$(eval file := $(1))
 	$(eval block := $(2))
@@ -126,13 +129,15 @@ define conf
 	done < "$(file)"
 endef
 
+# macro force: Run command sine die
+# return never
+## it starts command if it is not already running
 force = $$(while true; do [ $$(ps x |awk 'BEGIN {nargs=split("'"$$*"'",args)} $$field == args[1] { matched=1; for (i=1;i<=NF-field;i++) { if ($$(i+field) == args[i+1]) {matched++} } if (matched == nargs) {found++} } END {print found+0}' field=4) -eq 0 ] && $(ECHO) $(command) || sleep 1; done)
 
+# macro gid: Return GID of group 1
 gid = $(shell grep '^$(1):' /etc/group 2>/dev/null |awk -F: '{print $$3}')
 
-##
-# function make
-## call make with predefined options and variables
+# function make: Call make with predefined options and variables
     # 1st arg: make command line (targets and arguments)
 	# 2nd arg: directory to call make from
 	# 3rd arg: list of variables to pass to make (ENV by default)
@@ -158,11 +163,14 @@ define make
 	$(if $(filter $(DRYRUN_RECURSIVE),true),$(MAKE) $(MAKE_DIR) $(patsubst %,-o %,$(MAKE_OLDFILE)) MAKE_OLDFILE="$(MAKE_OLDFILE)" DRYRUN=$(DRYRUN) RECURSIVE=$(RECURSIVE) $(MAKE_ARGS) $(cmd))
 endef
 
+# macro pop: Return last word of string 1 according to separator 2
 pop = $(patsubst %$(or $(2),/)$(lastword $(subst $(or $(2),/), ,$(1))),%,$(1))
 
+# macro sed: Exec sed script 1 on file 2
 sed = $(call exec,sed -i $(SED_SUFFIX) '\''$(1)'\'' $(2))
 
-# set ENV=$(env) for target ending with :$(env) and call $* target
+# function TARGET:ENV: Create a new target ending with :env
+## it sets ENV, ENV_FILE and calls original target
 define TARGET:ENV
 .PHONY: $(TARGET)
 $(TARGET): $(ASSIGN_ENV)
@@ -171,12 +179,14 @@ $(TARGET):
 	$$(call make,$$*,,ENV_FILE)
 endef
 
-# eval each target:$(env) targets
-# override value of $(ENV) with $(env)
-# override values of .env files with $(PARAMETERS)/$(env)/$(APP)/.env file
+# set ENV=env for targets ending with :env
+## for each env in ENV_LIST
+##  it overrides value of ENV with env
+##  it adds $(PARAMETERS)/$(env)/$(APP)/.env file to ENV_FILE
+##  it evals TARGET:ENV
 $(foreach env,$(ENV_LIST),$(eval TARGET := %\:$(env)) $(eval ASSIGN_ENV := ENV:=$(env)) $(eval ASSIGN_ENV_FILE := ENV_FILE+=$(wildcard $(PARAMETERS)/$(env)/$(APP)/.env)) $(eval $(TARGET:ENV)))
 
-# set ENV=$(env) for each target ending with @$(env)
+# set ENV=env for targets ending with @env
 $(foreach env,$(ENV_LIST),$(eval %@$(env): ENV:=$(env)))
 
 # Accept arguments for CMDS targets and turn them into do-nothing targets