Re: [PATCH] doc: Bring in Makefile documentation

Am 21. Juli 2021 22:56:58 MESZ schrieb Simon Glass sjg@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@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.