[PATCH] doc: Bring in Makefile documentation

[Heinrich Schuchardt]

Am 21. Juli 2021 22:56:58 MESZ schrieb Simon Glass <sjg at chromium.org>:
>U-Boot uses the Linux Kbuild build system. Add the associated
>documentation so that people can understand the Makefiles better.
>
>This is taken from Linux v5.12
>
>Signed-off-by: Simon Glass <sjg at chromium.org>
>---
>
> doc/develop/index.rst     |    1 +
> doc/develop/makefiles.rst | 1674 +++++++++++++++++++++++++++++++++++++
> 2 files changed, 1675 insertions(+)
> create mode 100644 doc/develop/makefiles.rst
>
>diff --git a/doc/develop/index.rst b/doc/develop/index.rst
>index 3edffbc6373..c1bbca617c9 100644
>--- a/doc/develop/index.rst
>+++ b/doc/develop/index.rst
>@@ -16,6 +16,7 @@ Implementation
>    menus
>    uefi/index
>    version
>+   makefiles

I would prefer to keep the alphabetic order.

Best regards

Heinrich

> 
> Debugging
> ---------
>diff --git a/doc/develop/makefiles.rst b/doc/develop/makefiles.rst
>new file mode 100644
>index 00000000000..c3b5b66992b
>--- /dev/null
>+++ b/doc/develop/makefiles.rst
>@@ -0,0 +1,1674 @@
>+======================
>+Linux Kernel Makefiles
>+======================
>+
>+Note: This document mostly applies to U-Boot so is included here.
>+
>+This document describes the Linux kernel Makefiles.
>+
>+.. Table of Contents
>+
>+	=== 1 Overview
>+	=== 2 Who does what
>+	=== 3 The kbuild files
>+	   --- 3.1 Goal definitions
>+	   --- 3.2 Built-in object goals - obj-y
>+	   --- 3.3 Loadable module goals - obj-m
>+	   --- 3.4 <deleted>
>+	   --- 3.5 Library file goals - lib-y
>+	   --- 3.6 Descending down in directories
>+	   --- 3.7 Non-builtin vmlinux targets - extra-y
>+	   --- 3.8 Always built goals - always-y
>+	   --- 3.9 Compilation flags
>+	   --- 3.10 Dependency tracking
>+	   --- 3.11 Custom Rules
>+	   --- 3.12 Command change detection
>+	   --- 3.13 $(CC) support functions
>+	   --- 3.14 $(LD) support functions
>+	   --- 3.15 Script Invocation
>+
>+	=== 4 Host Program support
>+	   --- 4.1 Simple Host Program
>+	   --- 4.2 Composite Host Programs
>+	   --- 4.3 Using C++ for host programs
>+	   --- 4.4 Controlling compiler options for host programs
>+	   --- 4.5 When host programs are actually built
>+
>+	=== 5 Userspace Program support
>+	   --- 5.1 Simple Userspace Program
>+	   --- 5.2 Composite Userspace Programs
>+	   --- 5.3 Controlling compiler options for userspace programs
>+	   --- 5.4 When userspace programs are actually built
>+
>+	=== 6 Kbuild clean infrastructure
>+
>+	=== 7 Architecture Makefiles
>+	   --- 7.1 Set variables to tweak the build to the architecture
>+	   --- 7.2 Add prerequisites to archheaders
>+	   --- 7.3 Add prerequisites to archprepare
>+	   --- 7.4 List directories to visit when descending
>+	   --- 7.5 Architecture-specific boot images
>+	   --- 7.6 Building non-kbuild targets
>+	   --- 7.7 Commands useful for building a boot image
>+	   --- 7.8 <deleted>
>+	   --- 7.9 Preprocessing linker scripts
>+	   --- 7.10 Generic header files
>+	   --- 7.11 Post-link pass
>+
>+	=== 8 Kbuild syntax for exported headers
>+		--- 8.1 no-export-headers
>+		--- 8.2 generic-y
>+		--- 8.3 generated-y
>+		--- 8.4 mandatory-y
>+
>+	=== 9 Kbuild Variables
>+	=== 10 Makefile language
>+	=== 11 Credits
>+	=== 12 TODO
>+
>+1 Overview
>+==========
>+
>+The Makefiles have five parts::
>+
>+	Makefile                    the top Makefile.
>+	.config                     the kernel configuration file.
>+	arch/$(SRCARCH)/Makefile    the arch Makefile.
>+	scripts/Makefile.*          common rules etc. for all kbuild
>Makefiles.
>+	kbuild Makefiles            exist in every subdirectory
>+
>+The top Makefile reads the .config file, which comes from the kernel
>+configuration process.
>+
>+The top Makefile is responsible for building two major products:
>vmlinux
>+(the resident kernel image) and modules (any module files).
>+It builds these goals by recursively descending into the
>subdirectories of
>+the kernel source tree.
>+The list of subdirectories which are visited depends upon the kernel
>+configuration. The top Makefile textually includes an arch Makefile
>+with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies
>+architecture-specific information to the top Makefile.
>+
>+Each subdirectory has a kbuild Makefile which carries out the commands
>+passed down from above. The kbuild Makefile uses information from the
>+.config file to construct various file lists used by kbuild to build
>+any built-in or modular targets.
>+
>+scripts/Makefile.* contains all the definitions/rules etc. that
>+are used to build the kernel based on the kbuild makefiles.
>+
>+
>+2 Who does what
>+===============
>+
>+People have four different relationships with the kernel Makefiles.
>+
>+*Users* are people who build kernels.  These people type commands such
>as
>+"make menuconfig" or "make".  They usually do not read or edit
>+any kernel Makefiles (or any other source files).
>+
>+*Normal developers* are people who work on features such as device
>+drivers, file systems, and network protocols.  These people need to
>+maintain the kbuild Makefiles for the subsystem they are
>+working on.  In order to do this effectively, they need some overall
>+knowledge about the kernel Makefiles, plus detailed knowledge about
>the
>+public interface for kbuild.
>+
>+*Arch developers* are people who work on an entire architecture, such
>+as sparc or ia64.  Arch developers need to know about the arch
>Makefile
>+as well as kbuild Makefiles.
>+
>+*Kbuild developers* are people who work on the kernel build system
>itself.
>+These people need to know about all aspects of the kernel Makefiles.
>+
>+This document is aimed towards normal developers and arch developers.
>+
>+
>+3 The kbuild files
>+==================
>+
>+Most Makefiles within the kernel are kbuild Makefiles that use the
>+kbuild infrastructure. This chapter introduces the syntax used in the
>+kbuild makefiles.
>+The preferred name for the kbuild files are 'Makefile' but 'Kbuild'
>can
>+be used and if both a 'Makefile' and a 'Kbuild' file exists, then the
>'Kbuild'
>+file will be used.
>+
>+Section 3.1 "Goal definitions" is a quick intro; further chapters
>provide
>+more details, with real examples.
>+
>+3.1 Goal definitions
>+--------------------
>+
>+	Goal definitions are the main part (heart) of the kbuild Makefile.
>+	These lines define the files to be built, any special compilation
>+	options, and any subdirectories to be entered recursively.
>+
>+	The most simple kbuild makefile contains one line:
>+
>+	Example::
>+
>+		obj-y += foo.o
>+
>+	This tells kbuild that there is one object in that directory, named
>+	foo.o. foo.o will be built from foo.c or foo.S.
>+
>+	If foo.o shall be built as a module, the variable obj-m is used.
>+	Therefore the following pattern is often used:
>+
>+	Example::
>+
>+		obj-$(CONFIG_FOO) += foo.o
>+
>+	$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
>+	If CONFIG_FOO is neither y nor m, then the file will not be compiled
>+	nor linked.
>+
>+3.2 Built-in object goals - obj-y
>+---------------------------------
>+
>+	The kbuild Makefile specifies object files for vmlinux
>+	in the $(obj-y) lists.  These lists depend on the kernel
>+	configuration.
>+
>+	Kbuild compiles all the $(obj-y) files.  It then calls
>+	"$(AR) rcSTP" to merge these files into one built-in.a file.
>+	This is a thin archive without a symbol table. It will be later
>+	linked into vmlinux by scripts/link-vmlinux.sh
>+
>+	The order of files in $(obj-y) is significant.  Duplicates in
>+	the lists are allowed: the first instance will be linked into
>+	built-in.a and succeeding instances will be ignored.
>+
>+	Link order is significant, because certain functions
>+	(module_init() / __initcall) will be called during boot in the
>+	order they appear. So keep in mind that changing the link
>+	order may e.g. change the order in which your SCSI
>+	controllers are detected, and thus your disks are renumbered.
>+
>+	Example::
>+
>+		#drivers/isdn/i4l/Makefile
>+		# Makefile for the kernel ISDN subsystem and device drivers.
>+		# Each configuration option enables a list of files.
>+		obj-$(CONFIG_ISDN_I4L)         += isdn.o
>+		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
>+
>+3.3 Loadable module goals - obj-m
>+---------------------------------
>+
>+	$(obj-m) specifies object files which are built as loadable
>+	kernel modules.
>+
>+	A module may be built from one source file or several source
>+	files. In the case of one source file, the kbuild makefile
>+	simply adds the file to $(obj-m).
>+
>+	Example::
>+
>+		#drivers/isdn/i4l/Makefile
>+		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
>+
>+	Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
>+
>+	If a kernel module is built from several source files, you specify
>+	that you want to build a module in the same way as above; however,
>+	kbuild needs to know which object files you want to build your
>+	module from, so you have to tell it by setting a $(<module_name>-y)
>+	variable.
>+
>+	Example::
>+
>+		#drivers/isdn/i4l/Makefile
>+		obj-$(CONFIG_ISDN_I4L) += isdn.o
>+		isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
>+
>+	In this example, the module name will be isdn.o. Kbuild will
>+	compile the objects listed in $(isdn-y) and then run
>+	"$(LD) -r" on the list of these files to generate isdn.o.
>+
>+	Due to kbuild recognizing $(<module_name>-y) for composite objects,
>+	you can use the value of a `CONFIG_` symbol to optionally include an
>+	object file as part of a composite object.
>+
>+	Example::
>+
>+		#fs/ext2/Makefile
>+	        obj-$(CONFIG_EXT2_FS) += ext2.o
>+		ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
>+			  namei.o super.o symlink.o
>+	        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
>+						xattr_trusted.o
>+
>+	In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
>+	part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
>+	evaluates to 'y'.
>+
>+	Note: Of course, when you are building objects into the kernel,
>+	the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
>+	kbuild will build an ext2.o file for you out of the individual
>+	parts and then link this into built-in.a, as you would expect.
>+
>+3.5 Library file goals - lib-y
>+------------------------------
>+
>+	Objects listed with obj-* are used for modules, or
>+	combined in a built-in.a for that specific directory.
>+	There is also the possibility to list objects that will
>+	be included in a library, lib.a.
>+	All objects listed with lib-y are combined in a single
>+	library for that directory.
>+	Objects that are listed in obj-y and additionally listed in
>+	lib-y will not be included in the library, since they will
>+	be accessible anyway.
>+	For consistency, objects listed in lib-m will be included in lib.a.
>+
>+	Note that the same kbuild makefile may list files to be built-in
>+	and to be part of a library. Therefore the same directory
>+	may contain both a built-in.a and a lib.a file.
>+
>+	Example::
>+
>+		#arch/x86/lib/Makefile
>+		lib-y    := delay.o
>+
>+	This will create a library lib.a based on delay.o. For kbuild to
>+	actually recognize that there is a lib.a being built, the directory
>+	shall be listed in libs-y.
>+
>+	See also "7.4 List directories to visit when descending".
>+
>+	Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
>+
>+3.6 Descending down in directories
>+----------------------------------
>+
>+	A Makefile is only responsible for building objects in its own
>+	directory. Files in subdirectories should be taken care of by
>+	Makefiles in these subdirs. The build system will automatically
>+	invoke make recursively in subdirectories, provided you let it know
>of
>+	them.
>+
>+	To do so, obj-y and obj-m are used.
>+	ext2 lives in a separate directory, and the Makefile present in fs/
>+	tells kbuild to descend down using the following assignment.
>+
>+	Example::
>+
>+		#fs/Makefile
>+		obj-$(CONFIG_EXT2_FS) += ext2/
>+
>+	If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
>+	the corresponding obj- variable will be set, and kbuild will descend
>+	down in the ext2 directory.
>+
>+	Kbuild uses this information not only to decide that it needs to
>visit
>+	the directory, but also to decide whether or not to link objects from
>+	the directory into vmlinux.
>+
>+	When Kbuild descends into the directory with 'y', all built-in
>objects
>+	from that directory are combined into the built-in.a, which will be
>+	eventually linked into vmlinux.
>+
>+	When Kbuild descends into the directory with 'm', in contrast,
>nothing
>+	from that directory will be linked into vmlinux. If the Makefile in
>+	that directory specifies obj-y, those objects will be left orphan.
>+	It is very likely a bug of the Makefile or of dependencies in
>Kconfig.
>+
>+	Kbuild also supports dedicated syntax, subdir-y and subdir-m, for
>+	descending into subdirectories. It is a good fit when you know they
>+	do not contain kernel-space objects at all. A typical usage is to let
>+	Kbuild descend into subdirectories to build tools.
>+
>+	Examples::
>+
>+		# scripts/Makefile
>+		subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins
>+		subdir-$(CONFIG_MODVERSIONS) += genksyms
>+		subdir-$(CONFIG_SECURITY_SELINUX) += selinux
>+
>+	Unlike obj-y/m, subdir-y/m does not need the trailing slash since
>this
>+	syntax is always used for directories.
>+
>+	It is good practice to use a `CONFIG_` variable when assigning
>directory
>+	names. This allows kbuild to totally skip the directory if the
>+	corresponding `CONFIG_` option is neither 'y' nor 'm'.
>+
>+3.7 Non-builtin vmlinux targets - extra-y
>+-----------------------------------------
>+
>+	extra-y specifies targets which are needed for building vmlinux,
>+	but not combined into built-in.a.
>+
>+	Examples are:
>+
>+	1) head objects
>+
>+	    Some objects must be placed at the head of vmlinux. They are
>+	    directly linked to vmlinux without going through built-in.a
>+	    A typical use-case is an object that contains the entry point.
>+
>+	    arch/$(SRCARCH)/Makefile should specify such objects as head-y.
>+
>+	    Discussion:
>+	      Given that we can control the section order in the linker
>script,
>+	      why do we need head-y?
>+
>+	2) vmlinux linker script
>+
>+	    The linker script for vmlinux is located at
>+	    arch/$(SRCARCH)/kernel/vmlinux.lds
>+
>+	Example::
>+
>+		# arch/x86/kernel/Makefile
>+		extra-y	:= head_$(BITS).o
>+		extra-y	+= head$(BITS).o
>+		extra-y	+= ebda.o
>+		extra-y	+= platform-quirks.o
>+		extra-y	+= vmlinux.lds
>+
>+	$(extra-y) should only contain targets needed for vmlinux.
>+
>+	Kbuild skips extra-y when vmlinux is apparently not a final goal.
>+	(e.g. 'make modules', or building external modules)
>+
>+	If you intend to build targets unconditionally, always-y (explained
>+	in the next section) is the correct syntax to use.
>+
>+3.8 Always built goals - always-y
>+---------------------------------
>+
>+	always-y specifies targets which are literally always built when
>+	Kbuild visits the Makefile.
>+
>+	Example::
>+	  # ./Kbuild
>+	  offsets-file := include/generated/asm-offsets.h
>+	  always-y += $(offsets-file)
>+
>+3.9 Compilation flags
>+---------------------
>+
>+    ccflags-y, asflags-y and ldflags-y
>+	These three flags apply only to the kbuild makefile in which they
>+	are assigned. They are used for all the normal cc, as and ld
>+	invocations happening during a recursive build.
>+	Note: Flags with the same behaviour were previously named:
>+	EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
>+	They are still supported but their usage is deprecated.
>+