diff options
Diffstat (limited to 'Documentation/kbuild')
| -rw-r--r-- | Documentation/kbuild/bash-completion.rst | 65 | ||||
| -rw-r--r-- | Documentation/kbuild/gendwarfksyms.rst | 246 | ||||
| -rw-r--r-- | Documentation/kbuild/index.rst | 7 | ||||
| -rw-r--r-- | Documentation/kbuild/kbuild.rst | 12 | ||||
| -rw-r--r-- | Documentation/kbuild/kconfig-language.rst | 85 | ||||
| -rw-r--r-- | Documentation/kbuild/kconfig.rst | 8 | ||||
| -rw-r--r-- | Documentation/kbuild/llvm.rst | 4 | ||||
| -rw-r--r-- | Documentation/kbuild/makefiles.rst | 27 | ||||
| -rw-r--r-- | Documentation/kbuild/modules.rst | 13 | ||||
| -rw-r--r-- | Documentation/kbuild/reproducible-builds.rst | 10 |
10 files changed, 363 insertions, 114 deletions
diff --git a/Documentation/kbuild/bash-completion.rst b/Documentation/kbuild/bash-completion.rst new file mode 100644 index 000000000000..2b52dbcd0933 --- /dev/null +++ b/Documentation/kbuild/bash-completion.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========================== +Bash completion for Kbuild +========================== + +The kernel build system is written using Makefiles, and Bash completion +for the `make` command is available through the `bash-completion`_ project. + +However, the Makefiles for the kernel build are complex. The generic completion +rules for the `make` command do not provide meaningful suggestions for the +kernel build system, except for the options of the `make` command itself. + +To enhance completion for various variables and targets, the kernel source +includes its own completion script at `scripts/bash-completion/make`. + +This script provides additional completions when working within the kernel tree. +Outside the kernel tree, it defaults to the generic completion rules for the +`make` command. + +Prerequisites +============= + +The script relies on helper functions provided by `bash-completion`_ project. +Please ensure it is installed on your system. On most distributions, you can +install the `bash-completion` package through the standard package manager. + +How to use +========== + +You can source the script directly:: + + $ source scripts/bash-completion/make + +Or, you can copy it into the search path for Bash completion scripts. +For example:: + + $ mkdir -p ~/.local/share/bash-completion/completions + $ cp scripts/bash-completion/make ~/.local/share/bash-completion/completions/ + +Details +======= + +The additional completion for Kbuild is enabled in the following cases: + + - You are in the root directory of the kernel source. + - You are in the top-level build directory created by the O= option + (checked via the `source` symlink pointing to the kernel source). + - The -C make option specifies the kernel source or build directory. + - The -f make option specifies a file in the kernel source or build directory. + +If none of the above are met, it falls back to the generic completion rules. + +The completion supports: + + - Commonly used targets, such as `all`, `menuconfig`, `dtbs`, etc. + - Make (or environment) variables, such as `ARCH`, `LLVM`, etc. + - Single-target builds (`foo/bar/baz.o`) + - Configuration files (`*_defconfig` and `*.config`) + +Some variables offer intelligent behavior. For instance, `CROSS_COMPILE=` +followed by a TAB displays installed toolchains. The list of defconfig files +shown depends on the value of the `ARCH=` variable. + +.. _bash-completion: https://github.com/scop/bash-completion/ diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst index e4beaae7e456..f1573dcc63ac 100644 --- a/Documentation/kbuild/gendwarfksyms.rst +++ b/Documentation/kbuild/gendwarfksyms.rst @@ -2,8 +2,8 @@ DWARF module versioning ======================= -1. Introduction -=============== +Introduction +============ When CONFIG_MODVERSIONS is enabled, symbol versions for modules are typically calculated from preprocessed source code using the @@ -14,27 +14,50 @@ selected, **gendwarfksyms** is used instead to calculate symbol versions from the DWARF debugging information, which contains the necessary details about the final module ABI. -1.1. Usage -========== +Dependencies +------------ + +gendwarfksyms depends on the libelf, libdw, and zlib libraries. + +Here are a few examples of how to install these dependencies: + +* Arch Linux and derivatives:: + + sudo pacman --needed -S libelf zlib + +* Debian, Ubuntu, and derivatives:: + + sudo apt install libelf-dev libdw-dev zlib1g-dev + +* Fedora and derivatives:: + + sudo dnf install elfutils-libelf-devel elfutils-devel zlib-devel + +* openSUSE and derivatives:: + + sudo zypper install libelf-devel libdw-devel zlib-devel + +Usage +----- gendwarfksyms accepts a list of object files on the command line, and a list of symbol names (one per line) in standard input:: - Usage: gendwarfksyms [options] elf-object-file ... < symbol-list + Usage: gendwarfksyms [options] elf-object-file ... < symbol-list - Options: - -d, --debug Print debugging information - --dump-dies Dump DWARF DIE contents - --dump-die-map Print debugging information about die_map changes - --dump-types Dump type strings - --dump-versions Dump expanded type strings used for symbol versions - -s, --stable Support kABI stability features - -T, --symtypes file Write a symtypes file - -h, --help Print this message + Options: + -d, --debug Print debugging information + --dump-dies Dump DWARF DIE contents + --dump-die-map Print debugging information about die_map changes + --dump-types Dump type strings + --dump-versions Dump expanded type strings used for symbol versions + -s, --stable Support kABI stability features + -T, --symtypes file Write a symtypes file + -h, --help Print this message -2. Type information availability -================================ +Type information availability +============================= While symbols are typically exported in the same translation unit (TU) where they're defined, it's also perfectly fine for a TU to export @@ -46,9 +69,9 @@ TU where symbols are actually exported, gendwarfksyms adds a pointer to exported symbols in the `EXPORT_SYMBOL()` macro using the following macro:: - #define __GENDWARFKSYMS_EXPORT(sym) \ - static typeof(sym) *__gendwarfksyms_ptr_##sym __used \ - __section(".discard.gendwarfksyms") = &sym; + #define __GENDWARFKSYMS_EXPORT(sym) \ + static typeof(sym) *__gendwarfksyms_ptr_##sym __used \ + __section(".discard.gendwarfksyms") = &sym; When a symbol pointer is found in DWARF, gendwarfksyms can use its @@ -56,8 +79,8 @@ type for calculating symbol versions even if the symbol is defined elsewhere. The name of the symbol pointer is expected to start with `__gendwarfksyms_ptr_`, followed by the name of the exported symbol. -3. Symtypes output format -========================= +Symtypes output format +====================== Similarly to genksyms, gendwarfksyms supports writing a symtypes file for each processed object that contain types for exported @@ -71,22 +94,22 @@ either a type reference or a symbol name. Type references have a one-letter prefix followed by "#" and the name of the type. Four reference types are supported:: - e#<type> = enum - s#<type> = struct - t#<type> = typedef - u#<type> = union + e#<type> = enum + s#<type> = struct + t#<type> = typedef + u#<type> = union Type names with spaces in them are wrapped in single quotes, e.g.:: - s#'core::result::Result<u8, core::num::error::ParseIntError>' + s#'core::result::Result<u8, core::num::error::ParseIntError>' The rest of the line contains a type string. Unlike with genksyms that produces C-style type strings, gendwarfksyms uses the same simple parsed DWARF format produced by **--dump-dies**, but with type references instead of fully expanded strings. -4. Maintaining a stable kABI -============================ +Maintaining a stable kABI +========================= Distribution maintainers often need the ability to make ABI compatible changes to kernel data structures due to LTS updates or backports. Using @@ -104,8 +127,8 @@ for source code annotation. Note that as these features are only used to transform the inputs for symbol versioning, the user is responsible for ensuring that their changes actually won't break the ABI. -4.1. kABI rules -=============== +kABI rules +---------- kABI rules allow distributions to fine-tune certain parts of gendwarfksyms output and thus control how symbol @@ -125,22 +148,25 @@ the rules. The fields are as follows: qualified name of the DWARF Debugging Information Entry (DIE). - `value`: Provides rule-specific data. -The following helper macro, for example, can be used to specify rules +The following helper macros, for example, can be used to specify rules in the source code:: - #define __KABI_RULE(hint, target, value) \ + #define ___KABI_RULE(hint, target, value) \ static const char __PASTE(__gendwarfksyms_rule_, \ __COUNTER__)[] __used __aligned(1) \ __section(".discard.gendwarfksyms.kabi_rules") = \ - "1\0" #hint "\0" #target "\0" #value + "1\0" #hint "\0" target "\0" value + + #define __KABI_RULE(hint, target, value) \ + ___KABI_RULE(hint, #target, #value) Currently, only the rules discussed in this section are supported, but the format is extensible enough to allow further rules to be added as need arises. -4.1.1. Managing definition visibility -===================================== +Managing definition visibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A declaration can change into a full definition when additional includes are pulled into the translation unit. This changes the versions of any @@ -168,8 +194,8 @@ Example usage:: KABI_DECLONLY(s); -4.1.2. Adding enumerators -========================= +Adding enumerators +~~~~~~~~~~~~~~~~~~ For enums, all enumerators and their values are included in calculating symbol versions, which becomes a problem if we later need to add more @@ -223,8 +249,89 @@ Example usage:: KABI_ENUMERATOR_IGNORE(e, C); KABI_ENUMERATOR_VALUE(e, LAST, 2); -4.3. Adding structure members -============================= +Managing structure size changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A data structure can be partially opaque to modules if its allocation is +handled by the core kernel, and modules only need to access some of its +members. In this situation, it's possible to append new members to the +structure without breaking the ABI, as long as the layout for the original +members remains unchanged. + +To append new members, we can hide them from symbol versioning as +described in section :ref:`Hiding members <hiding_members>`, but we can't +hide the increase in structure size. The `byte_size` rule allows us to +override the structure size used for symbol versioning. + +The rule fields are expected to be as follows: + +- `type`: "byte_size" +- `target`: The fully qualified name of the target data structure + (as shown in **--dump-dies** output). +- `value`: A positive decimal number indicating the structure size + in bytes. + +Using the `__KABI_RULE` macro, this rule can be defined as:: + + #define KABI_BYTE_SIZE(fqn, value) \ + __KABI_RULE(byte_size, fqn, value) + +Example usage:: + + struct s { + /* Unchanged original members */ + unsigned long a; + void *p; + + /* Appended new members */ + KABI_IGNORE(0, unsigned long n); + }; + + KABI_BYTE_SIZE(s, 16); + +Overriding type strings +~~~~~~~~~~~~~~~~~~~~~~~ + +In rare situations where distributions must make significant changes to +otherwise opaque data structures that have inadvertently been included +in the published ABI, keeping symbol versions stable using the more +targeted kABI rules can become tedious. The `type_string` rule allows us +to override the full type string for a type or a symbol, and even add +types for versioning that no longer exist in the kernel. + +The rule fields are expected to be as follows: + +- `type`: "type_string" +- `target`: The fully qualified name of the target data structure + (as shown in **--dump-dies** output) or symbol. +- `value`: A valid type string (as shown in **--symtypes**) output) + to use instead of the real type. + +Using the `__KABI_RULE` macro, this rule can be defined as:: + + #define KABI_TYPE_STRING(type, str) \ + ___KABI_RULE("type_string", type, str) + +Example usage:: + + /* Override type for a structure */ + KABI_TYPE_STRING("s#s", + "structure_type s { " + "member base_type int byte_size(4) " + "encoding(5) n " + "data_member_location(0) " + "} byte_size(8)"); + + /* Override type for a symbol */ + KABI_TYPE_STRING("my_symbol", "variable s#s"); + +The `type_string` rule should be used only as a last resort if maintaining +a stable symbol versions cannot be reasonably achieved using other +means. Overriding a type string increases the risk of actual ABI breakages +going unnoticed as it hides all changes to the type. + +Adding structure members +------------------------ Perhaps the most common ABI compatible change is adding a member to a kernel data structure. When changes to a structure are anticipated, @@ -237,8 +344,8 @@ natural method. This section describes gendwarfksyms support for using reserved space in data structures and hiding members that don't change the ABI when calculating symbol versions. -4.3.1. Reserving space and replacing members -============================================ +Reserving space and replacing members +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Space is typically reserved for later use by appending integer types, or arrays, to the end of the data structure, but any type can be used. Each @@ -246,21 +353,21 @@ reserved member needs a unique name, but as the actual purpose is usually not known at the time the space is reserved, for convenience, names that start with `__kabi_` are left out when calculating symbol versions:: - struct s { - long a; - long __kabi_reserved_0; /* reserved for future use */ - }; + struct s { + long a; + long __kabi_reserved_0; /* reserved for future use */ + }; The reserved space can be taken into use by wrapping the member in a union, which includes the original type and the replacement member:: - struct s { - long a; - union { - long __kabi_reserved_0; /* original type */ - struct b b; /* replaced field */ - }; - }; + struct s { + long a; + union { + long __kabi_reserved_0; /* original type */ + struct b b; /* replaced field */ + }; + }; If the `__kabi_` naming scheme was used when reserving space, the name of the first member of the union must start with `__kabi_reserved`. This @@ -276,18 +383,20 @@ The examples include `KABI_(RESERVE|USE|REPLACE)*` macros that help simplify the process and also ensure the replacement member is correctly aligned and its size won't exceed the reserved space. -4.3.2. Hiding members -===================== +.. _hiding_members: + +Hiding members +~~~~~~~~~~~~~~ Predicting which structures will require changes during the support timeframe isn't always possible, in which case one might have to resort to placing new members into existing alignment holes:: - struct s { - int a; - /* a 4-byte alignment hole */ - unsigned long b; - }; + struct s { + int a; + /* a 4-byte alignment hole */ + unsigned long b; + }; While this won't change the size of the data structure, one needs to @@ -296,13 +405,14 @@ to reserved fields, this can be accomplished by wrapping the added member to a union where one of the fields has a name starting with `__kabi_ignored`:: - struct s { - int a; - union { - char __kabi_ignored_0; - int n; - }; - unsigned long b; - }; + struct s { + int a; + union { + char __kabi_ignored_0; + int n; + }; + unsigned long b; + }; -With **--stable**, both versions produce the same symbol version. +With **--stable**, both versions produce the same symbol version. The +examples include a `KABI_IGNORE` macro to simplify the code. diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst index e82af05cd652..f46233be82b9 100644 --- a/Documentation/kbuild/index.rst +++ b/Documentation/kbuild/index.rst @@ -23,9 +23,4 @@ Kernel Build System llvm gendwarfksyms -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` + bash-completion diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index 3388a10f2dcc..5a9013bacfb7 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -180,7 +180,7 @@ architecture. KDOCFLAGS --------- Specify extra (warning/error) flags for kernel-doc checks during the build, -see scripts/kernel-doc for which flags are supported. Note that this doesn't +see tools/docs/kernel-doc for which flags are supported. Note that this doesn't (currently) apply to documentation builds. ARCH @@ -328,8 +328,14 @@ KBUILD_BUILD_TIMESTAMP ---------------------- Setting this to a date string overrides the timestamp used in the UTS_VERSION definition (uname -v in the running kernel). The value has to -be a string that can be passed to date -d. The default value -is the output of the date command at one point during build. +be a string that can be passed to date -d. E.g.:: + + $ KBUILD_BUILD_TIMESTAMP="Mon Oct 13 00:00:00 UTC 2025" make + +The default value is the output of the date command at one point during +build. If provided, this timestamp will also be used for mtime fields +within any initramfs archive. Initramfs mtimes are 32-bit, so dates before +the 1970 Unix epoch, or after 2106-02-07 06:28:15 UTC will fail. KBUILD_BUILD_USER, KBUILD_BUILD_HOST ------------------------------------ diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 2619fdf56e68..d9338407c1c6 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -118,7 +118,7 @@ applicable everywhere (see syntax). This is a shorthand notation for a type definition plus a value. Optionally dependencies for this default value can be added with "if". -- dependencies: "depends on" <expr> +- dependencies: "depends on" <expr> ["if" <expr>] This defines a dependency for this menu entry. If multiple dependencies are defined, they are connected with '&&'. Dependencies @@ -134,6 +134,16 @@ applicable everywhere (see syntax). bool "foo" default y + The dependency definition itself may be conditional by appending "if" + followed by an expression. For example:: + + config FOO + tristate + depends on BAR if BAZ + + meaning that FOO is constrained by the value of BAR only if BAZ is + also set. + - reverse dependencies: "select" <symbol> ["if" <expr>] While normal dependencies reduce the upper limit of a symbol (see @@ -194,16 +204,6 @@ applicable everywhere (see syntax). ability to hook into a secondary subsystem while allowing the user to configure that subsystem out without also having to unset these drivers. - Note: If the combination of FOO=y and BAZ=m causes a link error, - you can guard the function call with IS_REACHABLE():: - - foo_init() - { - if (IS_REACHABLE(CONFIG_BAZ)) - baz_register(&foo); - ... - } - Note: If the feature provided by BAZ is highly desirable for FOO, FOO should imply not only BAZ, but also its dependency BAR:: @@ -226,7 +226,7 @@ applicable everywhere (see syntax). - numerical ranges: "range" <symbol> <symbol> ["if" <expr>] - This allows to limit the range of possible input values for int + This allows limiting the range of possible input values for int and hex symbols. The user can only input a value which is larger than or equal to the first symbol and smaller than or equal to the second symbol. @@ -242,6 +242,38 @@ applicable everywhere (see syntax). enables the third modular state for all config symbols. At most one symbol may have the "modules" option set. +- transitional attribute: "transitional" + This declares the symbol as transitional, meaning it should be processed + during configuration but omitted from newly written .config files. + Transitional symbols are useful for backward compatibility during config + option migrations - they allow olddefconfig to process existing .config + files while ensuring the old option doesn't appear in new configurations. + + A transitional symbol: + - Has no prompt (is not visible to users in menus) + - Is processed normally during configuration (values are read and used) + - Can be referenced in default expressions of other symbols + - Is not written to new .config files + - Cannot have any other properties (it is a pass-through option) + + Example migration from OLD_NAME to NEW_NAME:: + + config NEW_NAME + bool "New option name" + default OLD_NAME + help + This replaces the old CONFIG_OLD_NAME option. + + config OLD_NAME + bool + transitional + help + Transitional config for OLD_NAME to NEW_NAME migration. + + With this setup, existing .config files with "CONFIG_OLD_NAME=y" will + result in "CONFIG_NEW_NAME=y" being set, while CONFIG_OLD_NAME will be + omitted from newly written .config files. + Menu dependencies ----------------- @@ -580,15 +612,23 @@ Some drivers are able to optionally use a feature from another module or build cleanly with that module disabled, but cause a link failure when trying to use that loadable module from a built-in driver. -The most common way to express this optional dependency in Kconfig logic -uses the slightly counterintuitive:: +The recommended way to express this optional dependency in Kconfig logic +uses the conditional form:: + + config FOO + tristate "Support for foo hardware" + depends on BAR if BAR + +This slightly counterintuitive style is also widely used:: config FOO tristate "Support for foo hardware" depends on BAR || !BAR This means that there is either a dependency on BAR that disallows -the combination of FOO=y with BAR=m, or BAR is completely disabled. +the combination of FOO=y with BAR=m, or BAR is completely disabled. The BAR +module must provide all the stubs for !BAR case. + For a more formalized approach if there are multiple drivers that have the same dependency, a helper symbol can be used, like:: @@ -599,6 +639,21 @@ the same dependency, a helper symbol can be used, like:: config BAR_OPTIONAL def_tristate BAR || !BAR +Much less favorable way to express optional dependency is IS_REACHABLE() within +the module code, useful for example when the module BAR does not provide +!BAR stubs:: + + foo_init() + { + if (IS_REACHABLE(CONFIG_BAR)) + bar_register(&foo); + ... + } + +IS_REACHABLE() is generally discouraged, because the code will be silently +discarded, when CONFIG_BAR=m and this code is built-in. This is not what users +usually expect when enabling BAR as module. + Kconfig recursive dependency limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index fc4e845bc249..d213c4f599a4 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -67,12 +67,12 @@ Environment variables for ``*config``: with its value when saving the configuration, instead of using the default, ``CONFIG_``. -Environment variables for ``{allyes/allmod/allno/rand}config``: +Environment variables for ``{allyes/allmod/allno/alldef/rand}config``: ``KCONFIG_ALLCONFIG`` - The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also - use the environment variable KCONFIG_ALLCONFIG as a flag or a filename - that contains config symbols that the user requires to be set to a + The allyesconfig/allmodconfig/alldefconfig/allnoconfig/randconfig variants + can also use the environment variable KCONFIG_ALLCONFIG as a flag or a + filename that contains config symbols that the user requires to be set to a specific value. If KCONFIG_ALLCONFIG is used without a filename where KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", ``make *config`` checks for a file named "all{yes/mod/no/def/random}.config" diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index bc8a283bc44b..441d8786fcbc 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -71,10 +71,6 @@ recommend:: PATH=/path/to/llvm/:$PATH make LLVM=-14 -``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like -``LLVM=1``. If you only wish to use certain LLVM utilities, use their -respective make variables. - The same value used for ``LLVM=`` should be set for each invocation of ``make`` if configuring and building via distinct commands. ``LLVM=`` should also be set as an environment variable when running scripts that will eventually run diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index d36519f194dc..24a4708d26e8 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -291,6 +291,10 @@ Example:: # arch/x86/kernel/Makefile extra-y += vmlinux.lds +extra-y is now deprecated because this is equivalent to: + + always-$(KBUILD_BUILTIN) += vmlinux.lds + $(extra-y) should only contain targets needed for vmlinux. Kbuild skips extra-y when vmlinux is apparently not a final goal. @@ -318,9 +322,6 @@ 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. ccflags-y specifies options for compiling with $(CC). @@ -628,10 +629,10 @@ gcc-min-version Example:: - cflags-$(call gcc-min-version, 70100) := -foo + cflags-$(call gcc-min-version, 110100) := -foo In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and - $(CONFIG_GCC_VERSION) is >= 7.1. + $(CONFIG_GCC_VERSION) is >= 11.1. clang-min-version clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater @@ -670,6 +671,20 @@ cc-cross-prefix endif endif +$(RUSTC) support functions +-------------------------- + +rustc-min-version + rustc-min-version tests if the value of $(CONFIG_RUSTC_VERSION) is greater + than or equal to the provided value and evaluates to y if so. + + Example:: + + rustflags-$(call rustc-min-version, 108500) := -Cfoo + + In this example, rustflags-y will be assigned the value -Cfoo if + $(CONFIG_RUSTC_VERSION) is >= 1.85.0. + $(LD) support functions ----------------------- @@ -1249,7 +1264,7 @@ Add prerequisites to archheaders -------------------------------- The archheaders: rule is used to generate header files that -may be installed into user space by ``make header_install``. +may be installed into user space by ``make headers_install``. It is run before ``make archprepare`` when run on the architecture itself. diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index a42f00d8cb90..b3a26a36ee17 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -318,7 +318,7 @@ Several Subdirectories | |__ include | |__ hardwareif.h |__ include - |__ complex.h + |__ complex.h To build the module complex.ko, we then need the following kbuild file:: @@ -426,11 +426,12 @@ Symbols From the Kernel (vmlinux + modules) Version Information Formats --------------------------- - Exported symbols have information stored in __ksymtab or __ksymtab_gpl - sections. Symbol names and namespaces are stored in __ksymtab_strings, - using a format similar to the string table used for ELF. If - CONFIG_MODVERSIONS is enabled, the CRCs corresponding to exported - symbols will be added to the __kcrctab or __kcrctab_gpl. + Exported symbols have information stored in the __ksymtab and + __kflagstab sections. Symbol names and namespaces are stored in + __ksymtab_strings section, using a format similar to the string + table used for ELF. If CONFIG_MODVERSIONS is enabled, the CRCs + corresponding to exported symbols will be added to the + __kcrctab section. If CONFIG_BASIC_MODVERSIONS is enabled (default with CONFIG_MODVERSIONS), imported symbols will have their symbol name and diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst index f2dcc39044e6..bc1eb82211df 100644 --- a/Documentation/kbuild/reproducible-builds.rst +++ b/Documentation/kbuild/reproducible-builds.rst @@ -50,8 +50,10 @@ Absolute filenames ------------------ When the kernel is built out-of-tree, debug information may include -absolute filenames for the source files. This must be overridden by -including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. +absolute filenames for the source files and build directory. These must +be overridden by including a ``-fdebug-prefix-map`` option for each in +the `KCFLAGS`_ and `KAFLAGS`_ variables to cover both ``.c`` and ``.S`` +files. Depending on the compiler used, the ``__FILE__`` macro may also expand to an absolute filename in an out-of-tree build. Kbuild automatically @@ -61,6 +63,9 @@ supported. The Reproducible Builds web site has more information about these `prefix-map options`_. +Some CONFIG options such as `CONFIG_DEBUG_EFI` embed absolute paths in +object files. Such options should be disabled. + Generated files in source packages ---------------------------------- @@ -132,6 +137,7 @@ See ``scripts/setlocalversion`` for details. .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host .. _KCFLAGS: kbuild.html#kcflags +.. _KAFLAGS: kbuild.html#kaflags .. _prefix-map options: https://reproducible-builds.org/docs/build-path/ .. _Reproducible Builds project: https://reproducible-builds.org/ .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ |