From a72c8c770584075782959f2aa5c1487d68517edd Mon Sep 17 00:00:00 2001 From: Sergey Matsievskiy Date: Fri, 8 Nov 2024 14:43:52 +0300 Subject: [PATCH] build: add comments to makefiles Add comments to build system makefile functions and variables to help developers in understanding build system internals and ease the development process. This patch adds some documentation examples with proposed doxygen-like syntax. Hopefully, this would start the discussion and result in generation of the makefile documentation guidelines. Signed-off-by: Sergey Matsievskiy Link: https://github.com/openwrt/openwrt/pull/16888 Signed-off-by: Christian Marangi --- include/image.mk | 56 +++++++++++++++++++++++++++ include/target.mk | 34 ++++++++++++++--- rules.mk | 97 ++++++++++++++++++++++++++++++++++++++++------- 3 files changed, 169 insertions(+), 18 deletions(-) diff --git a/include/image.mk b/include/image.mk index a4ac1b49cf..9a4dff2167 100644 --- a/include/image.mk +++ b/include/image.mk @@ -21,6 +21,11 @@ include $(INCLUDE_DIR)/rootfs.mk override MAKE:=$(_SINGLE)$(SUBMAKE) override NO_TRACE_MAKE:=$(_SINGLE)$(NO_TRACE_MAKE) +##@ +# @brief Convert size with unit postfix to unitless expression in bytes. +# +# @param 1: Size with unit. Possible unit postfix are `g`, `m`, `k`. +## exp_units = $(subst k, * 1024,$(subst m, * 1024k,$(subst g, * 1024m,$(1)))) target_params = $(subst +,$(space),$*) @@ -111,6 +116,12 @@ endef PROFILE_SANITIZED := $(call tolower,$(subst DEVICE_,,$(subst $(space),-,$(PROFILE)))) +##@ +# @brief Call function for each group of arguments. +# +# @param 1: List of lists of arguments. Lists are separated by `|`. +# @param 2: Function to call for list of arguments. +## define split_args $(foreach data, \ $(subst |,$(space),\ @@ -118,12 +129,24 @@ $(foreach data, \ $(call $(2),$(strip $(subst ^,$(space),$(data))))) endef +##@ +# @brief Call build function with arguments. +# +# @param 1: Function to call. Function name is prepended with `Build/`. +# @param 2...: Function arguments. +## define build_cmd $(if $(Build/$(word 1,$(1))),,$(error Missing Build/$(word 1,$(1)))) $(call Build/$(word 1,$(1)),$(wordlist 2,$(words $(1)),$(1))) endef +##@ +# @brief Call build functions from the list. +# +# @param 1: List of build functions with arguments, separated by `|`. +# First word in each group is a build command without `Build/` prefix. +## define concat_cmd $(call split_args,$(1),build_cmd) endef @@ -163,6 +186,12 @@ DTC_WARN_FLAGS := \ DTC_FLAGS += $(DTC_WARN_FLAGS) DTCO_FLAGS += $(DTC_WARN_FLAGS) +##@ +# @brief Pad file to specified size. +# +# @param 1: File. +# @param 2: Padding. +## define Image/pad-to dd if=$(1) of=$(1).new bs=$(2) conv=sync mv $(1).new $(1) @@ -403,26 +432,53 @@ define Device/InitProfile DEVICE_DESCRIPTION = Build firmware images for $$(DEVICE_TITLE) endef +##@ +# @brief Image configuration variables. +# +# @param 1: Device name. +## define Device/Init + ##@ Device name. DEVICE_NAME := $(1) + ##@ Commands to build kernel. + # Commands with arguments are separated by `|`. + ## KERNEL:= + ##@ Commands to build initramfs. + # Commands with arguments are separated by `|`. + ## KERNEL_INITRAMFS = $$(KERNEL) + ##@ Kernel command line. CMDLINE:= + ##@ Images to build. IMAGES := + ##@ Artifacts to build. ARTIFACTS := + ##@ Device image prefix. DEVICE_IMG_PREFIX := $(IMG_PREFIX)-$(1) + ##@ Device image name. DEVICE_IMG_NAME = $$(DEVICE_IMG_PREFIX)-$$(1)-$$(2) + ##@ Factory image name. FACTORY_IMG_NAME := + ##@ Maximum image size. Optional. IMAGE_SIZE := + ##@ Maximum image size. Optional. NAND_SIZE := + ##@ Kernel image prefix. KERNEL_PREFIX = $$(DEVICE_IMG_PREFIX) + ##@ Kernel image suffix. KERNEL_SUFFIX := -kernel.bin + ##@ Initramfs image suffix. KERNEL_INITRAMFS_SUFFIX = $$(KERNEL_SUFFIX) + ##@ Kernel image name. KERNEL_IMAGE = $$(KERNEL_PREFIX)$$(KERNEL_SUFFIX) + ##@ Initramfs image prefix. KERNEL_INITRAMFS_PREFIX = $$(DEVICE_IMG_PREFIX)-initramfs KERNEL_INITRAMFS_IMAGE = $$(KERNEL_INITRAMFS_PREFIX)$$(KERNEL_INITRAMFS_SUFFIX) + ##@ Initramfs image name. KERNEL_INITRAMFS_NAME = $$(KERNEL_NAME)-initramfs + ##@ Kernel install flag. KERNEL_INSTALL := KERNEL_NAME := vmlinux KERNEL_DEPENDS := diff --git a/include/target.mk b/include/target.mk index 3dc0acff5c..02ea68b15c 100644 --- a/include/target.mk +++ b/include/target.mk @@ -7,10 +7,17 @@ ifneq ($(__target_inc),1) __target_inc=1 -# default device type +##@ +# @brief Default device type ( basic | nas | router ). +## DEVICE_TYPE?=router -# Default packages - the really basic set +##@ +# @brief Default packages. +# +# The really basic set. Additional packages are added based on @DEVICE_TYPE and +# @CONFIG_* values. +## DEFAULT_PACKAGES:=\ base-files \ ca-bundle \ @@ -27,15 +34,21 @@ DEFAULT_PACKAGES:=\ urandom-seed \ urngd -# For the basic set +##@ +# @brief Default packages for @DEVICE_TYPE basic. +## DEFAULT_PACKAGES.basic:= -# For nas targets +##@ +# @brief Default packages for @DEVICE_TYPE nas. +## DEFAULT_PACKAGES.nas:=\ block-mount \ fdisk \ lsblk \ mdadm -# For router targets +##@ +# @brief Default packages for @DEVICE_TYPE router. +## DEFAULT_PACKAGES.router:=\ dnsmasq \ firewall4 \ @@ -85,7 +98,18 @@ endif # Add device specific packages (here below to allow device type set from subtarget) DEFAULT_PACKAGES += $(DEFAULT_PACKAGES.$(DEVICE_TYPE)) +##@ +# @brief Filter out packages, prepended with `-`. +# +# @param 1: Package list. +## filter_packages = $(filter-out -% $(patsubst -%,%,$(filter -%,$(1))),$(1)) + +##@ +# @brief Append extra package dependencies. +# +# @param 1: Package list. +## extra_packages = $(if $(filter wpad wpad-% nas,$(1)),iwinfo) define ProfileDefault diff --git a/rules.mk b/rules.mk index 973fd1cbb9..54df407fca 100644 --- a/rules.mk +++ b/rules.mk @@ -20,6 +20,11 @@ endif export TMP_DIR:=$(TOPDIR)/tmp export TMPDIR:=$(TMP_DIR) +##@ +# @brief Strip quotes `"` and pounds `#` from string. +# +# @param 1: String. +## qstrip=$(strip $(subst ",,$(1))) #")) @@ -27,8 +32,23 @@ empty:= space:= $(empty) $(empty) comma:=, pound:=\# +##@ +# @brief Merge strings by removing spaces. +# +# @param 1: String. +## merge=$(subst $(space),,$(1)) +##@ +# @brief Get hash sum of variable list. +# +# @param 1: List of variable names. +## confvar=$(shell echo '$(foreach v,$(1),$(v)=$(subst ','\'',$($(v))))' | $(MKHASH) md5) +##@ +# @brief Strip last extension from file name. +# +# @param 1: File name. +## strip_last=$(patsubst %.$(lastword $(subst .,$(space),$(1))),%,$(1)) paren_left = ( @@ -51,9 +71,18 @@ __tr_head = $(subst $(paren_left)subst,$(paren_left)subst$(space),$(__tr_head_st __tr_tail = $(subst $(space),,$(foreach cv,$(1),$(paren_right))) __tr_template = $(__tr_head)$$(1)$(__tr_tail) +##@ +# @brief Convert string characters to upper. +## $(eval toupper = $(call __tr_template,$(chars_lower),$(chars_upper))) +##@ +# @brief Convert string characters to lower. +## $(eval tolower = $(call __tr_template,$(chars_upper),$(chars_lower))) +##@ +# @brief Abbreviate version. Truncate to 8 characters. +## version_abbrev = $(if $(if $(CHECK),,$(DUMP)),$(1),$(shell printf '%.8s' $(1))) _SINGLE=export MAKEFLAGS=$(space); @@ -102,6 +131,13 @@ endif DEFAULT_SUBDIR_TARGETS:=clean download prepare compile update refresh prereq dist distcheck configure check check-depends +##@ +# @brief Create default targets. +# +# Targets are created from @DEFAULT_SUBDIR_TARGETS and input argument lists. +# +# @param 1: Additional targets list. +## define DefaultTargets $(foreach t,$(DEFAULT_SUBDIR_TARGETS) $(1), .$(t): @@ -371,16 +407,28 @@ export BISON_PKGDATADIR:=$(STAGING_DIR_HOST)/share/bison export HOST_GNULIB_SRCDIR:=$(STAGING_DIR_HOST)/share/gnulib export M4:=$(STAGING_DIR_HOST)/bin/m4 +##@ +# @brief Slugify variable name and prepend suffix. +## define shvar V_$(subst .,_,$(subst -,_,$(subst /,_,$(1)))) endef +##@ +# @brief Create and export variable, set to function result. +# +# @param 1: Function name. Used as variable name, prepended with `V_`. +## define shexport export $(call shvar,$(1))=$$(call $(1)) endef +##@ +# @brief Support 64 bit tine in C code. +# # Test support for 64-bit time with C code from largefile.m4 provided by GNU Gnulib -# the value is 'y' when successful and '' otherwise +# the value is `y` when successful and `` otherwise +## define YEAR_2038 $(shell \ mkdir -p $(TMP_DIR); \ @@ -392,9 +440,12 @@ $(shell \ ) endef -# Execute commands under flock -# $(1) => The shell expression. -# $(2) => The lock name. If not given, the global lock will be used. +##@ +# @brief Execute commands under flock +# +# @param 1: The shell expression. +# @param 2: The lock name. If not given, the global lock will be used. +## ifneq ($(wildcard $(STAGING_DIR_HOST)/bin/flock),) define locked SHELL= \ @@ -406,10 +457,14 @@ else locked=$(1) endif -# Recursively copy paths into another directory, purge dangling + +##@ +# @brief Recursively copy paths into another directory, purge dangling # symlinks before. -# $(1) => File glob expression -# $(2) => Destination directory +# +# @param 1: File glob expression. +# @param 1: Destination directory. +## define file_copy for src_dir in $(sort $(foreach d,$(wildcard $(1)),$(dir $(d)))); do \ ( cd $$src_dir; find -type f -or -type d ) | \ @@ -424,19 +479,30 @@ define file_copy $(CP) $(1) $(2) endef -# Calculate sha256sum of any plain file within a given directory -# $(1) => Input directory -# $(2) => If set, recurse into subdirectories +##@ +# @brief Calculate sha256sum of any plain file within a given directory. +# +# @param 1: Input directory. +# @param 2: If set, recurse into subdirectories. +## define sha256sums (cd $(1); find . $(if $(2),,-maxdepth 1) -type f -not -name 'sha256sums' -printf "%P\n" | sort | \ xargs -r $(MKHASH) -n sha256 | sed -ne 's!^\(.*\) \(.*\)$$!\1 *\2!p' > sha256sums) endef -# file extension +##@ +# @brief Retrieve file extension. +# +# @param 1: File name. +## ext=$(word $(words $(subst ., ,$(1))),$(subst ., ,$(1))) -# Count Git commits of a package -# $(1) => if non-empty: count commits since last ": [uU]pdate to " or ": [bB]ump to " in commit message +##@ +# @brief Count Git commits of a package. +# +# @param 1: if non-empty: count commits since last ": [uU]pdate to " +# or ": [bB]ump to " in commit message. +## define commitcount $(shell \ if git log -1 >/dev/null 2>/dev/null; then \ @@ -458,6 +524,11 @@ $(shell \ ) endef +##@ +# @brief Get ABI version string, stripping `-`, `_` and `.`. +# +# @param 1: Version string. +## abi_version_str = $(subst -,,$(subst _,,$(subst .,,$(1)))) COMMITCOUNT = $(if $(DUMP),0,$(call commitcount))