Ops: Added structure and help generator to makefile (closes #26) (#27)

* Added structure and help generator to makefile (closes #26) * Fixed make and spelling issues from linting * Removed minphony requirement from checkmake * [MegaLinter] Apply linters fixes --------- Co-authored-by: andrewvaughan <[email protected]>
andrewvaughan · Oct 20, 2023 · acef038 · acef038
1 parent cdb1c38
commit acef038
Show file tree

Hide file tree

Showing 12 changed files with 551 additions and 14 deletions.
diff --git a/.config/dictionaries/ops.txt b/.config/dictionaries/ops.txt
@@ -1,4 +1,22 @@
+addsuffix
+CHECKMAKE
 devcontainer
+endef
+findstring
+ifeq
+ifneq
+MAKEFLAGS
 megalinter
+ONESHELL
 oxsecurity
+pipefail
+ritm
+rmul
+setab
+setaf
+SHELLFLAGS
+sitm
+smul
 stefanzweifel
+tput
+Txterm
diff --git a/.config/linters/.checkmake.ini b/.config/linters/.checkmake.ini
@@ -0,0 +1,6 @@
+# This configures checkmake to not implement a mandatory `PHONY` target set
+#
+# @link https://github.com/mrtazz/checkmake
+
+[minphony]
+disabled = true
diff --git a/.config/make/00-config.mak b/.config/make/00-config.mak
@@ -0,0 +1,58 @@
+##
+# Make Configurations
+#
+# This file is used to configure how this make configuration runs and should always be the first file written. No other
+# configurations should share the `00` prefix or be loaded, alphabetically, prior to this file.
+#
+
+
+## ---------------------------------------------------------------------------------------------------------------------
+# GNU Make Configurations
+#
+# @link https://www.gnu.org/software/make/manual/html_node/Special-Variables.html
+# @link https://www.gnu.org/software/make/manual/html_node/Special-Targets.html
+#
+
+
+# The default target to load when no target is provided, regardless of load order.
+.DEFAULT_GOAL := all
+
+# Use Bash as the shell
+SHELL := /bin/bash
+.SHELLFLAGS = -eu -o pipefail -c
+
+# Do not output the recipe prior to execution
+.SILENT:
+
+# Run all commands in the same shell
+# @link https://www.gnu.org/software/make/manual/html_node/One-Shell.html
+.ONESHELL:
+
+# Export all variables to child processes
+.EXPORT_ALL_VARIABLES:
+
+
+
+## ---------------------------------------------------------------------------------------------------------------------
+# Project Makefile Configurations
+#
+
+
+# By default, the `DEBUG` flag will follow whether the `make` command was called with the `-d` or `--debug` s:
+#
+# `make -d`
+# `make --debug=basic`
+#
+# To enable this `DEBUG` flag without increasing `make` verbosity, set the flag manually:
+#
+# `make DEBUG=1`
+#
+ifneq (,$(findstring --debug=,-$(MAKEFLAGS)))
+DEBUG ?= 1
+endif
+
+ifneq (,$(findstring d,-$(filter-out --%,-$(MAKEFLAGS))))
+DEBUG ?= 1
+endif
+
+DEBUG ?= 0
diff --git a/.config/make/10-ui.mak b/.config/make/10-ui.mak
@@ -0,0 +1,248 @@
+##
+# Make UI Configurations
+#
+# Shared variables for terminal colors and styling are managed in this configuration file. "Templates" for other files
+# can be implemented by changing the settings, here.
+#
+
+
+# This is a special variable $(,) to allow for commas to be used when calling helper methods. Raw commas are always seen
+# as argument separators, regardless of whether they are in quotes or not, so this variable should be used whenever a
+# comma is intended to be sent to a function within the argument as opposed to being used as an argument separator.
+#
+# @see _title
+,=,
+
+
+
+## ---------------------------------------------------------------------------------------------------------------------
+# Terminal Constants
+#
+# @link https://www.mankier.com/5/terminfo#Description-Predefined_Capabilities
+# @link https://man7.org/linux/man-pages/man4/console_codes.4.html
+#
+
+ifeq ($(UNAME_S),Darwin)
+_ESC := \x1B
+endif
+
+_ESC ?= \e
+
+_BOLD         := $(shell tput bold)
+_DIM          := $(shell tput dim)
+_ITALIC       := $(shell tput sitm)
+_UNDERLINE    := $(shell tput smul)
+_INVERT       := $(shell tput rev)
+
+_NO_BOLD      := $(_ESC)[21
+_NO_DIM       := $(_ESC)[22
+_NO_ITALIC    := $(shell tput ritm)
+_NO_UNDERLINE := $(shell tput rmul)
+_NO_INVERT    := $(_ESC)[27
+
+# Foreground colors
+_FG_BLACK     := $(shell tput setaf 0)
+_FG_RED       := $(shell tput setaf 9 || tput setaf 1)
+_FG_GREEN     := $(shell tput setaf 10 || tput setaf 2)
+_FG_YELLOW    := $(shell tput setaf 11 || tput setaf 3)
+_FG_BLUE      := $(shell tput setaf 12 || tput setaf 4)
+_FG_MAGENTA   := $(shell tput setaf 13 || tput setaf 5)
+_FG_CYAN      := $(shell tput setaf 14 || tput setaf 6)
+_FG_WHITE     := $(shell tput setaf 15 || tput setaf 7)
+
+# Background colors
+_BG_BLACK     := $(shell tput setab 0)
+_BG_RED       := $(shell tput setab 9 || tput setab 1)
+_BG_GREEN     := $(shell tput setab 10 || tput setab 2)
+_BG_YELLOW    := $(shell tput setab 11 || tput setab 3)
+_BG_BLUE      := $(shell tput setab 12 || tput setab 4)
+_BG_MAGENTA   := $(shell tput setab 13 || tput setab 5)
+_BG_CYAN      := $(shell tput setab 14 || tput setab 6)
+_BG_WHITE     := $(shell tput setab 15 || tput setab 7)
+
+_RESET        := $(shell tput -Txterm sgr0 || echo "$(_ESC)[0m")
+
+# Terminal size
+TERM_ROWS = $(shell tput lines || echo 0)
+TERM_COLS = $(shell tput cols || echo 80)
+
+
+
+## ---------------------------------------------------------------------------------------------------------------------
+# Usage Template Targets
+#
+# To use these in a Makefile, simply call the target, such as:
+#
+# ```
+# $(call title, My Title)
+# ```
+#
+
+
+##
+# Print a fixed-width title. Titles over the fixed-width will be word wrapped.
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _title, My title$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _title
+	MAK_FIX_WIDTH=$(strip $(2)) \
+		&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+		&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+		&& export IFS=$$'\n' \
+		&& echo \
+		&& for line in $${MAK_WRAPPED}; do \
+			printf "$(_BOLD)$(_FG_BLACK)$(_BG_CYAN)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "$${line}"; \
+		done
+endef
+
+
+##
+# Print a fixed-width header. Headers over the fixed-width will be word wrapped.
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _header, My header$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _header
+	MAK_FIX_WIDTH=$(strip $(2)) \
+		&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+		&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+		&& export IFS=$$'\n' \
+		&& echo \
+		&& for line in $${MAK_WRAPPED}; do \
+			printf "$(_UNDERLINE)$(_FG_BLUE)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "$${line}"; \
+		done
+endef
+
+
+##
+# Print a debug statement. Statements over the fixed-width will be word wrapped. Messages will only appear if `DEBUG` is
+# set to `1` or greater. This is done automatically with any of the Make debug flags, unless modified, or debug mode can
+# be enabled with:
+#
+# ```
+# make DEBUG=1 ...
+# ```
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _debug, My debug$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _debug
+	[[ $(DEBUG) -gt 0 ]] && ( \
+		MAK_FIX_WIDTH=$(strip $(2)) \
+			&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+			&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+			&& export IFS=$$'\n' \
+			&& for line in $${MAK_WRAPPED}; do \
+				printf "$(_DIM)$(_FG_YELLOW)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "[MAKE DEBUG] $${line}"; \
+			done \
+	) || true
+endef
+
+
+##
+# Writes an informational message to the screen with no formatting, other than word-wrapping. Statements over the fixed-
+# width will be word wrapped.
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _info, My info$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _info
+	MAK_FIX_WIDTH=$(strip $(2)) \
+		&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+		&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+		&& export IFS=$$'\n' \
+		&& for line in $${MAK_WRAPPED}; do \
+			printf "%s\n" "$${line}"; \
+		done \
+		&& echo
+endef
+
+
+##
+# Writes a warning message to the screen. Statements over the fixed-width will be word wrapped.
+#
+# This command does _not_ call the Make `warning` function, as this effectively duplicates (and improves) all
+# functionality that function would execute.
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _warning, My warning$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _warning
+	MAK_FIX_WIDTH=$(strip $(2)) \
+		&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+		&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+		&& export IFS=$$'\n' \
+		&& echo \
+		&& printf "$(BOLD)$(_FG_BLACK)$(_BG_YELLOW)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "WARNING:" \
+		&& for line in $${MAK_WRAPPED}; do \
+			printf "$(BOLD)$(_FG_YELLOW)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "$${line}"; \
+		done \
+		&& echo
+endef
+
+
+##
+# Writes an error message to the screen. Statements over the fixed-width will be word wrapped.
+#
+# This command _does_ call the Make `error` function and halt any further progress.
+#
+# Please note, due to a limitation in Make, commas can not be passed to this function. A helper variable of $(,) is
+# provided to insert a comma, if necessary:
+#
+# ```
+# $(call _error, My error$(,) and the comma$(,) as expected)
+# ```
+#
+# @param {string} (1) - the message to print
+# @param {string} (2) - (optional) the fixed width of the text (default: terminal width)
+#
+define _error
+	MAK_FIX_WIDTH=$(strip $(2)) \
+		&& MAK_FIX_WIDTH=$${MAK_FIX_WIDTH:-$(TERM_COLS)} \
+		&& MAK_WRAPPED=$$(echo "$(strip $(1)") | fmt -w $${MAK_FIX_WIDTH}) \
+		&& export IFS=$$'\n' \
+		&& echo \
+		&& printf "$(BOLD)$(_FG_BLACK)$(_BG_RED)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "FATAL ERROR:" \
+		&& for line in $${MAK_WRAPPED}; do \
+			printf "$(BOLD)$(_FG_RED)%-$${MAK_FIX_WIDTH}s$(_RESET)\n" "$${line}"; \
+		done \
+		&& echo
+
+	$(error, $(1))
+endef
diff --git a/.config/make/20-usage.mak b/.config/make/20-usage.mak
@@ -0,0 +1,54 @@
+##
+# Usage
+#
+# This file contains help information on how to use this Makefile.
+#
+
+.PHONY: help
+
+
+##
+# Print the usage instructions for this Makefile.
+#
+# This will automatically pull the first line after the double-hash (##) comment for any target to print as the
+# help. This means any new targets will have their usage instructions auto-generated here, so long as the comment
+# formatting remains correct.
+#
+# Private targets should start with an underscore (`_`) to prevent having their information listed here.
+#
+help:
+	$(call _title, Makefile Help, 80)
+
+	printf "\nUsage: $(_FG_CYAN)make $(_FG_GREEN)$(_ITALIC)<target>$(_RESET)\n\n"
+
+	$(call _info, \
+		This Makefile provides various utility methods for this project in an effort to make development more \
+		consistent and developer-friendly. Please refer to the living project documentation for more details:, 80 \
+	)
+
+	printf "    $(_UNDERLINE)$(_FG_BLUE)https://github.com/andrewvaughan/template-core$(_RESET)\n\n"
+
+	$(call _info, The following targets are available$(,) which can be called via:, 80)
+
+	for file in $(MAKEFILE_LIST); do \
+		cat $$file \
+			| awk ' \
+				BEGIN { c = "" }; \
+				/^##/ { \
+					c = ""; \
+				}; \
+				/^# .+/ { \
+					if (length(c) == 0) { \
+						for (i = 2; i <= NF; i++) \
+							c = c $$i " "; \
+					} \
+				}; \
+				/^[a-zA-Z0-9][a-zA-Z0-9_-]+:/ { \
+					split($$0, spl, ":"); \
+					printf "    $(_FG_GREEN)$(_ITALIC)%-15s$(_RESET) %s\n", spl[1], c; \
+				}' \
+			$$file \
+		; \
+	done
+
+	echo