Skip to contentSkip to conversation

kbuild: doc: describe proper script invocation

RFC PATCH In review Lukas Bulwahn 2 participants 2 messages Sep 28, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 kbuild: doc: describe proper script invocation

During an investigation to fix up the execute bits of scripts in the kernel repository, Andrew Morton and Kees Cook pointed out that the execute bit should not matter, and that build scripts cannot rely on that. Kees could not point to any documentation, though.

Provide some basic documentation how the build shall invoke scripts, such that the execute bits do not matter.

This serves as reference for further clean-up patches in the future.

---
applies cleanly on next-20200925 and v5.9-rc7

Kees, Andrew, please ack.

Masahiro-san, please pick this small documentation update into your kbuild tree.

Ujjwal Kumar, a potential future mentee, will follow up with further fixes to the build scripts.

 Documentation/kbuild/makefiles.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
Documentation/kbuild/makefiles.rst +18 -0
index 58d513a0fa95..9d0d198adb7e 100644
@@ -21,6 +21,7 @@ This document describes the Linux kernel Makefiles.
 	   --- 3.10 Special Rules
 	   --- 3.11 $(CC) support functions
 	   --- 3.12 $(LD) support functions
+	   --- 3.13 Script Invocation
 
 	=== 4 Host Program support
 	   --- 4.1 Simple Host Program
@@ -605,6 +606,23 @@ more details, with real examples.
 		#Makefile
 		LDFLAGS_vmlinux += $(call ld-option, -X)
 
+3.13 Script invocation
+----------------------
+
+	Make rules may invoke scripts to build the kernel. The rules shall
+	always provide the appropriate interpreter to execute the script. They
+	shall not rely on the execute bits being set, and shall not invoke the
+	script directly.
+
+	Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),
+	$(PYTHON) and $(PYTHON3) to refer to interpreters for the respective
+	scripts.
+
+	Example::
+
+		#Makefile
+		cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \
+			     $(KERNELRELEASE)
 
 4 Host Program support
 ======================
Signature · 1 line
2.17.1
#1 lore raw
Quoted 10 lines · Lukas Bulwahn

During an investigation to fix up the execute bits of scripts in the kernel repository, Andrew Morton and Kees Cook pointed out that the execute bit should not matter, and that build scripts cannot rely on that. Kees could not point to any documentation, though.

Provide some basic documentation how the build shall invoke scripts, such that the execute bits do not matter.

This serves as reference for further clean-up patches in the future.

For scripts run by users directly, the executable bit should be set. (e.g. scripts/checkpatch.pl)

For scripts invoked from the build system, the convention is to use interpreters such as $(CONFIG_SHELL), and we do not need to set
the executable bit. But, we often set the executable bit for this case, too.

This convention started from the following commit, which was made by the previous kbuild maintainer.

commit 06ed5c2bfacaf67039e87a213fa5d1cdde34246a

Author: Michal Marek <[email protected]>
Date:   Wed Aug 20 16:02:59 2014 +0200

kbuild: Make scripts executable

The Makefiles call the respective interpreter explicitly, but this makes it easier to use the scripts manually.

Quoted 58 lines

---
applies cleanly on next-20200925 and v5.9-rc7

Kees, Andrew, please ack.

Masahiro-san, please pick this small documentation update into your kbuild tree.

Ujjwal Kumar, a potential future mentee, will follow up with further fixes to the build scripts.

 Documentation/kbuild/makefiles.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
Documentation/kbuild/makefiles.rst +18 -1
index 58d513a0fa95..9d0d198adb7e 100644
@@ -21,6 +21,7 @@ This document describes the Linux kernel Makefiles.
           --- 3.10 Special Rules
           --- 3.11 $(CC) support functions
           --- 3.12 $(LD) support functions
+          --- 3.13 Script Invocation
 
        === 4 Host Program support
           --- 4.1 Simple Host Program
@@ -605,6 +606,23 @@ more details, with real examples.
                #Makefile
                LDFLAGS_vmlinux += $(call ld-option, -X)
 
+3.13 Script invocation
+----------------------
+
+       Make rules may invoke scripts to build the kernel. The rules shall
+       always provide the appropriate interpreter to execute the script. They
+       shall not rely on the execute bits being set, and shall not invoke the
+       script directly.
+
+       Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL),
+       $(PYTHON) and $(PYTHON3) to refer to interpreters for the respective
+       scripts.
+
+       Example::
+
+               #Makefile
+               cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \
+                            $(KERNELRELEASE)
 
 4 Host Program support
 ======================
--

2.17.1

Signature · 2 lines
Best Regards
Masahiro Yamada