kbuild.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. include:: ../disclaimer-zh_CN.rst
  4
  5:Original: Documentation/kbuild/kbuild.rst
  6:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
  7
  8======
  9Kbuild
 10======
 11
 12
 13输出文件
 14========
 15
 16modules.order
 17-------------
 18该文件记录模块在 Makefile 中出现的顺序。modprobe 使用该文件来确定性
 19解析匹配多个模块的别名。
 20
 21modules.builtin
 22---------------
 23该文件列出了所有内置到内核中的模块。modprobe 使用该文件来避免尝试加载
 24内置模块时出错。
 25
 26modules.builtin.modinfo
 27-----------------------
 28该文件包含所有内置模块的 modinfo。与单独模块的 modinfo 不同，所有字段
 29都带有模块名称前缀。
 30
 31modules.builtin.ranges
 32----------------------
 33该文件包含所有内核内置模块的地址偏移范围（每个 ELF 节）。结合 System.map
 34文件，它可以用来将模块名称与符号关联起来。
 35
 36环境变量
 37========
 38
 39KCPPFLAGS
 40---------
 41在预处理时传递的额外选项。kbuild 进行所有预处理（包括构建 C 文件和汇编文件）
 42时，都会使用这些预处理选项。
 43
 44KAFLAGS
 45-------
 46传递给汇编器的额外选项（适用于内置模块和外部模块）。
 47
 48AFLAGS_MODULE
 49-------------
 50外部模块的额外汇编选项。
 51
 52AFLAGS_KERNEL
 53-------------
 54内置模块的额外汇编选项。
 55
 56KCFLAGS
 57-------
 58传递给 C 编译器的额外选项（适用于内置模块和外部模块）。
 59
 60KRUSTFLAGS
 61----------
 62传递给 Rust 编译器的额外选项（适用于内置模块和外部模块）。
 63
 64CFLAGS_KERNEL
 65-------------
 66在编译内置代码时，传递给 $(CC) 的额外选项。
 67
 68CFLAGS_MODULE
 69-------------
 70编译外部模块时，传递给 $(CC) 的额外模块特定选项。
 71
 72RUSTFLAGS_KERNEL
 73----------------
 74在编译内置代码时，传递给 $(RUSTC) 的额外选项。
 75
 76RUSTFLAGS_MODULE
 77----------------
 78用于 $(RUSTC) 的额外模块特定选项。
 79
 80LDFLAGS_MODULE
 81--------------
 82用于 $(LD) 链接模块时的额外选项。
 83
 84HOSTCFLAGS
 85----------
 86在构建主机程序时传递给 $(HOSTCC) 的额外标志。
 87
 88HOSTCXXFLAGS
 89------------
 90在构建主机程序时传递给 $(HOSTCXX) 的额外标志。
 91
 92HOSTRUSTFLAGS
 93-------------
 94在构建主机程序时传递给 $(HOSTRUSTC) 的额外标志。
 95
 96PROCMACROLDFLAGS
 97----------------
 98用于链接 Rust 过程宏的标志。由于过程宏是由 rustc 在构建时加载的，
 99因此必须以与当前使用的 rustc 工具链兼容的方式进行链接。
100
101例如，当 rustc 使用的 C 库与用户希望用于主机程序的 C 库不同时，
102此设置会非常有用。
103
104如果未设置，则默认使用链接主机程序时传递的标志。
105
106HOSTLDFLAGS
107-----------
108链接主机程序时传递的额外选项。
109
110HOSTLDLIBS
111----------
112在构建主机程序时链接的额外库。
113
114.. _zh_cn_userkbuildflags:
115
116USERCFLAGS
117----------
118用于 $(CC) 编译用户程序（userprogs）时的额外选项。
119
120USERLDFLAGS
121-----------
122用于 $(LD) 链接用户程序时的额外选项。用户程序（userprogs）是使用 CC 链接的，
123因此 $(USERLDFLAGS) 应该根据需要包含 "-Wl," 前缀。
124
125KBUILD_KCONFIG
126--------------
127将顶级 Kconfig 文件设置为此环境变量的值。默认名称为 "Kconfig"。
128
129KBUILD_VERBOSE
130--------------
131设置 kbuild 的详细程度。可以分配与 "V=..." 相同的值。
132
133有关完整列表，请参见 `make help`。
134
135设置 "V=..." 优先于 KBUILD_VERBOSE。
136
137KBUILD_EXTMOD
138-------------
139在构建外部模块时设置内核源代码的搜索目录。
140
141设置 "M=..." 优先于 KBUILD_EXTMOD。
142
143KBUILD_OUTPUT
144-------------
145指定内核构建的输出目录。
146
147在单独的构建目录中为预构建内核构建外部模块时，这个变量也可以指向内核输出目录。请注意，
148这并不指定外部模块本身的输出目录(使用 KBUILD_EXTMOD_OUTPUT 来达到这个目的)。
149
150输出目录也可以使用 "O=..." 指定。
151
152设置 "O=..." 优先于 KBUILD_OUTPUT。
153
154KBUILD_EXTMOD_OUTPUT
155--------------------
156指定外部模块的输出目录
157
158设置 "MO=..." 优先于 KBUILD_EXTMOD_OUTPUT.
159
160KBUILD_EXTRA_WARN
161-----------------
162指定额外的构建检查。也可以通过在命令行传递 "W=..." 来设置相同的值。
163
164请参阅 `make help` 了解支持的值列表。
165
166设置 "W=..." 优先于 KBUILD_EXTRA_WARN。
167
168KBUILD_DEBARCH
169--------------
170对于 deb-pkg 目标，允许覆盖 deb-pkg 部署的正常启发式方法。通常 deb-pkg 尝试根据
171UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确的架构。KBUILD_DEBARCH
172的值假定（不检查）为有效的 Debian 架构。
173
174KDOCFLAGS
175---------
176指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
177scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
178
179ARCH
180----
181设置 ARCH 为要构建的架构。
182
183在大多数情况下，架构的名称与 arch/ 目录中的子目录名称相同。
184
185但某些架构（如 x86 和 sparc）有别名。
186
187- x86: i386 表示 32 位，x86_64 表示 64 位
188- parisc: parisc64 表示 64 位
189- sparc: sparc32 表示 32 位，sparc64 表示 64 位
190
191CROSS_COMPILE
192-------------
193指定 binutils 文件名的可选固定部分。CROSS_COMPILE 可以是文件名的一部分或完整路径。
194
195在某些设置中，CROSS_COMPILE 也用于 ccache。
196
197CF
198--
199用于 sparse 的额外选项。
200
201CF 通常在命令行中如下所示使用::
202
203    make CF=-Wbitwise C=2
204
205INSTALL_PATH
206------------
207INSTALL_PATH 指定放置更新后的内核和系统映像的路径。默认值是 /boot，但你可以设置
208为其他值。
209
210INSTALLKERNEL
211-------------
212使用 "make install" 时调用的安装脚本。
213默认名称是 "installkernel"。
214
215该脚本将会以以下参数调用：
216
217   - $1 - 内核版本
218   - $2 - 内核映像文件
219   - $3 - 内核映射文件
220   - $4 - 默认安装路径（如果为空，则使用根目录）
221
222"make install" 的实现是架构特定的，可能与上述有所不同。
223
224提供 INSTALLKERNEL 以便在交叉编译内核时可以指定自定义安装程序。
225
226MODLIB
227------
228指定模块的安装位置。
229默认值为::
230
231    $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
232
233该值可以被覆盖，在这种情况下将忽略默认值。
234
235INSTALL_MOD_PATH
236----------------
237INSTALL_MOD_PATH 指定了模块目录重定位时 MODLIB 的前缀，通常由构建根
238（build roots）所需。它没有在 makefile 中定义，但如果需要，可以作为
239参数传递给 make。
240
241INSTALL_MOD_STRIP
242-----------------
243如果 INSTALL_MOD_STRIP 被定义，内核模块在安装后会被剥离。如果
244INSTALL_MOD_STRIP 的值为 '1'，则会使用默认选项 --strip-debug。否则，
245INSTALL_MOD_STRIP 的值将作为 strip 命令的选项。
246
247INSTALL_HDR_PATH
248----------------
249INSTALL_HDR_PATH 指定了执行 "make headers_*" 时，用户空间头文件的安装位置。
250
251默认值为::
252
253    $(objtree)/usr
254
255$(objtree) 是保存输出文件的目录。
256输出目录通常使用命令行中的 "O=..." 进行设置。
257
258该值可以被覆盖，在这种情况下将忽略默认值。
259
260INSTALL_DTBS_PATH
261-----------------
262INSTALL_DTBS_PATH 指定了设备树二进制文件的安装位置，通常由构建根（build roots）所需。
263它没有在 makefile 中定义，但如果需要，可以作为参数传递给 make。
264
265KBUILD_ABS_SRCTREE
266--------------------------------------------------
267Kbuild 在可能的情况下使用相对路径指向源代码树。例如，在源代码树中构建时，源代码树路径是
268'.'。
269
270设置该标志请求 Kbuild 使用源代码树的绝对路径。
271在某些情况下这是有用的，例如在生成带有绝对路径条目的标签文件时等。
272
273KBUILD_SIGN_PIN
274---------------
275当签署内核模块时，如果私钥需要密码或 PIN，此变量允许将密码或 PIN 传递给 sign-file 工具。
276
277KBUILD_MODPOST_WARN
278-------------------
279KBUILD_MODPOST_WARN 可以设置为在最终模块链接阶段出现未定义符号时避免错误。它将这些错误
280转为警告。
281
282KBUILD_MODPOST_NOFINAL
283----------------------
284KBUILD_MODPOST_NOFINAL 可以设置为跳过模块的最终链接。这仅在加速编译测试时有用。
285
286KBUILD_EXTRA_SYMBOLS
287--------------------
288用于依赖其他模块符号的模块。详见 modules.rst。
289
290ALLSOURCE_ARCHS
291---------------
292对于 tags/TAGS/cscope 目标，可以指定包含在数据库中的多个架构，用空格分隔。例如::
293
294    $ make ALLSOURCE_ARCHS="x86 mips arm" tags
295
296要获取所有可用架构，也可以指定 all。例如::
297
298    $ make ALLSOURCE_ARCHS=all tags
299
300IGNORE_DIRS
301-----------
302对于 tags/TAGS/cscope 目标，可以选择不包含在数据库中的目录，用空格分隔。例如::
303
304    $ make IGNORE_DIRS="drivers/gpu/drm/radeon tools" cscope
305
306KBUILD_BUILD_TIMESTAMP
307----------------------
308将该环境变量设置为日期字符串，可以覆盖在 UTS_VERSION 定义中使用的时间戳
309(运行内核时的 uname -v) 。该值必须是一个可以传递给 date -d 的字符串。例如::
310
311	$ KBUILD_BUILD_TIMESTAMP="Mon Oct 13 00:00:00 UTC 2025" make
312
313默认值是内核构建某个时刻的 date 命令输出。如果提供该时戳，它还用于任何 initramfs 归
314档文件中的 mtime 字段。 Initramfs mtimes 是 32 位的，因此早于 Unix 纪元 1970 年，或
315晚于协调世界时 (UTC) 2106 年 2 月 7 日 6 时 28 分 15 秒的日期是无效的。
316
317KBUILD_BUILD_USER, KBUILD_BUILD_HOST
318------------------------------------
319这两个变量允许覆盖启动时显示的 user@host 字符串以及 /proc/version 中的信息。
320默认值分别是 whoami 和 host 命令的输出。
321
322LLVM
323----
324如果该变量设置为 1，Kbuild 将使用 Clang 和 LLVM 工具，而不是 GCC 和 GNU
325binutils 来构建内核。