[linux-block.git] / scripts / Kbuild.include

# SPDX-License-Identifier: GPL-2.0
####
# kbuild: Generic definitions

# Convenient variables
comma   := ,
quote   := "
squote  := '
empty   :=
space   := $(empty) $(empty)
space_escape := _-_SPACE_-_
pound := \#
define newline


endef

###
# Comparison macros.
# Usage: $(call test-lt, $(CONFIG_LLD_VERSION), 150000)
#
# Use $(intcmp ...) if supported. (Make >= 4.4)
# Otherwise, fall back to the 'test' shell command.
ifeq ($(intcmp 1,0,,,y),y)
test-ge = $(intcmp $(strip $1)0, $(strip $2)0,,y,y)
test-gt = $(intcmp $(strip $1)0, $(strip $2)0,,,y)
else
test-ge = $(shell test $(strip $1)0 -ge $(strip $2)0 && echo y)
test-gt = $(shell test $(strip $1)0 -gt $(strip $2)0 && echo y)
endif
test-le = $(call test-ge, $2, $1)
test-lt = $(call test-gt, $2, $1)

###
# Name of target with a '.' as filename prefix. foo/bar.o => foo/.bar.o
dot-target = $(dir $@).$(notdir $@)

###
# Name of target with a '.tmp_' as filename prefix. foo/bar.o => foo/.tmp_bar.o
tmp-target = $(dir $@).tmp_$(notdir $@)

###
# The temporary file to save gcc -MMD generated dependencies must not
# contain a comma
depfile = $(subst $(comma),_,$(dot-target).d)

###
# filename of target with directory and extension stripped
basetarget = $(basename $(notdir $@))

###
# real prerequisites without phony targets
real-prereqs = $(filter-out $(PHONY), $^)

###
# Escape single quote for use in echo statements
escsq = $(subst $(squote),'\$(squote)',$1)

###
# Quote a string to pass it to C files. foo => '"foo"'
stringify = $(squote)$(quote)$1$(quote)$(squote)

###
# The path to Kbuild or Makefile. Kbuild has precedence over Makefile.
kbuild-file = $(or $(wildcard $(src)/Kbuild),$(src)/Makefile)

###
# Read a file, replacing newlines with spaces
#
# Make 4.2 or later can read a file by using its builtin function.
ifneq ($(filter-out 3.% 4.0 4.1, $(MAKE_VERSION)),)
read-file = $(subst $(newline),$(space),$(file < $1))
else
read-file = $(shell cat $1 2>/dev/null)
endif

###
# Easy method for doing a status message
       kecho := :
 quiet_kecho := echo
silent_kecho := :
kecho := $($(quiet)kecho)

###
# filechk is used to check if the content of a generated file is updated.
# Sample usage:
#
# filechk_sample = echo $(KERNELRELEASE)
# version.h: FORCE
#	$(call filechk,sample)
#
# The rule defined shall write to stdout the content of the new file.
# The existing file will be compared with the new one.
# - If no file exist it is created
# - If the content differ the new file is used
# - If they are equal no change, and no timestamp update
define filechk
	$(check-FORCE)
	$(Q)set -e;						\
	mkdir -p $(dir $@);					\
	trap "rm -f $(tmp-target)" EXIT;			\
	{ $(filechk_$(1)); } > $(tmp-target);			\
	if [ ! -r $@ ] || ! cmp -s $@ $(tmp-target); then	\
		$(kecho) '  UPD     $@';			\
		mv -f $(tmp-target) $@;				\
	fi
endef

###
# Shorthand for $(Q)$(MAKE) -f scripts/Makefile.build obj=
# Usage:
# $(Q)$(MAKE) $(build)=dir
build := -f $(srctree)/scripts/Makefile.build obj

###
# Shorthand for $(Q)$(MAKE) -f scripts/Makefile.clean obj=
# Usage:
# $(Q)$(MAKE) $(clean)=dir
clean := -f $(srctree)/scripts/Makefile.clean obj

# pring log
#
# If quiet is "silent_", print nothing and sink stdout
# If quiet is "quiet_", print short log
# If quiet is empty, print short log and whole command
silent_log_print = exec >/dev/null;
 quiet_log_print = $(if $(quiet_cmd_$1), echo '  $(call escsq,$(quiet_cmd_$1)$(why))';)
       log_print = echo '$(pound) $(call escsq,$(or $(quiet_cmd_$1),cmd_$1 $@)$(why))'; \
                   echo '  $(call escsq,$(cmd_$1))';

# Delete the target on interruption
#
# GNU Make automatically deletes the target if it has already been changed by
# the interrupted recipe. So, you can safely stop the build by Ctrl-C (Make
# will delete incomplete targets), and resume it later.
#
# However, this does not work when the stderr is piped to another program, like
#  $ make >&2 | tee log
# Make dies with SIGPIPE before cleaning the targets.
#
# To address it, we clean the target in signal traps.
#
# Make deletes the target when it catches SIGHUP, SIGINT, SIGQUIT, SIGTERM.
# So, we cover them, and also SIGPIPE just in case.
#
# Of course, this is unneeded for phony targets.
delete-on-interrupt = \
	$(if $(filter-out $(PHONY), $@), \
		$(foreach sig, HUP INT QUIT TERM PIPE, \
			trap 'rm -f $@; trap - $(sig); kill -s $(sig) $$$$' $(sig);))

# print and execute commands
cmd = @$(if $(cmd_$(1)),set -e; $($(quiet)log_print) $(delete-on-interrupt) $(cmd_$(1)),:)

###
# if_changed      - execute command if any prerequisite is newer than
#                   target, or command line has changed
# if_changed_dep  - as if_changed, but uses fixdep to reveal dependencies
#                   including used config symbols
# if_changed_rule - as if_changed but execute rule instead
# See Documentation/kbuild/makefiles.rst for more info

ifneq ($(KBUILD_NOCMDDEP),1)
# Check if both commands are the same including their order. Result is empty
# string if equal. User may override this check using make KBUILD_NOCMDDEP=1
# If the target does not exist, the *.cmd file should not be included so
# $(savedcmd_$@) gets empty. Then, target will be built even if $(newer-prereqs)
# happens to become empty.
cmd-check = $(filter-out $(subst $(space),$(space_escape),$(strip $(savedcmd_$@))), \
                         $(subst $(space),$(space_escape),$(strip $(cmd_$1))))
else
# We still need to detect missing targets.
cmd-check = $(if $(strip $(savedcmd_$@)),,1)
endif

# Replace >$< with >$$< to preserve $ when reloading the .cmd file
# (needed for make)
# Replace >#< with >$(pound)< to avoid starting a comment in the .cmd file
# (needed for make)
# Replace >'< with >'\''< to be able to enclose the whole string in '...'
# (needed for the shell)
make-cmd = $(call escsq,$(subst $(pound),$$(pound),$(subst $$,$$$$,$(cmd_$(1)))))

# Find any prerequisites that are newer than target or that do not exist.
# PHONY targets skipped in both cases.
# If there is no prerequisite other than phony targets, $(newer-prereqs) becomes
# empty even if the target does not exist. cmd-check saves this corner case.
newer-prereqs = $(filter-out $(PHONY),$?)

# It is a typical mistake to forget the FORCE prerequisite. Check it here so
# no more breakage will slip in.
check-FORCE = $(if $(filter FORCE, $^),,$(warning FORCE prerequisite is missing))

if-changed-cond = $(newer-prereqs)$(cmd-check)$(check-FORCE)

# Execute command if command has changed or prerequisite(s) are updated.
if_changed = $(if $(if-changed-cond),$(cmd_and_savecmd),@:)

cmd_and_savecmd =                                                            \
	$(cmd);                                                              \
	printf '%s\n' 'savedcmd_$@ := $(make-cmd)' > $(dot-target).cmd

# Execute the command and also postprocess generated .d dependencies file.
if_changed_dep = $(if $(if-changed-cond),$(cmd_and_fixdep),@:)

cmd_and_fixdep =                                                             \
	$(cmd);                                                              \
	scripts/basic/fixdep $(depfile) $@ '$(make-cmd)' > $(dot-target).cmd;\
	rm -f $(depfile)

# Usage: $(call if_changed_rule,foo)
# Will check if $(cmd_foo) or any of the prerequisites changed,
# and if so will execute $(rule_foo).
if_changed_rule = $(if $(if-changed-cond),$(rule_$(1)),@:)

###
# why - tell why a target got built
#       enabled by make V=2
#       Output (listed in the order they are checked):
#          (1) - due to target is PHONY
#          (2) - due to target missing
#          (3) - due to: file1.h file2.h
#          (4) - due to command line change
#          (5) - due to missing .cmd file
#          (6) - due to target not in $(targets)
# (1) PHONY targets are always build
# (2) No target, so we better build it
# (3) Prerequisite is newer than target
# (4) The command line stored in the file named dir/.target.cmd
#     differed from actual command line. This happens when compiler
#     options changes
# (5) No dir/.target.cmd file (used to store command line)
# (6) No dir/.target.cmd file and target not listed in $(targets)
#     This is a good hint that there is a bug in the kbuild file
ifneq ($(findstring 2, $(KBUILD_VERBOSE)),)
_why =                                                                        \
    $(if $(filter $@, $(PHONY)),- due to target is PHONY,                    \
        $(if $(wildcard $@),                                                 \
            $(if $(newer-prereqs),- due to: $(newer-prereqs),                \
                $(if $(cmd-check),                                           \
                    $(if $(savedcmd_$@),- due to command line change,        \
                        $(if $(filter $@, $(targets)),                       \
                            - due to missing .cmd file,                      \
                            - due to $(notdir $@) not in $$(targets)         \
                         )                                                   \
                     )                                                       \
                 )                                                           \
             ),                                                              \
             - due to target missing                                         \
         )                                                                   \
     )

why = $(space)$(strip $(_why))
endif

###############################################################################

# delete partially updated (i.e. corrupted) files on error
.DELETE_ON_ERROR:

# do not delete intermediate files automatically
#
# .NOTINTERMEDIATE is more correct, but only available on newer Make versions.
# Make 4.4 introduced .NOTINTERMEDIATE, and it appears in .FEATURES, but the
# global .NOTINTERMEDIATE does not work. We can use it on Make > 4.4.
# Use .SECONDARY for older Make versions, but "newer-prereq" cannot detect
# deleted files.
ifneq ($(and $(filter notintermediate, $(.FEATURES)),$(filter-out 4.4,$(MAKE_VERSION))),)
.NOTINTERMEDIATE:
else
.SECONDARY:
endif
Commit	Line	Data
96ac6d43	1	# SPDX-License-Identifier: GPL-2.0
8ec4b4ff SR	2	####
	3	# kbuild: Generic definitions
	4
beda9f3a	5	# Convenient variables
8ec4b4ff	6	comma := ,
13338935	7	quote := "
d51bfb78	8	squote := '
8ec4b4ff SR	9	empty :=
8ec4b4ff SR	10	space := $(empty) $(empty)
9c8fa9bc	11	space_escape := _-_SPACE_-_
9564a8cf	12	pound := \#
6768fa4b MY	13	define newline
	14
	15
	16	endef
8ec4b4ff	17
fccb3d3e MY	18	###
	19	# Comparison macros.
	20	# Usage: $(call test-lt, $(CONFIG_LLD_VERSION), 150000)
	21	#
	22	# Use $(intcmp ...) if supported. (Make >= 4.4)
	23	# Otherwise, fall back to the 'test' shell command.
	24	ifeq ($(intcmp 1,0,,,y),y)
	25	test-ge = $(intcmp $(strip $1)0, $(strip $2)0,,y,y)
	26	test-gt = $(intcmp $(strip $1)0, $(strip $2)0,,,y)
	27	else
	28	test-ge = $(shell test $(strip $1)0 -ge $(strip $2)0 && echo y)
	29	test-gt = $(shell test $(strip $1)0 -gt $(strip $2)0 && echo y)
	30	endif
	31	test-le = $(call test-ge, $2, $1)
	32	test-lt = $(call test-gt, $2, $1)
	33
48f1f058 SR	34	###
	35	# Name of target with a '.' as filename prefix. foo/bar.o => foo/.bar.o
	36	dot-target = $(dir $@).$(notdir $@)
	37
c25e1c55 MY	38	###
	39	# Name of target with a '.tmp_' as filename prefix. foo/bar.o => foo/.tmp_bar.o
	40	tmp-target = $(dir $@).tmp_$(notdir $@)
	41
8ec4b4ff	42	###
30a77297	43	# The temporary file to save gcc -MMD generated dependencies must not
8ec4b4ff	44	# contain a comma
48f1f058	45	depfile = $(subst $(comma),_,$(dot-target).d)
8ec4b4ff	46
5e8d780d SR	47	###
	48	# filename of target with directory and extension stripped
	49	basetarget = $(basename $(notdir $@))
	50
afa974b7 MY	51	###
	52	# real prerequisites without phony targets
	53	real-prereqs = $(filter-out $(PHONY), $^)
	54
d51bfb78 SR	55	###
	56	# Escape single quote for use in echo statements
	57	escsq = $(subst $(squote),'\$(squote)',$1)
	58
7e826c44 MY	59	###
	60	# Quote a string to pass it to C files. foo => '"foo"'
	61	stringify = $(squote)$(quote)$1$(quote)$(squote)
	62
a2430b25 MY	63	###
a2430b25 MY	64	# The path to Kbuild or Makefile. Kbuild has precedence over Makefile.
b1992c37	65	kbuild-file = $(or $(wildcard $(src)/Kbuild),$(src)/Makefile)
a2430b25	66
6768fa4b MY	67	###
	68	# Read a file, replacing newlines with spaces
	69	#
	70	# Make 4.2 or later can read a file by using its builtin function.
	71	ifneq ($(filter-out 3.% 4.0 4.1, $(MAKE_VERSION)),)
	72	read-file = $(subst $(newline),$(space),$(file < $1))
	73	else
	74	read-file = $(shell cat $1 2>/dev/null)
	75	endif
	76
5410ecc0 MF	77	###
	78	# Easy method for doing a status message
	79	kecho := :
	80	quiet_kecho := echo
	81	silent_kecho := :
	82	kecho := $($(quiet)kecho)
	83
8ec4b4ff SR	84	###
	85	# filechk is used to check if the content of a generated file is updated.
	86	# Sample usage:
ba97df45 MY	87	#
	88	# filechk_sample = echo $(KERNELRELEASE)
	89	# version.h: FORCE
8ec4b4ff	90	# $(call filechk,sample)
ba97df45	91	#
8ec4b4ff SR	92	# The rule defined shall write to stdout the content of the new file.
	93	# The existing file will be compared with the new one.
	94	# - If no file exist it is created
	95	# - If the content differ the new file is used
	96	# - If they are equal no change, and no timestamp update
8ec4b4ff	97	define filechk
e1f86d7b	98	$(check-FORCE)
88fe89a4 MY	99	$(Q)set -e; \
88fe89a4 MY	100	mkdir -p $(dir $@); \
12fec3d6 MY	101	trap "rm -f $(tmp-target)" EXIT; \
	102	{ $(filechk_$(1)); } > $(tmp-target); \
	103	if [ ! -r $@ ] \|\| ! cmp -s $@ $(tmp-target); then \
88fe89a4	104	$(kecho) ' UPD $@'; \
12fec3d6	105	mv -f $(tmp-target) $@; \
8ec4b4ff SR	106	fi
	107	endef
	108
beda9f3a	109	###
8ec4b4ff SR	110	# Shorthand for $(Q)$(MAKE) -f scripts/Makefile.build obj=
	111	# Usage:
	112	# $(Q)$(MAKE) $(build)=dir
5b2389b4	113	build := -f $(srctree)/scripts/Makefile.build obj
8ec4b4ff	114
371fdc77 MY	115	###
	116	# Shorthand for $(Q)$(MAKE) -f scripts/Makefile.clean obj=
	117	# Usage:
	118	# $(Q)$(MAKE) $(clean)=dir
	119	clean := -f $(srctree)/scripts/Makefile.clean obj
	120
8962b6b4 MY	121	# pring log
	122	#
	123	# If quiet is "silent_", print nothing and sink stdout
	124	# If quiet is "quiet_", print short log
	125	# If quiet is empty, print short log and whole command
	126	silent_log_print = exec >/dev/null;
	127	quiet_log_print = $(if $(quiet_cmd_$1), echo ' $(call escsq,$(quiet_cmd_$1)$(why))';)
6ae4b986	128	log_print = echo '$(pound) $(call escsq,$(or $(quiet_cmd_$1),cmd_$1 $@)$(why))'; \
8962b6b4	129	echo ' $(call escsq,$(cmd_$1))';
174a1dcc	130
a7f3257d MY	131	# Delete the target on interruption
	132	#
	133	# GNU Make automatically deletes the target if it has already been changed by
	134	# the interrupted recipe. So, you can safely stop the build by Ctrl-C (Make
	135	# will delete incomplete targets), and resume it later.
	136	#
	137	# However, this does not work when the stderr is piped to another program, like
	138	# $ make >&2 \| tee log
	139	# Make dies with SIGPIPE before cleaning the targets.
	140	#
	141	# To address it, we clean the target in signal traps.
	142	#
	143	# Make deletes the target when it catches SIGHUP, SIGINT, SIGQUIT, SIGTERM.
	144	# So, we cover them, and also SIGPIPE just in case.
	145	#
	146	# Of course, this is unneeded for phony targets.
	147	delete-on-interrupt = \
	148	$(if $(filter-out $(PHONY), $@), \
	149	$(foreach sig, HUP INT QUIT TERM PIPE, \
	150	trap 'rm -f $@; trap - $(sig); kill -s $(sig) $$$$' $(sig);))
	151
8962b6b4 MY	152	# print and execute commands
8962b6b4 MY	153	cmd = @$(if $(cmd_$(1)),set -e; $($(quiet)log_print) $(delete-on-interrupt) $(cmd_$(1)),:)
8ec4b4ff SR	154
8ec4b4ff SR	155	###
5de043f4	156	# if_changed - execute command if any prerequisite is newer than
8ec4b4ff SR	157	# target, or command line has changed
	158	# if_changed_dep - as if_changed, but uses fixdep to reveal dependencies
	159	# including used config symbols
	160	# if_changed_rule - as if_changed but execute rule instead
cd238eff	161	# See Documentation/kbuild/makefiles.rst for more info
8ec4b4ff SR	162
8ec4b4ff SR	163	ifneq ($(KBUILD_NOCMDDEP),1)
50bcca6a	164	# Check if both commands are the same including their order. Result is empty
9c8fa9bc	165	# string if equal. User may override this check using make KBUILD_NOCMDDEP=1
ee2162bd MY	166	# If the target does not exist, the *.cmd file should not be included so
	167	# $(savedcmd_$@) gets empty. Then, target will be built even if $(newer-prereqs)
	168	# happens to become empty.
92215e7a	169	cmd-check = $(filter-out $(subst $(space),$(space_escape),$(strip $(savedcmd_$@))), \
9c8fa9bc	170	$(subst $(space),$(space_escape),$(strip $(cmd_$1))))
c4d5ee13	171	else
ee2162bd	172	# We still need to detect missing targets.
92215e7a	173	cmd-check = $(if $(strip $(savedcmd_$@)),,1)
8ec4b4ff SR	174	endif
8ec4b4ff SR	175
164f0d2e MM	176	# Replace >$< with >$$< to preserve $ when reloading the .cmd file
164f0d2e MM	177	# (needed for make)
9564a8cf	178	# Replace >#< with >$(pound)< to avoid starting a comment in the .cmd file
164f0d2e MM	179	# (needed for make)
	180	# Replace >'< with >'\''< to be able to enclose the whole string in '...'
	181	# (needed for the shell)
9564a8cf	182	make-cmd = $(call escsq,$(subst $(pound),$$(pound),$(subst $$,$$$$,$(cmd_$(1)))))
6176aa9a	183
2d3b1b8f	184	# Find any prerequisites that are newer than target or that do not exist.
48f1f058	185	# PHONY targets skipped in both cases.
ee2162bd MY	186	# If there is no prerequisite other than phony targets, $(newer-prereqs) becomes
ee2162bd MY	187	# empty even if the target does not exist. cmd-check saves this corner case.
eba19032	188	newer-prereqs = $(filter-out $(PHONY),$?)
48f1f058	189
e1f86d7b MY	190	# It is a typical mistake to forget the FORCE prerequisite. Check it here so
	191	# no more breakage will slip in.
	192	check-FORCE = $(if $(filter FORCE, $^),,$(warning FORCE prerequisite is missing))
	193
	194	if-changed-cond = $(newer-prereqs)$(cmd-check)$(check-FORCE)
6796e804	195
5de043f4	196	# Execute command if command has changed or prerequisite(s) are updated.
ebd191b3 MY	197	if_changed = $(if $(if-changed-cond),$(cmd_and_savecmd),@:)
	198
	199	cmd_and_savecmd = \
67126965	200	$(cmd); \
92215e7a	201	printf '%s\n' 'savedcmd_$@ := $(make-cmd)' > $(dot-target).cmd
8ec4b4ff	202
5de043f4	203	# Execute the command and also postprocess generated .d dependencies file.
6796e804	204	if_changed_dep = $(if $(if-changed-cond),$(cmd_and_fixdep),@:)
c1a95fda	205
e4aca459	206	cmd_and_fixdep = \
3a2429e1	207	$(cmd); \
392885ee	208	scripts/basic/fixdep $(depfile) $@ '$(make-cmd)' > $(dot-target).cmd;\
e5d28910	209	rm -f $(depfile)
c1a95fda	210
8ec4b4ff	211	# Usage: $(call if_changed_rule,foo)
beda9f3a RZ	212	# Will check if $(cmd_foo) or any of the prerequisites changed,
beda9f3a RZ	213	# and if so will execute $(rule_foo).
6796e804	214	if_changed_rule = $(if $(if-changed-cond),$(rule_$(1)),@:)
48f1f058	215
45d506bd	216	###
312a3d09	217	# why - tell why a target got built
45d506bd SR	218	# enabled by make V=2
	219	# Output (listed in the order they are checked):
	220	# (1) - due to target is PHONY
	221	# (2) - due to target missing
	222	# (3) - due to: file1.h file2.h
	223	# (4) - due to command line change
	224	# (5) - due to missing .cmd file
	225	# (6) - due to target not in $(targets)
	226	# (1) PHONY targets are always build
	227	# (2) No target, so we better build it
	228	# (3) Prerequisite is newer than target
	229	# (4) The command line stored in the file named dir/.target.cmd
	230	# differed from actual command line. This happens when compiler
	231	# options changes
	232	# (5) No dir/.target.cmd file (used to store command line)
	233	# (6) No dir/.target.cmd file and target not listed in $(targets)
	234	# This is a good hint that there is a bug in the kbuild file
6ae4b986	235	ifneq ($(findstring 2, $(KBUILD_VERBOSE)),)
8962b6b4	236	_why = \
45d506bd SR	237	$(if $(filter $@, $(PHONY)),- due to target is PHONY, \
45d506bd SR	238	$(if $(wildcard $@), \
eba19032	239	$(if $(newer-prereqs),- due to: $(newer-prereqs), \
50bcca6a	240	$(if $(cmd-check), \
92215e7a	241	$(if $(savedcmd_$@),- due to command line change, \
45d506bd SR	242	$(if $(filter $@, $(targets)), \
	243	- due to missing .cmd file, \
	244	- due to $(notdir $@) not in $$(targets) \
	245	) \
	246	) \
	247	) \
	248	), \
	249	- due to target missing \
	250	) \
	251	)
	252
8962b6b4	253	why = $(space)$(strip $(_why))
45d506bd	254	endif
3ee550f1	255
3ee550f1	256	###############################################################################
9c2af1c7 MY	257
	258	# delete partially updated (i.e. corrupted) files on error
	259	.DELETE_ON_ERROR:
8e9b61b2 MY	260
8e9b61b2 MY	261	# do not delete intermediate files automatically
875ef1a5 MY	262	#
	263	# .NOTINTERMEDIATE is more correct, but only available on newer Make versions.
	264	# Make 4.4 introduced .NOTINTERMEDIATE, and it appears in .FEATURES, but the
	265	# global .NOTINTERMEDIATE does not work. We can use it on Make > 4.4.
	266	# Use .SECONDARY for older Make versions, but "newer-prereq" cannot detect
	267	# deleted files.
	268	ifneq ($(and $(filter notintermediate, $(.FEATURES)),$(filter-out 4.4,$(MAKE_VERSION))),)
	269	.NOTINTERMEDIATE:
	270	else
8e9b61b2	271	.SECONDARY:
875ef1a5	272	endif