* [PATCH 1/2] docs/zh_CN: add the translation of kbuild/kbuild.rst
[not found] <cover.1729259177.git.dzm91@hust.edu.cn>
@ 2024-10-18 13:47 ` Dongliang Mu
2024-10-18 13:47 ` [PATCH 2/2] docs/zh_CN: add the translations of kbuild/reproducible-builds.rst Dongliang Mu
1 sibling, 0 replies; 5+ messages in thread
From: Dongliang Mu @ 2024-10-18 13:47 UTC (permalink / raw)
To: si.yanteng, Alex Shi, Yanteng Si, Jonathan Corbet, Miguel Ojeda,
Alex Gaynor, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Alice Ryhl, Trevor Gross,
Nathan Chancellor, Nick Desaulniers, Bill Wendling, Justin Stitt,
Dongliang Mu
Cc: hust-os-kernel-patches, linux-doc, linux-kernel, rust-for-linux, llvm
Finish the translation of kbuild/kbuild.rst and move kbuild
from TODO to the main body.
Update to commit 2eb5d7f24299 ("kbuild: doc: describe the -C
option precisely for external module builds")
Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20241016131710.2619567-1-dzm91@hust.edu.cn
---
.../translations/zh_CN/kbuild/index.rst | 2 +-
.../translations/zh_CN/kbuild/kbuild.rst | 304 ++++++++++++++++++
2 files changed, 305 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/kbuild/kbuild.rst
diff --git a/Documentation/translations/zh_CN/kbuild/index.rst b/Documentation/translations/zh_CN/kbuild/index.rst
index e8eb448c1197..c06268cf44be 100644
--- a/Documentation/translations/zh_CN/kbuild/index.rst
+++ b/Documentation/translations/zh_CN/kbuild/index.rst
@@ -15,12 +15,12 @@
kconfig
headers_install
gcc-plugins
+ kbuild
TODO:
- kconfig-language
- kconfig-macro-language
-- kbuild
- makefiles
- modules
- issues
diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
new file mode 100644
index 000000000000..e5e2aebe1ebc
--- /dev/null
+++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
@@ -0,0 +1,304 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/kbuild/kbuild.rst
+:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
+
+======
+Kbuild
+======
+
+
+输出文件
+========
+
+modules.order
+-------------
+该文件记录模块在 Makefile 中出现的顺序。modprobe 使用该文件来确定性
+解析匹配多个模块的别名。
+
+modules.builtin
+---------------
+该文件列出了所有内置到内核中的模块。modprobe 使用该文件来避免尝试加载
+内置模块时出错。
+
+modules.builtin.modinfo
+-----------------------
+该文件包含所有内置模块的 modinfo。与单独模块的 modinfo 不同，所有字段
+都带有模块名称前缀。
+
+modules.builtin.ranges
+----------------------
+该文件包含所有内核内置模块的地址偏移范围（每个 ELF 节）。结合 System.map
+文件，它可以用来将模块名称与符号关联起来。
+
+环境变量
+========
+
+KCPPFLAGS
+---------
+在预处理时传递的额外选项。kbuild 进行所有预处理（包括构建 C 文件和汇编文件）
+时，都会使用这些预处理选项。
+
+KAFLAGS
+-------
+传递给汇编器的额外选项（适用于内置模块和外部模块）。
+
+AFLAGS_MODULE
+-------------
+外部模块的额外汇编选项。
+
+AFLAGS_KERNEL
+-------------
+内置模块的额外汇编选项。
+
+KCFLAGS
+-------
+传递给 C 编译器的额外选项（适用于内置模块和外部模块）。
+
+KRUSTFLAGS
+----------
+传递给 Rust 编译器的额外选项（适用于内置模块和外部模块）。
+
+CFLAGS_KERNEL
+-------------
+在编译内置代码时，传递给 $(CC) 的额外选项。
+
+CFLAGS_MODULE
+-------------
+编译外部模块时，传递给 $(CC) 的额外模块特定选项。
+
+RUSTFLAGS_KERNEL
+----------------
+在编译内置代码时，传递给 $(RUSTC) 的额外选项。
+
+RUSTFLAGS_MODULE
+----------------
+用于 $(RUSTC) 的额外模块特定选项。
+
+LDFLAGS_MODULE
+--------------
+用于 $(LD) 链接模块时的额外选项。
+
+HOSTCFLAGS
+----------
+在构建主机程序时传递给 $(HOSTCC) 的额外标志。
+
+HOSTCXXFLAGS
+------------
+在构建主机程序时传递给 $(HOSTCXX) 的额外标志。
+
+HOSTRUSTFLAGS
+-------------
+在构建主机程序时传递给 $(HOSTRUSTC) 的额外标志。
+
+HOSTLDFLAGS
+-----------
+链接主机程序时传递的额外选项。
+
+HOSTLDLIBS
+----------
+在构建主机程序时链接的额外库。
+
+.. _zh_cn_userkbuildflags:
+
+USERCFLAGS
+----------
+用于 $(CC) 编译用户程序（userprogs）时的额外选项。
+
+USERLDFLAGS
+-----------
+用于 $(LD) 链接用户程序时的额外选项。用户程序（userprogs）是使用 CC 链接的，
+因此 $(USERLDFLAGS) 应该根据需要包含 "-Wl," 前缀。
+
+KBUILD_KCONFIG
+--------------
+将顶级 Kconfig 文件设置为此环境变量的值。默认名称为 "Kconfig"。
+
+KBUILD_VERBOSE
+--------------
+设置 kbuild 的详细程度。可以分配与 "V=..." 相同的值。
+
+有关完整列表，请参见 `make help`。
+
+设置 "V=..." 优先于 KBUILD_VERBOSE。
+
+KBUILD_EXTMOD
+-------------
+在构建外部模块时设置内核源代码的搜索目录。
+
+设置 "M=..." 优先于 KBUILD_EXTMOD。
+
+KBUILD_OUTPUT
+-------------
+指定内核构建的输出目录。
+
+在单独的构建目录中为预构建内核构建外部模块时，这个变量也可以指向内核输出目录。请注意，
+这并不指定外部模块本身的输出目录。
+
+输出目录也可以使用 "O=..." 指定。
+
+设置 "O=..." 优先于 KBUILD_OUTPUT。
+
+KBUILD_EXTRA_WARN
+-----------------
+指定额外的构建检查。也可以通过在命令行传递 "W=..." 来设置相同的值。
+
+请参阅 `make help` 了解支持的值列表。
+
+设置 "W=..." 优先于 KBUILD_EXTRA_WARN。
+
+KBUILD_DEBARCH
+--------------
+对于 deb-pkg 目标，允许覆盖 deb-pkg 部署的正常启发式方法。通常 deb-pkg 尝试根据
+UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确的架构。KBUILD_DEBARCH
+的值假定（不检查）为有效的 Debian 架构。
+
+KDOCFLAGS
+---------
+指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
+scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
+
+ARCH
+----
+设置 ARCH 为要构建的架构。
+
+在大多数情况下，架构的名称与 arch/ 目录中的子目录名称相同。
+
+但某些架构（如 x86 和 sparc）有别名。
+
+- x86: i386 表示 32 位，x86_64 表示 64 位
+- parisc: parisc64 表示 64 位
+- sparc: sparc32 表示 32 位，sparc64 表示 64 位
+
+CROSS_COMPILE
+-------------
+指定 binutils 文件名的可选固定部分。CROSS_COMPILE 可以是文件名的一部分或完整路径。
+
+在某些设置中，CROSS_COMPILE 也用于 ccache。
+
+CF
+--
+用于 sparse 的额外选项。
+
+CF 通常在命令行中如下所示使用::
+
+ make CF=-Wbitwise C=2
+
+INSTALL_PATH
+------------
+INSTALL_PATH 指定放置更新后的内核和系统映像的路径。默认值是 /boot，但你可以设置
+为其他值。
+
+INSTALLKERNEL
+-------------
+使用 "make install" 时调用的安装脚本。
+默认名称是 "installkernel"。
+
+该脚本将会以以下参数调用：
+
+ - $1 - 内核版本
+ - $2 - 内核映像文件
+ - $3 - 内核映射文件
+ - $4 - 默认安装路径（如果为空，则使用根目录）
+
+"make install" 的实现是架构特定的，可能与上述有所不同。
+
+提供 INSTALLKERNEL 以便在交叉编译内核时可以指定自定义安装程序。
+
+MODLIB
+------
+指定模块的安装位置。
+默认值为::
+
+ $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
+
+该值可以被覆盖，在这种情况下将忽略默认值。
+
+INSTALL_MOD_PATH
+----------------
+INSTALL_MOD_PATH 指定了模块目录重定位时 MODLIB 的前缀，通常由构建根
+（build roots）所需。它没有在 makefile 中定义，但如果需要，可以作为
+参数传递给 make。
+
+INSTALL_MOD_STRIP
+-----------------
+如果 INSTALL_MOD_STRIP 被定义，内核模块在安装后会被剥离。如果
+INSTALL_MOD_STRIP 的值为 '1'，则会使用默认选项 --strip-debug。否则，
+INSTALL_MOD_STRIP 的值将作为 strip 命令的选项。
+
+INSTALL_HDR_PATH
+----------------
+INSTALL_HDR_PATH 指定了执行 "make headers_*" 时，用户空间头文件的安装位置。
+
+默认值为::
+
+ $(objtree)/usr
+
+$(objtree) 是保存输出文件的目录。
+输出目录通常使用命令行中的 "O=..." 进行设置。
+
+该值可以被覆盖，在这种情况下将忽略默认值。
+
+INSTALL_DTBS_PATH
+-----------------
+INSTALL_DTBS_PATH 指定了设备树二进制文件的安装位置，通常由构建根（build roots）所需。
+它没有在 makefile 中定义，但如果需要，可以作为参数传递给 make。
+
+KBUILD_ABS_SRCTREE
+--------------------------------------------------
+Kbuild 在可能的情况下使用相对路径指向源代码树。例如，在源代码树中构建时，源代码树路径是
+'.'。
+
+设置该标志请求 Kbuild 使用源代码树的绝对路径。
+在某些情况下这是有用的，例如在生成带有绝对路径条目的标签文件时等。
+
+KBUILD_SIGN_PIN
+---------------
+当签署内核模块时，如果私钥需要密码或 PIN，此变量允许将密码或 PIN 传递给 sign-file 工具。
+
+KBUILD_MODPOST_WARN
+-------------------
+KBUILD_MODPOST_WARN 可以设置为在最终模块链接阶段出现未定义符号时避免错误。它将这些错误
+转为警告。
+
+KBUILD_MODPOST_NOFINAL
+----------------------
+KBUILD_MODPOST_NOFINAL 可以设置为跳过模块的最终链接。这仅在加速编译测试时有用。
+
+KBUILD_EXTRA_SYMBOLS
+--------------------
+用于依赖其他模块符号的模块。详见 modules.rst。
+
+ALLSOURCE_ARCHS
+---------------
+对于 tags/TAGS/cscope 目标，可以指定包含在数据库中的多个架构，用空格分隔。例如::
+
+ $ make ALLSOURCE_ARCHS="x86 mips arm" tags
+
+要获取所有可用架构，也可以指定 all。例如::
+
+ $ make ALLSOURCE_ARCHS=all tags
+
+IGNORE_DIRS
+-----------
+对于 tags/TAGS/cscope 目标，可以选择不包含在数据库中的目录，用空格分隔。例如::
+
+ $ make IGNORE_DIRS="drivers/gpu/drm/radeon tools" cscope
+
+KBUILD_BUILD_TIMESTAMP
+----------------------
+将该环境变量设置为日期字符串，可以覆盖在 UTS_VERSION 定义中使用的时间戳
+（运行内核时的 uname -v）。该值必须是一个可以传递给 date -d 的字符串。默认值是
+内核构建某个时刻的 date 命令输出。
+
+KBUILD_BUILD_USER, KBUILD_BUILD_HOST
+------------------------------------
+这两个变量允许覆盖启动时显示的 user@host 字符串以及 /proc/version 中的信息。
+默认值分别是 whoami 和 host 命令的输出。
+
+LLVM
+----
+如果该变量设置为 1，Kbuild 将使用 Clang 和 LLVM 工具，而不是 GCC 和 GNU
+binutils 来构建内核。
--
2.43.0
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH 2/2] docs/zh_CN: add the translations of kbuild/reproducible-builds.rst
[not found] <cover.1729259177.git.dzm91@hust.edu.cn>
2024-10-18 13:47 ` [PATCH 1/2] docs/zh_CN: add the translation of kbuild/kbuild.rst Dongliang Mu
@ 2024-10-18 13:47 ` Dongliang Mu
2024-10-21 5:20 ` Yanteng Si
2024-10-21 15:30 ` Jonathan Corbet
1 sibling, 2 replies; 5+ messages in thread
From: Dongliang Mu @ 2024-10-18 13:47 UTC (permalink / raw)
To: si.yanteng, Alex Shi, Yanteng Si, Jonathan Corbet, Dongliang Mu
Cc: hust-os-kernel-patches, linux-doc, linux-kernel
Finish the translation of kbuild/reproducible-builds.rst and move
reproducible-builds.rst from TODO to the main body.
Update to commit 114ff6fe6cfb ("Documentation: kbuild: Add description
of git for reproducible builds")
Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
---
.../translations/zh_CN/kbuild/index.rst | 2 +-
.../zh_CN/kbuild/reproducible-builds.rst | 114 ++++++++++++++++++
2 files changed, 115 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/kbuild/reproducible-builds.rst
diff --git a/Documentation/translations/zh_CN/kbuild/index.rst b/Documentation/translations/zh_CN/kbuild/index.rst
index c06268cf44be..0ba96aecb13a 100644
--- a/Documentation/translations/zh_CN/kbuild/index.rst
+++ b/Documentation/translations/zh_CN/kbuild/index.rst
@@ -16,6 +16,7 @@
headers_install
gcc-plugins
kbuild
+ reproducible-builds
TODO:
@@ -24,7 +25,6 @@ TODO:
- makefiles
- modules
- issues
-- reproducible-builds
- llvm
.. only:: subproject and html
diff --git a/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst b/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst
new file mode 100644
index 000000000000..5f27ebf2fbfc
--- /dev/null
+++ b/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst
@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/kbuild/reproducible-builds.rst
+
+:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
+
+============
+可重现的构建
+============
+
+通常希望使用相同工具集构建相同源代码是可重现的，即，输出始终完全相同。这使得能够验证
+二进制分发或嵌入式系统的构建基础设施未被篡改。这样也更容易验证源代码或工具的更改不会
+影响最终生成的二进制文件。
+
+`可重现构建项目`_ 提供了有关该主题的更多信息。本文档涵盖了构建内核可能不可重现的
+各种原因，以及如何避免这些问题。
+
+时间戳
+------
+
+内核在三个地方嵌入时间戳：
+
+* 通过 ``uname()`` 显示与包含在 ``/proc/version`` 中的版本字符串
+
+* initramfs 中的文件时间戳
+
+* 如果启动 ``CONFIG_IKHEADERS``，内核或相应模块中嵌入的内核头文件的时间戳，
+ 通过 ``/sys/kernel/kheaders.tar.xz`` 显示
+
+默认情况下，时间戳为当前时间或内核头文件的修改时间。这个内容必须使用
+`KBUILD_BUILD_TIMESTAMP`_ 变量进行覆盖。如果你从某个 git 提交进行构建，
+可以使用其提交日期。
+
+内核 *不* 使用 ``__DATE__`` 和 ``__TIME__`` 宏，并在使用这些宏时启用警告。
+如果你合并的外部代码使用这些宏，则必须通过设置 `SOURCE_DATE_EPOCH`_ 环境
+变量来覆盖它们对应的时间戳。
+
+用户，主机
+----------
+
+内核在 ``/proc/version`` 中嵌入构建用户和主机名。必须使用
+`KBUILD_BUILD_USER 和 KBUILD_BUILD_HOST`_ 变量来覆盖这些设置。如果
+您从某个 git 提交进行构建，可以使用其提交者地址。
+
+绝对文件名
+----------
+
+当内核在树外构建时，调试信息可能包括源文件的绝对文件名。这些信息必须通过在
+`KCFLAGS`_ 变量中包含 ``-fdebug-prefix-map`` 选项来覆盖。
+
+根据使用的编译器，``__FILE__`` 宏在树外构建中也可能扩展为绝对文件名。Kbuild
+自动使用 ``-fmacro-prefix-map`` 选项来防止这种情况，前提是它被支持。
+
+可重现构建网站提供了有关这些 `prefix-map 选项`_ 的更多信息。
+
+在源包中的生成文件
+------------------
+
+在 ``tools/`` 子目录下，一些程序的构建过程并不完全支持树外构建。这可能导致后续
+使用如 ``make rpm-pkg`` 构建的源码包包含生成的文件。在构建源码包之前，您应该通过
+运行 ``make mrproper`` 或 ``git clean -d -f -x`` 来确保源码树是干净的。
+
+模块签名
+--------
+
+如果你启用 ``CONFIG_MODULE_SIG_ALL``，默认行为是为每次构建生成不同的临时密钥，
+从而导致模块不可重现。然而，将签名密钥包含在源代码中显然会违背签名模块的目的。
+
+一种方法是将构建过程分为几个部分，以便不可重现的部分可以作为源处理：
+
+1. 生成一个持久的签名密钥。将该密钥的证书添加到内核源代码中。
+
+2. 将 ``CONFIG_SYSTEM_TRUSTED_KEYS`` 符号设置为包括签名密钥的证书，将
+``CONFIG_MODULE_SIG_KEY`` 设置为空字符串，并禁用 ``CONFIG_MODULE_SIG_ALL``。
+最后，构建内核和模块。
+
+3. 为模块创建分离的签名，并将它们作为源发布。
+
+4. 附加模块签名并进行第二次构建。这可以重建模块，或使用步骤 2 的输出。
+
+结构随机化
+----------
+
+如果你启用 ``CONFIG_RANDSTRUCT``，则需要在 ``scripts/basic/randstruct.seed``
+中预生成随机种子，以便每次构建都使用相同的值。有关详细信息，请参见
+``scripts/gen-randstruct-seed.sh``。
+
+调试信息冲突
+------------
+
+这并非是个不可重现性的问题，而是生成的文件 *过于* 可重现的问题。
+
+一旦你设置了所有必要的变量来开展可重现构建，vDSO 的调试信息可能即使对于不同的内核版
+本也是相同的。这会导致不同内核版本的调试信息软件包之间发生文件冲突。
+
+为了避免这种情况，你可以通过在 vDSO 中包含一个任意的 salt 字符串，使其对于不同的
+内核版本是不同的。这种机制由 Kconfig 符号 ``CONFIG_BUILD_SALT`` 指定。
+
+Git
+---
+
+未提交的更改或 Git 中的不同提交 ID 也可能导致不同的编译结果。例如，在执行
+``git reset HEAD^`` 后，即使代码相同，编译期间生成的
+``include/config/kernel.release`` 也会不同，导致最终生成的二进制文件也不尽相同。
+有关详细信息，请参见 ``scripts/setlocalversion``。
+
+.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
+.. _KBUILD_BUILD_USER 和 KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
+.. _KCFLAGS: kbuild.html#kcflags
+.. _prefix-map 选项: https://reproducible-builds.org/docs/build-path/
+.. _可重现构建项目: https://reproducible-builds.org/
+.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
--
2.43.0
^ permalink raw reply [flat|nested] 5+ messages in thread