[openwrt/openwrt] build: add comments to makefiles
LEDE Commits
lede-commits at lists.infradead.org
Tue Nov 12 08:56:13 PST 2024
ansuel pushed a commit to openwrt/openwrt.git, branch main:
https://git.openwrt.org/a72c8c770584075782959f2aa5c1487d68517edd
commit a72c8c770584075782959f2aa5c1487d68517edd
Author: Sergey Matsievskiy <matsievskiysv at gmail.com>
AuthorDate: Fri Nov 8 14:43:52 2024 +0300
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 <matsievskiysv at gmail.com>
Link: https://github.com/openwrt/openwrt/pull/16888
Signed-off-by: Christian Marangi <ansuelsmth at gmail.com>
---
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))
More information about the lede-commits
mailing list