Skip to contentSkip to conversation

docs: sphinx-pre-install: improve dependency checks

PATCH In review Chen Miao 3 participants 12 messages Aug 14 – Aug 16

Subsystems (3)
lore
Share & tools
lore

Chen Miao

author
#0 lore raw

v4 cover docs: sphinx-pre-install: improve dependency checks

Hi all,

The Sphinx dependency checker currently does not provide useful installation guidance on macOS and only checks whether a make executable exists. This can leave macOS users without a clear setup path and allow an incompatible make implementation to pass the dependency check before the documentation build fails.

This series:

- documents the case-sensitive APFS volume needed for a kernel tree on macOS;
- adds macOS/Homebrew dependency handling, including command-line-only MacTeX support, required PDF font casks, and a PATH refresh hint;
- checks for GNU Make 4.0 or newer and honors an exported MAKE before preferring Homebrew gmake;
- teaches sphinx-build-wrapper to select a compatible GNU Make lazily for Info and Rust docs; and
- updates the zh_CN documentation in separate patches, including the APFS guidance in the contributor how-to.

Changes in v4:

- always pass LLVM=1 when invoking rustdoc, since Rust documentation requires LLVM even when the outer documentation build does not use it;

Thanks,
Chen Miao

Chen Miao (6):
docs: kdoc: add GNU Make detection
docs: sphinx-pre-install: add macOS Homebrew support
docs: sphinx-pre-install: check GNU Make version
docs: sphinx-build-wrapper: prefer gmake docs/zh_CN: doc-guide: document macOS Sphinx setup docs/zh_CN: how-to: document case-sensitive APFS setup

 Documentation/doc-guide/sphinx.rst            |  20 +++
 .../translations/zh_CN/doc-guide/sphinx.rst   |  17 ++-
 Documentation/translations/zh_CN/how-to.rst   |   8 ++
 tools/docs/sphinx-build-wrapper               |  20 ++-
 tools/docs/sphinx-pre-install                 | 120 +++++++++++++++++-
 tools/lib/python/kdoc/gmake_detect.py         |  62 +++++++++
 6 files changed, 238 insertions(+), 9 deletions(-)
 create mode 100644 tools/lib/python/kdoc/gmake_detect.py

base-commit: 8492d4e6bb7b9b1e78f2d17c4dda5272f25ec118

Signature · 1 line
2.50.1 (Apple Git-155)
author
#1 lore raw

PATCH v4 1/6 docs: kdoc: add GNU Make detection

The Sphinx dependency checker and build wrapper need to select a GNU Make executable that meets the minimum supported version. Keep the version parsing and command selection in a common module so both tools use identical behavior.

---
 tools/lib/python/kdoc/gmake_detect.py | 62 +++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 tools/lib/python/kdoc/gmake_detect.py
tools/lib/python/kdoc/gmake_detect.py new file +62 -0
new file mode 100644
index 000000000..5c0a28bc7
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) 2026 Chen Miao <[email protected]>
+
+"""Detect a supported GNU Make executable."""
+
+import re
+import shutil
+import subprocess
+import sys
+
+from kdoc.python_version import PythonVersion
+
+
+MIN_GMAKE_VERSION = PythonVersion("4.0").version
+
+
+def get_gmake_version(cmd):
+    """Return the GNU Make version for *cmd*, or ``None`` otherwise."""
+    if not cmd:
+        return None
+
+    kwargs = {}
+    if sys.version_info < (3, 7):
+        kwargs["universal_newlines"] = True
+    else:
+        kwargs["text"] = True
+
+    try:
+        result = subprocess.run(
+            [cmd, "--version"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+            **kwargs,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+
+    match = re.search(
+        r"^GNU Make\s+([0-9]+(?:\.[0-9]+)*)", result.stdout, re.MULTILINE
+    )
+    if not match:
+        return None
+
+    return PythonVersion.parse_version(match.group(1))
+
+
+def find_gmake(make=None):
+    """Return the first GNU Make 4.0+ from MAKE, gmake, or make."""
+    candidates = (
+        make,
+        shutil.which("gmake"),
+        shutil.which("make"),
+    )
+
+    for cmd in candidates:
+        version = get_gmake_version(cmd)
+        if version and version >= MIN_GMAKE_VERSION:
+            return cmd
+
+    return None
Signature · 1 line
2.50.1 (Apple Git-155)
author
#2 lore raw

PATCH v4 2/6 docs: sphinx-pre-install: add macOS Homebrew support

In reply to Chen Miao

The dependency checker currently reports an unknown distribution on macOS and cannot provide installation hints.

Detect macOS and include its product version in the status output. Use Homebrew for formula dependencies and install the command-line-only MacTeX cask without sudo. Only require Homebrew when dependencies need to be installed, install the DejaVu and Noto CJK fonts needed for PDF output, and explain how to refresh PATH after installing MacTeX.

Keep PyYAML in the virtualenv requirements because Homebrew does not provide a PyYAML formula. Check the module even on macOS: it is required by the parser_yaml extension regardless of how Sphinx is installed. When it is missing, direct users to the default virtualenv mode.

---
 Documentation/doc-guide/sphinx.rst |  18 +++++
 tools/docs/sphinx-pre-install      | 110 +++++++++++++++++++++++++++++
 2 files changed, 128 insertions(+)
Documentation/doc-guide/sphinx.rst +18 -0
index 51c370260..1e105542a 100644
@@ -131,6 +131,24 @@ It supports two optional parameters:
 ``--no-virtualenv``
 	Use OS packaging for Sphinx instead of Python virtual environment.
 
+macOS uses a case-insensitive APFS volume by default, but the kernel tree
+contains file names that differ only in case. Before cloning the tree, use
+``diskutil apfs list`` to find the APFS container identifier, replace
+``diskX`` below with that identifier, and create an additional case-sensitive
+volume with::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+On macOS, the script uses Homebrew for system dependencies. Homebrew
+commands are printed without ``sudo``. The PDF toolchain is provided by the
+``mactex-no-gui`` cask, while the required DejaVu and Noto CJK fonts are
+installed from Homebrew font casks; use ``--no-pdf`` when only building HTML
+documentation. After installing MacTeX, restart the terminal or run
+``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visible.
+The default virtualenv mode is recommended on macOS because PyYAML is
+installed from ``Documentation/sphinx/requirements.txt`` rather than from a
+Homebrew formula.
+
 Installing Sphinx Minimal Version
 ---------------------------------
 
tools/docs/sphinx-pre-install +110 -0

134 lines not on this page · raw message

Signature · 1 line
2.50.1 (Apple Git-155)
author
#3 lore raw

PATCH v4 3/6 docs: sphinx-pre-install: check GNU Make version

In reply to Chen Miao

The kernel documentation build requires GNU Make 4.0 or newer, but the Sphinx dependency checker only verifies that a make executable exists. This lets incompatible make implementations pass the check and fail later during the build.

Check the GNU Make version on all supported systems. Prefer a compatible gmake command, which is how Homebrew provides GNU Make on macOS, and fall back to make. Use the common kdoc detector so the dependency checker and build wrapper apply the same selection logic. Document the requirement and the macOS gmake invocation.

---
 Documentation/doc-guide/sphinx.rst |  4 +++-
 tools/docs/sphinx-pre-install      | 10 +++++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)
Documentation/doc-guide/sphinx.rst +3 -1
index 1e105542a..4fb716e77 100644
@@ -147,7 +147,9 @@ documentation. After installing MacTeX, restart the terminal or run
 ``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visible.
 The default virtualenv mode is recommended on macOS because PyYAML is
 installed from ``Documentation/sphinx/requirements.txt`` rather than from a
-Homebrew formula.
+Homebrew formula. The script also checks for GNU Make 4.0 or newer; when
+Homebrew provides it as ``gmake``, use ``gmake htmldocs`` instead of
+``make htmldocs``.
 
 Installing Sphinx Minimal Version
 ---------------------------------
tools/docs/sphinx-pre-install +9 -1
index 1956f1369..7625ac5a4 100755
@@ -37,6 +37,7 @@ import os.path
 src_dir = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, os.path.join(src_dir, '../lib/python'))
 from kdoc.python_version import PythonVersion
+from kdoc.gmake_detect import find_gmake
 
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
@@ -308,6 +309,13 @@ class MissingCheckers(AncillaryMethods):
 
         return None
 
+    def check_make(self):
+        """Check for GNU Make 4.0 or newer."""
+        if find_gmake(os.environ.get("MAKE")):
+            return
+
+        self.deps.add_package("make", DepManager.SYSTEM_MANDATORY)
+
     def check_perl_module(self, prog, dtype):
         """
         Does perl have a dependency? Is it available?
@@ -1559,7 +1567,7 @@ class SphinxDependencyChecker(MissingCheckers):
         # Check for needed programs/tools
         self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY)
 
-        self.check_program("make", DepManager.SYSTEM_MANDATORY)
+        self.check_make()
         self.check_program("which", DepManager.SYSTEM_MANDATORY)
 
         self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
Signature · 1 line
2.50.1 (Apple Git-155)
author
#4 lore raw

PATCH v4 4/6 docs: sphinx-build-wrapper: prefer gmake

In reply to Chen Miao

Homebrew installs GNU Make as gmake on macOS, but the Sphinx build wrapper invokes make directly when generating Info and Rust documentation. This can make the dependency check succeed while those documentation targets still use an incompatible make implementation.

Honor MAKE when it names a compatible GNU Make. Otherwise check gmake and then make, selecting the first GNU Make 4.0 or newer. Use the common kdoc detector to keep this selection consistent with sphinx-pre-install.

---
 tools/docs/sphinx-build-wrapper | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)
tools/docs/sphinx-build-wrapper +13 -7
index 1bb962202..994e5f7da 100755
@@ -63,6 +63,7 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
 from kdoc.python_version import PythonVersion
+from kdoc.gmake_detect import find_gmake
 from kdoc.latex_fonts import LatexFontChecker
 from jobserver import JobserverExec         # pylint: disable=C0413,C0411,E0401
 
@@ -97,6 +98,14 @@ class SphinxBuilder:
     with the Kernel.
     """
 
+    def get_make(self):
+        """Select the first GNU Make 4.0 or newer in preference order."""
+        make = find_gmake(self.env.get("MAKE"))
+        if make:
+            return make
+
+        sys.exit("GNU Make 4.0 or newer is required")
+
     def get_path(self, path, use_cwd=False, abs_path=False):
         """
         Ancillary routine to handle patches the right way, as shell does.
@@ -569,9 +578,10 @@ class SphinxBuilder:
         texinfo directory.
         """
 
+        make = self.get_make()
         for output_dir in output_dirs:
             try:
-                subprocess.run(["make", "info"], cwd=output_dir, check=True)
+                subprocess.run([make, "info"], cwd=output_dir, check=True)
             except subprocess.CalledProcessError as e:
                 sys.exit(f"Error generating info docs: {e}")
 
@@ -787,12 +797,8 @@ class SphinxBuilder:
 
         if rustdoc and target in ["htmldocs", "epubdocs"]:
             print("Building rust docs")
-            if "MAKE" in self.env:
-                cmd = [self.env["MAKE"]]
-            else:
-                cmd = ["make", "LLVM=1"]
-
-            cmd += [ "rustdoc"]
+            make = self.get_make()
+            cmd = [make, "LLVM=1", "rustdoc"]
             if self.verbose:
                 print(" ".join(cmd))
 
Signature · 1 line
2.50.1 (Apple Git-155)
author
#5 lore raw

PATCH v4 5/6 docs/zh_CN: doc-guide: document macOS Sphinx setup

In reply to Chen Miao

Translate the macOS Sphinx dependency setup added to the English documentation. Keep the translation in a separate patch so translation status tooling can track the source change correctly.

---
 .../translations/zh_CN/doc-guide/sphinx.rst     | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/translations/zh_CN/doc-guide/sphinx.rst +16 -1
index 3375c6f3a..e6d42d970 100644
@@ -110,6 +110,22 @@ PDF和LaTeX构建
 
 	使用Sphinx的系统打包,而不是Python虚拟环境。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符,
+将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+在 macOS 上,该脚本使用 Homebrew 安装系统依赖,输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供,所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装;如果只构建 HTML 文档,请使用 ``--no-pdf``。
+安装 MacTeX 后,请重新启动终端,或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境,因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为
+``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
+
 Sphinx构建
 ==========
 
@@ -409,4 +425,3 @@ Documentation/doc-guide/kernel-doc.rst 。
    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
    </svg>
-
Signature · 1 line
2.50.1 (Apple Git-155)
reviewer
#6 lore raw

Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup

Quoted 24 lines · Chen Miao

Translate the macOS Sphinx dependency setup added to the English documentation. Keep the translation in a separate patch so translation status tooling can track the source change correctly.

---
  .../translations/zh_CN/doc-guide/sphinx.rst     | 17 ++++++++++++++++-
  1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/translations/zh_CN/doc-guide/sphinx.rst +6 -0
index 3375c6f3a..e6d42d970 100644
@@ -110,6 +110,22 @@ PDF和LaTeX构建
 
  	使用Sphinx的系统打包,而不是Python虚拟环境。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符,
+将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+

Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 128

Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10 -0
+在 macOS 上,该脚本使用 Homebrew 安装系统依赖,输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供,所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装;如果只构建 HTML 文档,请使用 ``--no-pdf``。
+安装 MacTeX 后,请重新启动终端,或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境,因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为
+``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
+

Hi Chen Miao,

The zh_CN only keeps the translations, therefore, you should first put this part into the english documenation.

Of course, you can extend this patch into one with English and zh_CN changes.

Dongliang Mu

Quoted 8 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +0 -1
  Sphinx构建
  ==========
 
@@ -409,4 +425,3 @@ Documentation/doc-guide/kernel-doc.rst 。
     <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
     <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
     </svg>
-
#7 lore raw

Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup

Quoted 37 lines · Dongliang Mu
Quoted 22 lines · Chen Miao

Translate the macOS Sphinx dependency setup added to the English documentation. Keep the translation in a separate patch so translation status tooling can track the source change correctly.

---
  .../translations/zh_CN/doc-guide/sphinx.rst     | 17 ++++++++++++++++-
  1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/translations/zh_CN/doc-guide/sphinx.rst +6 -0
index 3375c6f3a..e6d42d970 100644
@@ -110,6 +110,22 @@ PDF和LaTeX构建
  	使用Sphinx的系统打包,而不是Python虚拟环境。
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符,
+将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+

Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126

Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10 -0
+在 macOS 上,该脚本使用 Homebrew 安装系统依赖,输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供,所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装;如果只构建 HTML 文档,请使用 ``--no-pdf``。
+安装 MacTeX 后,请重新启动终端,或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境,因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为
+``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
+

Hi Chen Miao,

Quoted 5 lines

The zh_CN only keeps the translations, therefore, you should first put this part into the english documenation.

Of course, you can extend this patch into one with English and zh_CN changes.

The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.

If so, let's add a 'Update xxx through...' in the commit message then.

But wait..:

+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。

Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.

Thanks.

reviewer
#8 lore raw

Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup

Quoted 36 lines · Weijie Yuan
Quoted 35 lines · Dongliang Mu
Quoted 22 lines · Chen Miao

Translate the macOS Sphinx dependency setup added to the English documentation. Keep the translation in a separate patch so translation status tooling can track the source change correctly.

---
   .../translations/zh_CN/doc-guide/sphinx.rst     | 17 ++++++++++++++++-
   1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/translations/zh_CN/doc-guide/sphinx.rst +6 -0
index 3375c6f3a..e6d42d970 100644
@@ -110,6 +110,22 @@ PDF和LaTeX构建
   	使用Sphinx的系统打包,而不是Python虚拟环境。
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符,
+将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+

Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126

Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10 -0
+在 macOS 上,该脚本使用 Homebrew 安装系统依赖,输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供,所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装;如果只构建 HTML 文档,请使用 ``--no-pdf``。
+安装 MacTeX 后,请重新启动终端,或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境,因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为
+``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
+

Hi Chen Miao,

Quoted 8 lines
Quoted 5 lines

The zh_CN only keeps the translations, therefore, you should first put this part into the english documenation.

Of course, you can extend this patch into one with English and zh_CN changes.

The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.

Oops, I missed this patch.

Yes, I mean, this patchset should only changes the English documentation. And then submit another patch to sync the zh_CN translation.

The changes to how-to.rst does not affect English documentation and I had commented with my reviewed-by tag.

Dongliang Mu

Quoted 2 lines

If so, let's add a 'Update xxx through...' in the commit message then.

Let us add another patch to keep the commit message and help us track translation status.

Quoted 9 lines

But wait..:

+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。

Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.

I think Chen Miao might miss it unintentionally since this change is in another patch.

Quoted 2 lines

Thanks.

#9 lore raw

Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup

Quoted 33 lines · Dongliang Mu
Quoted 24 lines
Quoted 24 lines
Quoted 12 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +6 -0
index 3375c6f3a..e6d42d970 100644
@@ -110,6 +110,22 @@ PDF和LaTeX构建
   	使用Sphinx的系统打包,而不是Python虚拟环境。
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符,
+将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+

Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126

Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10 -0
+在 macOS 上,该脚本使用 Homebrew 安装系统依赖,输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供,所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装;如果只构建 HTML 文档,请使用 ``--no-pdf``。
+安装 MacTeX 后,请重新启动终端,或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境,因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装,而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为
+``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
+

Hi Chen Miao,

Quoted 8 lines
Quoted 5 lines

The zh_CN only keeps the translations, therefore, you should first put this part into the english documenation.

Of course, you can extend this patch into one with English and zh_CN changes.

The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.

Quoted 7 lines

Oops, I missed this patch.

Yes, I mean, this patchset should only changes the English documentation. And then submit another patch to sync the zh_CN translation.

The changes to how-to.rst does not affect English documentation and I had commented with my reviewed-by tag.

OK, thanks!

Quoted 11 lines
Quoted 8 lines

But wait..:

+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。

Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.

I think Chen Miao might miss it unintentionally since this change is in another patch.

omg, I somehow missed the English original in [PATCH v4 3/6], too. Then it's my fault. Chen Miao merged two parts of changes for English Docs into one Chinese translation patch here. So he's right. I was just in a rush to send out the email and didn't take the time to double-check my question. Sorry for my recklessness.

Thanks!

author
#10 lore raw

PATCH v4 6/6 docs/zh_CN: how-to: document case-sensitive APFS setup

In reply to Chen Miao

The APFS volume used by macOS is case-insensitive by default, while the kernel tree contains file names that differ only in case. Document the diskutil commands needed to identify the APFS container and add a case-sensitive volume before cloning the tree.

---
 Documentation/translations/zh_CN/how-to.rst | 8 ++++++++
 1 file changed, 8 insertions(+)
Documentation/translations/zh_CN/how-to.rst +8 -0
index 9ec2384e1..e1d3d2b8b 100644
@@ -102,6 +102,14 @@ Linux 发行版和简单地使用 Linux 命令行,那么可以迅速开始了
 开头的命令。**请注意**,最新版本 Sphinx 的文档编译速度有极大提升,强烈建议
 您通过 pip/pypi 安装最新版本 Sphinx。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。在执行 ``git clone`` 前,可在现有 APFS 容器中创建一个额外的大小写
+敏感卷(先用 ``diskutil apfs list`` 找到容器标识符,并将下面的 ``diskX`` 替换为该标识符)::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+然后将内核源码克隆到新卷中。
+
 如果您处于一个多用户环境中,为了避免对其他人造成影响,建议您配置单用户
 sphinx 虚拟环境,即只需要执行::
 
Signature · 1 line
2.50.1 (Apple Git-155)
reviewer Reviewed-by on v4 6/6
#11 lore raw

Re: [PATCH v4 6/6] docs/zh_CN: how-to: document case-sensitive APFS setup

Quoted 7 lines · Chen Miao

The APFS volume used by macOS is case-insensitive by default, while the kernel tree contains file names that differ only in case. Document the diskutil commands needed to identify the APFS container and add a case-sensitive volume before cloning the tree.

BTW, this how-to file is only guidance for Chinese contributors. So there is no original English documentation and we don't need change the english documentation at the same time.

Dongliang Mu

Quoted 23 lines
---
  Documentation/translations/zh_CN/how-to.rst | 8 ++++++++
  1 file changed, 8 insertions(+)
Documentation/translations/zh_CN/how-to.rst +8 -0
index 9ec2384e1..e1d3d2b8b 100644
@@ -102,6 +102,14 @@ Linux 发行版和简单地使用 Linux 命令行,那么可以迅速开始了
  开头的命令。**请注意**,最新版本 Sphinx 的文档编译速度有极大提升,强烈建议
  您通过 pip/pypi 安装最新版本 Sphinx。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写
+不同的文件。在执行 ``git clone`` 前,可在现有 APFS 容器中创建一个额外的大小写
+敏感卷(先用 ``diskutil apfs list`` 找到容器标识符,并将下面的 ``diskX`` 替换为该标识符)::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+然后将内核源码克隆到新卷中。
+
  如果您处于一个多用户环境中,为了避免对其他人造成影响,建议您配置单用户
  sphinx 虚拟环境,即只需要执行::