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@gmail.com> Link: https://github.com/openwrt/openwrt/pull/16888 Signed-off-by: Christian Marangi <ansuelsmth@gmail.com>
This commit is contained in:
Sergey Matsievskiy
Christian Marangi
parent
dbe01f7d99
commit
a72c8c7705
|
|
@ -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 :=
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
97
rules.mk
97
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))
|
||||
|
|
|
|||
Loading…
Reference in New Issue