Makefile

# ---------------------------------------
# Author: David Marsh <rdmarsh@gmail.com>
# ---------------------------------------
#
# This Makefile is used to generate files for elm
#   for usage: make help
#   more info: make about
#
# elm Extract LogicMonitor
# Copyright (C) 2021--2026 David Marsh rdmarsh@gmail.com
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.

# MAKE FLAGS
#MAKEFLAGS += -j4
EDITABLE ?= --editable

# API VERSION
# ---------------------------------------
# set to '3' to use api v3, anything else will use v2
apiversion ?= 3

# FILE EXTENSIONS
# ---------------------------------------
# change only if needed

JSN ?= json
J2 ?= j2
PY ?= py

# SOURCE DIR and FILENAMES
# ---------------------------------------
# change only if needed

name := elm
prog := $(name).$(PY)


cfgdir := $(HOME)/.config/logicmonitor/credentials
bindir := $(HOME)/bin
XDG_DATA_HOME ?= $(HOME)/.local/share
compdir := $(XDG_DATA_HOME)/bash-completion/completions
cmddir := _cmds
defdir := _defs
jnjdir := _jnja

# EXECUTABLE AND PROGRAM FLAGS
# ---------------------------------------
# change only if needed

CURL ?= curl
JQ ?= jq
AWK ?= awk
JINJA ?= venv/bin/jinja2

# for testing non-required commands
GREP ?= grep
GREPFLAGS = -l

#python
PYTHON ?= python3

# venv location
VENV := venv

# pip for install
PIP ?= $(VENV)/bin/$(PYTHON) -m pip
PIPFLAGS = install
REQUIREMENTS = requirements.txt

# for pyinstaller
pyiworkdir := _build
pyidistdir := _dist
testbin := $(pyidistdir)/$(name)/$(name)
PYINST ?= $(VENV)/bin/pyinstaller
# --collect-all=pandas/numpy is blunt: it drags in the libraries' own test
# suites (~29M of pandas/tests + numpy/*/tests) that elm never imports. They
# are removed by the post-build prune in the _build recipe. NB: do not also
# use --exclude-module here -- --collect-all registers every test submodule as
# an explicit hidden import, which --exclude-module then drops, emitting
# thousands of spurious "ERROR: Hidden import not found" lines. The prune is
# the clean mechanism.
PYINSTFLAGS += --name $(name) --hidden-import=engine --collect-all=_cmds --collect-all=pandas --collect-all=numpy --log-level WARN --workpath $(pyiworkdir) --distpath $(pyidistdir) --noconfirm

# SWAGGER PATHS AND API VERSION
# ---------------------------------------
# do not change

SWAGGER_V2_URL := https://www.logicmonitor.com/swagger-ui-master/dist/swagger.json
SWAGGER_V3_URL := https://www.logicmonitor.com/swagger-ui-master/api-v3/dist/swagger.json

ifneq ($(apiversion),3)
apiversion = 2
endif

ifeq ($(apiversion),3)
lm_swagger_url := $(SWAGGER_V3_URL)
else
lm_swagger_url := $(SWAGGER_V2_URL)
endif

# BUILD VARIABLES
# ---------------------------------------
# do not change

CMDSOURCES := $(wildcard $(defdir)/[A-Z]*.$(JSN))
CMDTARGETS := $(patsubst $(defdir)/%.$(JSN),$(cmddir)/%.$(PY),$(CMDSOURCES))

TSTTARGETS := $(patsubst $(defdir)/%.$(JSN),%,$(CMDSOURCES))
REQSOURCES = $(patsubst $(defdir)/%.$(JSN),%,$(shell $(GREP) $(GREPFLAGS) "\"required\":true" $(CMDSOURCES)))

NONREQTARGETS = $(filter-out ExternalApiStats $(REQSOURCES),$(TSTTARGETS))

# All output formats supported by elm
FORMATS_ALL = csv html prettyhtml jira json jsonl prettyjson xml prettyxml gfm latex md pipe rst tab tsv values raw txt api curl wget
# Formats that support -H (hide headers) and -I (show index) flags (excludes json, jsonl, prettyjson, xml, prettyxml, raw, api)
FORMATS_HDR = csv html prettyhtml jira gfm latex md pipe rst tab tsv txt
# Formats that support --head and --foot custom text (text-based table formats only)
FORMATS_TXT = jira gfm md pipe rst tab txt

# COLOUR OUTPUT
# ---------------------------------------
# do not change

NO_COLOR=\033[0m
OK_COLOR=\033[0;32m
IN_COLOR=\033[0;34m
WR_COLOR=\033[0;33m
ER_COLOR=\033[0;31m
OK_STRING=$(OK_COLOR)[OK]$(NO_COLOR)
IN_STRING=$(IN_COLOR)[INFO]$(NO_COLOR)
WR_STRING=$(WR_COLOR)[WARN]$(NO_COLOR)
ER_STRING=$(ER_COLOR)[ERROR]$(NO_COLOR)

# TARGETS
# ---------------------------------------
# do not change

.PHONY: all
all: init ## Build everything except install (init, render, cfg, build)
	$(MAKE) _render _build
	@echo "$(OK_STRING) $@"

# INIT FOR COMPILE
# =======================================
# do not change
 
.PHONY: init
init: $(defdir)/commands.$(JSN) upgrade ## Check prerequisites, initialise dirs, get swagger file, create definition files, install jinja2-cli
	$(GREP) -m1 jinja2-cli $(REQUIREMENTS) | xargs -r $(PIP) $(PIPFLAGS)
	@echo "$(OK_STRING) $@"

# REQ FOR COMPILE
# =======================================
# do not change

.PHONY: PYTHON-exists CURL-exists JINJA-exists JQ-exists AWK-exists PYINST-exists
PYTHON-exists: ; @which $(PYTHON) || { echo "$(ER_STRING) $(PYTHON) not found"; exit 1; }
PYINST-exists: ; @which $(PYINST) || { echo "$(ER_STRING) $(PYINST) not found"; exit 1; }
CURL-exists:   ; @which $(CURL)   || { echo "$(ER_STRING) $(CURL) not found"; exit 1; }
JINJA-exists:  ; @which $(JINJA)  || { echo "$(ER_STRING) $(JINJA) not found"; exit 1; }
JQ-exists:     ; @which $(JQ)     || { echo "$(ER_STRING) $(JQ) not found"; exit 1; }
AWK-exists:    ; @which $(AWK)    || { echo "$(ER_STRING) $(AWK) not found"; exit 1; }

# REQ DIRS
# =======================================
# do not change

$(cmddir) $(defdir) $(cfgdir) $(bindir):
	mkdir -p $@
	@echo "$(OK_STRING) $@"

$(compdir):
	mkdir -p $@
	@echo "$(OK_STRING) $@"

# Combine the commands.*.json files into one for use by jinja later.
# The top-level all target calls make again after init so CMDTARGETS is
# populated from the freshly-created per-command definition files.

$(defdir)/commands.$(JSN): $(defdir)/commands.documented.$(JSN) $(defdir)/commands.undocumented.$(JSN) | $(defdir) JQ-exists
	$(JQ) -s '{commands: (.[0].commands + .[1].commands)}' $^ > $@
	@echo "$(OK_STRING) $@"

# The commands.*.json files are used to trigger when the individual defs
# need to be (re)built as we don't know the names of the individual def
# files at this stage and CMDSOURCES isn't populated. There's probably
# a better way to do this, but this will do for now. First jq creates
# commands.*.json from the swagger files. Second jq creates individual
# def json files from commands.*.json files

# cant split these long lines, high level magic
# https://stackoverflow.com/questions/56167046/jq-split-a-huge-json-of-array-and-save-into-file-named-with-a-value

$(defdir)/commands.documented.$(JSN): $(defdir)/swagger.$(JSN) $(MAKEFILE_LIST) | $(defdir) JQ-exists
	$(JQ) '{ "commands": [ .paths | to_entries[] | .key as $$path | .value | to_entries[] | select(.key == "get") | .value.operationId as $$opid | .value.operationId |= gsub("^(get|collect|fetch)";"") | { opid:$$opid, command:.value.operationId, path:$$path, summary:.value.summary, tag:.value.tags[0], options:(.value.parameters // []) } ]}' $< > $@
	$(JQ) -c '.commands[] | (.command | if type == "number" then . else tostring | gsub("[^A-Za-z0-9-_]";"+") end), .' $@ | $(AWK) 'function fn(s) { sub(/^"/,"",s); sub(/"$$/,"",s); return "$(defdir)/" s ".$(JSN)"; } NR%2{f=fn($$0); next} {print > f; close(f);} '
	@echo "$(OK_STRING) $@"

$(defdir)/commands.undocumented.$(JSN): ./swagger.undocumented.$(JSN) $(MAKEFILE_LIST) | $(defdir) JQ-exists
	$(JQ) '{ "commands": [ .paths | to_entries[] | .key as $$path | .value | to_entries[] | select(.key == "get") | .value.operationId as $$opid | .value.operationId |= gsub("^(get|collect|fetch)";"") | { opid:$$opid, command:.value.operationId, path:$$path, summary:.value.summary, tag:.value.tags[0], options:(.value.parameters // []) } ]}' $< > $@
	$(JQ) -c '.commands[] | (.command | if type == "number" then . else tostring | gsub("[^A-Za-z0-9-_]";"+") end), .' $@ | $(AWK) 'function fn(s) { sub(/^"/,"",s); sub(/"$$/,"",s); return "$(defdir)/" s ".$(JSN)"; } NR%2{f=fn($$0); next} {print > f; close(f);} '
	@echo "$(OK_STRING) $@"

$(defdir)/swagger.$(JSN): $(MAKEFILE_LIST) | $(defdir) CURL-exists
	$(CURL) $(lm_swagger_url) $(OUTPUT_OPTION)
	@echo "$(OK_STRING) $@"

.PHONY: cfg
cfg: $(cfgdir)/config.example.ini ## Create config dir, copy example file and set permissions of all config files
	@echo "$(OK_STRING) $@"

.PHONY: $(cfgdir)/config.example.ini
$(cfgdir)/config.example.ini: config.example.ini | $(cfgdir)
	cmp -s $< $@ || cp $< $@
	chmod 600 $(@D)/*
	@if [ ! -s $(@D)/config.ini ] ; then \
		echo ;\
		echo "$(OK_COLOR)>>> API credentials can be placed in an ini file <<<$(NO_COLOR)" ;\
		echo ;\
		echo "cp $(@D)/config.example.ini $(@D)/config.ini" ;\
		echo "vi $(@D)/config.ini" ;\
		echo ;\
		echo ;\
	fi
	@echo "$(OK_STRING) $@"

# BUILD AND INSTALL COMMANDS
# =======================================
# do not change

.PHONY: render _render
render: init ## Make python commands from templates and install requirements
	$(MAKE) _render
	@echo "$(OK_STRING) $@"

_render: engine.$(PY) $(prog) elm-completion.bash $(cmddir)/__init__.$(PY)

$(cmddir)/__init__.$(PY): | $(cmddir)
	touch $@
	@echo "$(OK_STRING) $@"

elm-completion.bash: $(jnjdir)/elm-completion.bash.$(J2) $(defdir)/commands.$(JSN) | JINJA-exists
	$(JINJA) $^ $(OUTPUT_OPTION)
	@echo "$(OK_STRING) $@"

$(prog): $(jnjdir)/$(prog).$(J2) $(defdir)/commands.$(JSN) $(CMDTARGETS) | JINJA-exists
	$(JINJA) $(jnjdir)/$(prog).$(J2) $(defdir)/commands.$(JSN) $(OUTPUT_OPTION)
	@echo "$(OK_STRING) $@"

engine.$(PY): $(jnjdir)/engine.$(PY).$(J2) $(defdir)/commands.$(JSN) | JINJA-exists
	$(JINJA) -D apiversion=$(apiversion) $^ $(OUTPUT_OPTION)
	@echo "$(OK_STRING) $@"

$(cmddir)/%.$(PY): $(jnjdir)/command.$(PY).$(J2) $(defdir)/%.$(JSN) | $(cmddir) JINJA-exists
	$(JINJA) -D apiversion=$(apiversion) $^ $(OUTPUT_OPTION)
	@echo "$(OK_STRING) $@"

.PHONY: build _build
build: init ## (Re)build the script
	$(MAKE) _render _build
	@echo "$(OK_STRING) $@"

_build: $(pyidistdir)/$(name)/$(name)

# Real inputs are the rendered sources: engine.py, elm.py (which itself depends
# on $(CMDTARGETS), so it re-renders whenever any command module changes) and
# the _cmds package marker. reqs is order-only -- it still runs every time to
# keep deps installed, but being phony it must NOT be a normal prerequisite or
# it would force a full rebuild on every make/install/docs invocation.
$(pyidistdir)/$(name)/$(name): engine.$(PY) $(prog) $(cmddir)/__init__.$(PY) | reqs PYTHON-exists PYINST-exists
	$(PIP) $(PIPFLAGS) $(EDITABLE) .
	$(PYINST) $(PYINSTFLAGS) $(prog)
	-find $(pyidistdir)/$(name)/_internal -type d -name tests \( -path '*/pandas/*' -o -path '*/numpy/*' \) -prune -exec $(RM) -r {} +
	@echo "$(OK_STRING) $@"

.PHONY: completion
completion: $(compdir)/$(name) ## Install bash completion to XDG data dir

$(compdir)/$(name): elm-completion.bash | $(compdir)
	cp elm-completion.bash $(compdir)/$(name)
	@echo "$(OK_STRING) bash completion installed to $(compdir)/$(name)"

# Like all/build, install must run init first and then re-invoke make:
# from a clean tree CMDTARGETS is computed before init creates _defs/, so a
# plain prerequisite chain would build the binary with no command modules
# (and fail earlier at JINJA-exists, since only init installs jinja2-cli).
.PHONY: install _install
install: init ## (Re)installs the script and modifies the path
	$(MAKE) _render _build _install
	@echo
	@echo "$(OK_COLOR)>>> If needed, you can add \$${HOME}/bin to your \$$PATH like this <<<$(NO_COLOR)"
	@echo
	@echo "echo 'export PATH=\"\$${HOME}/bin:\$${PATH}\"' >> \$${HOME}/.bash_profile"
	@echo "source ~/.bash_profile"
	@echo
	@echo "$(OK_COLOR)>>> Bash completion installed to $(compdir)/$(name) <<<$(NO_COLOR)"
	@echo "bash-completion 2.x sources this automatically. If not working, add to ~/.bash_profile:"
	@echo "source $(compdir)/$(name)"
	@echo
	@echo "$(OK_COLOR)>>> Finished <<<$(NO_COLOR)"
	@echo
	@echo "You can now run '$(OK_COLOR)elm$(NO_COLOR)' from anywhere on the cli"
	@uname -s | grep -q Darwin && echo "$(WR_COLOR)Note:$(NO_COLOR) macOS Gatekeeper verifies new binaries on first run - expect 10-30 seconds once per install, then normal speed" || true
	@echo
	@echo "$(OK_STRING) $@"

_install: $(bindir)/$(name) cfg completion

.PHONY: hooks
hooks: ## Install git hooks (run once after cloning)
	git config core.hooksPath .githooks
	@echo "$(OK_STRING) $@"

.PHONY: docs
docs: $(testbin) ## Inject elm --help output into README.md between marker comments
	$(testbin) --help | sed 's|$(HOME)|/home/user|g' > /tmp/elm_help.txt
	$(AWK) '/^<!-- elm-help-start -->$$/{print; print "```text"; while ((getline line < "/tmp/elm_help.txt") > 0) print line; print "```"; skip=1; next} /^<!-- elm-help-end -->$$/{skip=0} !skip{print}' README.md > /tmp/README_tmp.md
	mv /tmp/README_tmp.md README.md
	rm /tmp/elm_help.txt
	@echo "$(OK_STRING) $@"

$(bindir)/$(name): $(pyidistdir)/$(name)/$(name) | $(bindir)
	$(RM) -r $(dir $@)_internal
	cp -r $(pyidistdir)/$(name)/_internal $(dir $@)
	install -m 755 $< $@
	@echo "$(OK_STRING) $@"

.PHONY: reqs
reqs: $(REQUIREMENTS) upgrade | PYTHON-exists ## Install python requirements
	$(PIP) $(PIPFLAGS) -r $<
	@echo "$(OK_STRING) $@"

.PHONY: upgrade
upgrade: $(VENV) | PYTHON-exists ## Upgrade pip
	$(PIP) $(PIPFLAGS) --upgrade pip

$(VENV): | PYTHON-exists
	$(PYTHON) -m venv $@
	@echo "$(OK_STRING) $@"

# TESTS
# =======================================
# do not change

.PHONY: test
test: testbasic testfmts testfmtcontent testsqlite testverb testid ## Run quick and simple tests
	@echo "$(OK_STRING) $@"

.PHONY: testlong
testlong: testhelp testcount testtotal testtext ## Tests that take a long time to complete
	@echo "$(OK_STRING) $@"

.PHONY: testbasic
testbasic: ## Test basic flags
	@echo testing: $(testbin) ; $(testbin) >/dev/null
	@echo testing: $(testbin) --help ; $(testbin) --help >/dev/null
	@echo testing: $(testbin) -h ; $(testbin) -h >/dev/null
	@echo testing: $(testbin) --version ; $(testbin) --version >/dev/null
	@echo testing: $(testbin) -V ; $(testbin) -V >/dev/null
	@echo testing: $(testbin) --help includes --profile ; $(testbin) --help | grep -q -- '--profile'
	@echo testing: --profile foo.ini strips .ini extension ; $(testbin) --profile __elm_test__.ini DeviceList 2>&1 | grep -qE 'Config file:.*__elm_test__\.ini$$'
	@echo testing: $(testbin) --list ; $(testbin) --list >/dev/null
	@echo testing: $(testbin) -l ; $(testbin) -l >/dev/null
	@echo testing: --list marks default profile active ; $(testbin) --list | grep -q '^\* config'
	@echo testing: --help includes --list ; $(testbin) --help | grep -q -- '--list'
	@echo testing: $(testbin) --ai ; $(testbin) --ai >/dev/null
	@echo testing: --ai output includes elm-notes.yaml ; $(testbin) --ai | grep -q 'elm-notes.yaml'
	@echo testing: --help includes --ai ; $(testbin) --help | grep -q -- '--ai'
	@echo testing: multiple -F flags both appear in URL ; $(testbin) -f api DeviceList -F 'hostStatus:normal' -F 'displayName~foo' -s1 2>/dev/null | grep -q 'hostStatus'
	@echo testing: trailing backslash in filter value is escaped ; $(testbin) -f api DeviceList -F 'hostname~foo\' -s1 2>/dev/null | grep -q 'filter=hostname~%22foo%5C%5C%22'
	@echo testing: embedded quote in filter value is escaped ; $(testbin) -f api DeviceList -F 'hostname~a"b' -s1 2>/dev/null | grep -q 'filter=hostname~%22a%5C%22b%22'
	@echo testing: curl format outputs curl command ; $(testbin) -f curl DeviceList -s1 2>/dev/null | grep -q '^curl '
	@echo testing: wget format outputs wget command ; $(testbin) -f wget DeviceList -s1 2>/dev/null | grep -q '^wget '
	@echo testing: sqlite format requires -o flag ; $(testbin) -f sqlite MetricsUsage 2>&1 | grep -q 'requires -o'
	@$(foreach cmd,$(TSTTARGETS), \
		echo testing: $(testbin) $(cmd) --help ;\
		$(testbin) $(cmd) --help >/dev/null || exit 1 ;\
		)
	@echo "$(OK_STRING) $@"

.PHONY: testtext
testtext: testH testI testHI testhead testfoot testheadfoot ## Test commands that alter columns, indices, header and footer
	@echo "$(OK_STRING) $@"

.PHONY: testhelp
testhelp: ## Test all commands with help flag
	@$(foreach cmd,$(TSTTARGETS), \
		echo testing: $(testbin) $(cmd) --help ;\
		$(testbin) $(cmd) --help >/dev/null || exit 1 ;\
		)
	@echo "$(OK_STRING) $@"

.PHONY: testid
testid: ## Test a command with an id flag                (connects to LM)
	@echo testing: $(testbin) AdminById --id 2 ; $(testbin) AdminById --id 2 ;
	@echo "$(OK_STRING) $@"

.PHONY: testcount
testcount: ## Test 'non-required' commands with count flag  (connects to LM)
	@$(foreach cmd,$(NONREQTARGETS), \
		echo testing: $(testbin) $(cmd) -c ;\
		$(testbin) $(cmd) -c || exit 1 ;\
		)
	@echo "$(OK_STRING) $@"

.PHONY: testcountdebug
testcountdebug: ## Test count flag with verbose debug output (connects to LM)
	@$(foreach cmd,$(NONREQTARGETS), \
		echo testing: $(testbin) -vv $(cmd) -c ;\
		$(testbin) -vv $(cmd) -c || exit 1 ;\
		)

.PHONY: testtotal
testtotal: ## Test 'non-required' commands with total flag  (connects to LM)
	@$(foreach cmd,$(NONREQTARGETS), \
		echo testing: $(testbin) $(cmd) -C ;\
		$(testbin) $(cmd) -C || exit 1 ;\
		)
	@echo "$(OK_STRING) $@"

.PHONY: testfmts
testfmts: ## Test a command with all formats               (connects to LM)
	@$(foreach fmt,$(FORMATS_ALL), \
		echo testing: $(testbin) --format $(fmt) MetricsUsage ; \
		$(testbin) --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

# testfmts only checks exit 0; this asserts each format's output is actually
# that format (catches a format silently producing the wrong structure or
# being aliased to another). Anchored to MetricsUsage like the other targets.
.PHONY: testfmtcontent
testfmtcontent: | JQ-exists ## Assert each format's output really is that format (connects to LM)
	@echo testing: csv is comma-delimited ; $(testbin) -f csv MetricsUsage 2>/dev/null | head -1 | grep -qE '^[A-Za-z].*,'
	@echo testing: tsv contains a real tab ; $(testbin) -f tsv MetricsUsage 2>/dev/null | grep -q "$$(printf '\t')"
	@echo testing: html is a minified table ; $(testbin) -f html MetricsUsage 2>/dev/null | grep -q '<table border=1'
	@echo testing: prettyhtml is a non-minified table ; $(testbin) -f prettyhtml MetricsUsage 2>/dev/null | grep -q 'border="1"'
	@echo testing: jira uses '||' header delimiter ; $(testbin) -f jira MetricsUsage 2>/dev/null | grep -q '||'
	@echo testing: json is valid and wrapped in command name ; $(testbin) -f json MetricsUsage 2>/dev/null | $(JQ) -e 'has("MetricsUsage")' >/dev/null
	@echo testing: jsonl is valid json per line and unwrapped ; out=$$($(testbin) -f jsonl MetricsUsage 2>/dev/null) ; echo "$$out" | $(JQ) -se 'length>0 and all(.[]; type=="object")' >/dev/null && ! echo "$$out" | grep -q MetricsUsage
	@echo testing: prettyjson is multi-line and wrapped ; out=$$($(testbin) -f prettyjson MetricsUsage 2>/dev/null) ; echo "$$out" | grep -q MetricsUsage && [ "$$(echo "$$out" | wc -l)" -gt 1 ]
	@echo testing: xml is compact ; $(testbin) -f xml MetricsUsage 2>/dev/null | grep -q '<data><row>'
	@echo testing: prettyxml is indented ; $(testbin) -f prettyxml MetricsUsage 2>/dev/null | grep -q '^  <row>'
	@echo testing: gfm has a markdown separator row ; $(testbin) -f gfm MetricsUsage 2>/dev/null | grep -q '^|-'
	@echo testing: latex has a tabular environment ; $(testbin) -f latex MetricsUsage 2>/dev/null | grep -q 'begin{tabular}'
	@echo testing: md has a separator line ; $(testbin) -f md MetricsUsage 2>/dev/null | grep -q -- '-----'
	@echo testing: pipe has alignment colons ; $(testbin) -f pipe MetricsUsage 2>/dev/null | grep -q -- '-:'
	@echo testing: rst is a grid table ; $(testbin) -f rst MetricsUsage 2>/dev/null | grep -q '==='
	@echo testing: tab has a separator line ; $(testbin) -f tab MetricsUsage 2>/dev/null | grep -q -- '-----'
	@echo testing: raw is a python dict repr ; $(testbin) -f raw MetricsUsage 2>/dev/null | grep -q "{'"
	@echo testing: txt has no separator line ; $(testbin) -f txt MetricsUsage 2>/dev/null | sed -n 2p | grep -qE '^ *[0-9]'
	@echo testing: api prints the authorization header ; $(testbin) -f api MetricsUsage 2>/dev/null | grep -q '^Authorization: LMv1'
	@echo testing: curl prints a curl command ; $(testbin) -f curl MetricsUsage 2>/dev/null | grep -q '^curl -H'
	@echo testing: wget prints a wget command ; $(testbin) -f wget MetricsUsage 2>/dev/null | grep -q '^wget '
	@echo testing: values single-field is a bare value with no header ; $(testbin) -f values MetricsUsage -f numberOfDevices 2>/dev/null | grep -qE '^[0-9]+$$'
	@echo testing: values multi-field is tab-separated with no header ; out=$$($(testbin) -f values MetricsUsage -f numberOfDevices,numberOfStandardDevices 2>/dev/null) ; echo "$$out" | grep -q "$$(printf '\t')" && ! echo "$$out" | grep -qi 'numberOfDevices'
	@echo "$(OK_STRING) $@"

.PHONY: testsqlite
testsqlite: ## Test sqlite format with a temp file         (connects to LM)
	@tmp=$$(mktemp /tmp/elm-test-XXXXXX.sqlite) ; \
	echo "testing: sqlite format appends rows with fetched_at" ; \
	$(testbin) -f sqlite -o $$tmp MetricsUsage 2>&1 | grep -q 'Appended' || (rm -f $$tmp; exit 1) ; \
	python3 -c "import sqlite3; c=sqlite3.connect('$$tmp'); r=c.execute('SELECT fetched_at FROM metrics_usage LIMIT 1').fetchone(); assert r and r[0].endswith('Z'), 'fetched_at missing or wrong format'; print('fetched_at ok')" || (rm -f $$tmp; exit 1) ; \
	echo "testing: sqlite format appends on second run" ; \
	$(testbin) -f sqlite -o $$tmp MetricsUsage 2>/dev/null ; \
	python3 -c "import sqlite3; c=sqlite3.connect('$$tmp'); n=c.execute('SELECT COUNT(*) FROM metrics_usage').fetchone()[0]; assert n>1, f'expected >1 rows after two appends, got {n}'; print(f'append ok: {n} rows')" || (rm -f $$tmp; exit 1) ; \
	rm -f $$tmp
	@echo "$(OK_STRING) $@"

.PHONY: testH
testH: ## Test a command and hide headers               (connects to LM)
	@$(foreach fmt,$(FORMATS_HDR), \
		echo testing: $(testbin) -H --format $(fmt) MetricsUsage ; \
		$(testbin) -H --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testI
testI: ## Test a command and show index                 (connects to LM)
	@$(foreach fmt,$(FORMATS_HDR), \
		echo testing: $(testbin) -I --format $(fmt) MetricsUsage ; \
		$(testbin) -I --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testHI
testHI: ## Test a command, hide headers and show index   (connects to LM)
	@$(foreach fmt,$(FORMATS_HDR), \
		echo testing: $(testbin) -H -I --format $(fmt) MetricsUsage ; \
		$(testbin) -H -I --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testhead
testhead: ## Test a command, custom header text            (connects to LM)
	@$(foreach fmt,$(FORMATS_TXT), \
		echo testing: $(testbin) --head \"this is header text\" --format $(fmt) MetricsUsage ; \
		$(testbin) --head "this is header text" --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testfoot
testfoot: ## Test a command, custom footer text            (connects to LM)
	@$(foreach fmt,$(FORMATS_TXT), \
		echo testing: $(testbin) --foot \"this is footer text\" --format $(fmt) MetricsUsage ; \
		$(testbin) --foot "this is footer text" --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testheadfoot
testheadfoot: ## Test a command, custom header and footer text (connects to LM)
	@$(foreach fmt,$(FORMATS_TXT), \
		echo testing: $(testbin) --head \"this is header text\" --foot \"this is footer text\" --format $(fmt) MetricsUsage ; \
		$(testbin) --head "this is header text" --foot "this is footer text" --format $(fmt) MetricsUsage || exit 1 ; \
	)
	@echo "$(OK_STRING) $@"

.PHONY: testverb
testverb: ## Test the verbose flags                        (connects to LM)
	@echo testing: $(testbin) -v  MetricsUsage ; $(testbin) -v  MetricsUsage
	@echo testing: $(testbin) -vv MetricsUsage ; $(testbin) -vv MetricsUsage
	@echo "$(OK_STRING) $@"

.PHONY: fail
fail: ## A failing test
	@echo test false ; false >/dev/null

# CLEANUP
# =======================================
# do not change

.PHONY: clean
clean: nomac ## Remove generated files
	$(RM) -r $(VENV)
	$(RM) -r __pycache__
	$(RM) -r $(name).egg-info
	$(RM) -r $(cmddir) $(defdir)
	$(RM) -r $(pyiworkdir) $(pyidistdir)
	$(RM) $(prog)
	$(RM) engine.$(PY)
	$(RM) $(name).spec
	@echo "$(OK_STRING) $@"

.PHONY: nomac
nomac: ## Remove unneeded mac files
	$(RM) .DS_Store
	@echo "$(OK_STRING) $@"

# ABOUT COPY HELP
# =======================================
# do not change

.PHONY: about
about: ## About this Makefile
	@echo
	@echo 'This Makefile is used to generate files for $(name)'
	@echo
	@echo 'Run "make help" for how to run'
	@echo
	@echo 'See https://github.com/rdmarsh/$(name)'
	@echo

.PHONY: copying
copying: ## Copyright notice
	@echo
	@echo 'Copyright (C) 2021--2026 David Marsh'
	@echo 'rdmarsh@gmail.com'
	@echo
	@echo 'This program is free software: you can redistribute it and/or modify'
	@echo 'it under the terms of the GNU General Public License as published by'
	@echo 'the Free Software Foundation, either version 3 of the License, or'
	@echo '(at your option) any later version.'
	@echo
	@echo 'This program comes with ABSOLUTELY NO WARRANTY.'
	@echo 'This is free software, and you are welcome to redistribute it'
	@echo 'under certain conditions. View the file "LICENSE" for details.'
	@echo

.PHONY: help
help: ## Show this help
	@$(AWK) 'BEGIN {FS = ":.*##"; printf "\nUsage: make [flags] [option]\n"} /^[$$()% \.0-9a-zA-Z_-]+:.*?##/ { printf "  \033[36mmake %-12s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
	@echo
	@echo 'Useful make flags:'
	@echo '  make -n   : dry run'
	@echo '  make -j   : run simultaneous jobs'
	@echo '  make -B   : force make target'
	@echo
	@echo 'You can override Makefile vars like so:'
	@echo '  make apiversion=2'
	@echo