From nobody Tue Sep 29 08:25:35 2026 Received: from mail-pj1-f47.google.com (mail-pj1-f47.google.com [209.85.216.47]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 809CC3F54B6 for ; Mon, 10 Aug 2026 14:33:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.47 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372406; cv=none; b=SNcr7vgmRBA1ozSz4PubxUeWwTUZSMNZgwkWx9QW5gdknhtiYVQuclzXQftSrIHnpZUX9cBf53mlvkKGRtjlQlyvzLZ2/GI9P9Q6nQcB372wsHglpUFK+zlOr/G8b2cbSnz149WMWJg6B0Ly8GWsSAmdKakhnJOEOImeHsa5auI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372406; c=relaxed/simple; bh=6/wSjlMr/KNyZmqRuyV2PMhBMKI664SqeBp2S7tEdu4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=SLqtaPSr53Yg64+Hh8XWwHTGkfFyOLo3AJjE8smYwL494kWtW2dBn/cjDRinjLmUsdFIhw+U8S6D1wB3oWVTutvgUDXc3jORMJdhCRZ/yQgMc21rzLnzW8KOkXCkm6mX2/+jyrHWG5oCOmJmklIqRXZoexH67mCRjlroWCCTmXw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=jHznw/yg; arc=none smtp.client-ip=209.85.216.47 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="jHznw/yg" Received: by mail-pj1-f47.google.com with SMTP id 98e67ed59e1d1-3856d6fbcb3so1823772a91.2 for ; Mon, 10 Aug 2026 07:33:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786372404; x=1786977204; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=8GPUA3qfNyS6NHODtebpstn+B5QpoZwQkRGKMZKYxpg=; b=jHznw/ygG7pQZDmaQ6Q+fHZkUyw5ZNQt2cGblzBViaRe3sx8szKYaV6llf6IfwpVjn V5fhvKTPS4MqDmRoCrFURJvbSEFtFDcwSEauvmO2V+sTzoIUWmmakWjCuojxn4I9VwRZ 4StAaUZkqo195clBF0V6ytnKmjcEe1Wy7OzXhPWXIVsIxYuCljt5/vnV1SBIxAqPxUVT rPEv5fFyJoE2igyQm2wj7CMzaYI4iBWqwgOTL1nxnmwXRIltSyJVAB2LXKeI2RjzgOST YodIRtEzY6yZ68YsIWdsMGSdcfE6r3xHSUnREUSkFYdQls/maq7Ypmfwzj8jad4tkhMU Avlw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786372404; x=1786977204; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=8GPUA3qfNyS6NHODtebpstn+B5QpoZwQkRGKMZKYxpg=; b=YiNjxlx/9rMrSs530/jl8OLztEHGgq/dstzN8CKQlv+Zmjqr+j+Jeg5T4+VNqFd5JS ODbpklaqRAmDP4pifVSaUYwiY2DF9lV/UqY1SSvxz/fBjz44qDklHZjI+BCkWNSzWNyZ pZ0OUuxkzbLhnpQxzbW5bg2ORc013X56NsWlPM8WQU3ML/cn1qaWBMY3qThLP22eY9WW Idy1tSDTMk0eWYy3bbC6bHdz5pZDedQk/H9FaQ8Ldg9rLeR8t6dC08ugpsF9yaEJc/hx seW1TwQFhzEDwiIU8zIh7h7sjYu0XgQ5vqbefYbjc2jRVrhq98CMFisXdbFKOxLVt7sp 8ymg== X-Forwarded-Encrypted: i=1; AHgh+RpPoR1Engzwd8SqqZ8hA5WMladwn+R+EXG+d4tP86kjFdKoGUlCyHsEDBKiM7SipuFz9e6FaGdWN4ppXxc=@vger.kernel.org X-Gm-Message-State: AOJu0YwqTQ2nY9wIFbl+/VTpQvHkyYKpxJSQmy07/6xvVLygTMu0syXj qb1Dk1xNVJbWN6CtjB0JLi3cs+S0sdNig8BBLeRYOqsl3xA3wUd7jc/z X-Gm-Gg: AR+sD11a1qQP9v0tL09iOmGfuJ6UouyJ/gRZO5qjtjrleuIHdaAwJmqm3qYLKZg9Uy3 k64M8d7/dWbZ9lg/9Vg1mAkRNZNcDGDe+pLfLmd6+B91VZLQLW4Ss4Yn38aK/ZyROr3IdSI/ser bXqqe+p+LIC6TNpQBzUjjsTy/pW41jF/bshbA0jJnNuaJhwsvswHC3pPtpF9Zv09Zdx8mjFiRhU R57AffJp/vWaf/f4W/oQ1wrm85RFqum7qhLD71a6+vur3Ptjqw3fo5XNEAGCdoRXE2697fjdhEg 63Agp6OyI7smoaMX7f55ICUd0Be9FOe3lkYqq9GsM8En6CreHHzMplxFAwvi33jvcu3kzTQqEkQ SPxn7xiVqBCGsXMw7y5sYmQFiySE0zsa976oFwOBUOOXPZAQ+cPiDWxa1BFK7BNlHxqveDE5dBD wxd8IBF8W9iq/z2S2upKRf2oVRtVIw0c75UGmLVeWdUnLLDlWvl8BInW8f/8T0+nZiCQ5cFxeWJ 08= X-Received: by 2002:a17:90b:390e:b0:38e:9ef9:eb97 with SMTP id 98e67ed59e1d1-392823ea541mr19035970a91.16.1786372403647; Mon, 10 Aug 2026 07:33:23 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1410cc132c1sm22197001c88.8.2026.08.10.07.33.21 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Mon, 10 Aug 2026 07:33:23 -0700 (PDT) From: Chen Miao To: corbet@lwn.net, alexs@kernel.org, si.yanteng@linux.dev, skhan@linuxfoundation.org, dzm91@hust.edu.cn, mchehab@kernel.org, wy@wyuan.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v2 1/5] docs: sphinx-pre-install: add macOS Homebrew support Date: Mon, 10 Aug 2026 22:33:05 +0800 Message-ID: <20260810143311.57775-2-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260810143311.57775-1-chenmiao.ku@gmail.com> References: <20260810143311.57775-1-chenmiao.ku@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 actually 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 virtual environment requirements because Homebrew does not provide a PyYAML formula. Document the macOS setup, the --no-pdf option, and how to create a case-sensitive APFS volume before cloning the kernel tree. Signed-off-by: Chen Miao --- Documentation/doc-guide/sphinx.rst | 18 +++++ tools/docs/sphinx-pre-install | 113 ++++++++++++++++++++++++++++- 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 51c370260..1e105542a 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -131,6 +131,24 @@ It supports two optional parameters: ``--no-virtualenv`` Use OS packaging for Sphinx instead of Python virtual environment. =20 +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-sensit= ive +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 HT= ML +documentation. After installing MacTeX, restart the terminal or run +``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visib= le. +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 --------------------------------- =20 diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install index 965c9b093..1b9d77ec3 100755 --- a/tools/docs/sphinx-pre-install +++ b/tools/docs/sphinx-pre-install @@ -518,6 +518,24 @@ class MissingCheckers(AncillaryMethods): a decent coverage. """ =20 + if sys.platform =3D=3D "darwin": + sw_vers =3D self.which("sw_vers") + if sw_vers: + try: + result =3D self.run( + [sw_vers, "-productVersion"], + capture_output=3DTrue, + text=3DTrue, + check=3DTrue, + ) + version =3D result.stdout.strip() + if version: + return f"macOS {version}" + except (subprocess.CalledProcessError, FileNotFoundError): + pass + + return "macOS" + system_release =3D "" =20 if self.which("lsb_release"): @@ -716,6 +734,93 @@ class SphinxDependencyChecker(MissingCheckers): =20 return self.get_install_progs(progs, "apt-get install") =20 + def give_macos_hints(self): + """Provide package installation hints for macOS using Homebrew.""" + progs =3D { + "Pod::Usage": "perl", + "convert": "imagemagick", + "dot": "graphviz", + "ensurepip": "python", + "python-sphinx": "sphinx-doc", + "rsvg-convert": "librsvg", + "xelatex": "mactex-no-gui", + "latexmk": "mactex-no-gui", + } + + if self.pdf: + font_dirs =3D [ + os.path.expanduser("~/Library/Fonts"), + "/Library/Fonts", + "/System/Library/Fonts", + ] + pdf_fonts =3D { + "font-dejavu": ["DejaVuSans.ttf"], + "font-noto-sans-cjk": ["NotoSansCJK.ttc"], + } + + for package, names in pdf_fonts.items(): + files =3D [ + os.path.join(font_dir, name) + for font_dir in font_dirs + for name in names + ] + self.check_missing_file(files, package, DepManager.PDF_MAN= DATORY) + + install =3D self.deps.check_missing(progs) + + if self.verbose_warn_install: + self.deps.warn_install() + + if not install: + return None + + formulae =3D set() + casks =3D set() + notes =3D [] + for package in install.split(): + if package =3D=3D "yaml": + notes.append( + "PyYAML is not provided as a Homebrew formula. Use the= " + "default virtualenv mode so it is installed from " + "Documentation/sphinx/requirements.txt." + ) + continue + + if package =3D=3D "mactex-no-gui" or package.startswith("font-= "): + casks.add(package) + else: + formulae.add(package) + + commands =3D [] + if formulae: + commands.append("\tbrew install " + " ".join(sorted(formulae))) + if casks: + commands.append("\tbrew install --cask " + " ".join(sorted(cas= ks))) + + if not commands: + self.distro_msg =3D "\n".join(notes) + return None + + if not self.which("brew"): + notes.append( + "Homebrew is needed to install the missing dependencies. " + "Install it from https://brew.sh/ and re-run this script." + ) + self.distro_msg =3D "\n".join(notes) + return None + + if "mactex-no-gui" in casks: + notes.append( + "After installing MacTeX, restart the terminal or run:\n" + "\teval \"$(/usr/libexec/path_helper)\"\n" + "before re-running this script." + ) + + if notes: + self.distro_msg =3D "\n".join(notes) + + return "\nYou should run:\n" + "\n".join(commands) + def give_redhat_hints(self): """ Provide package installation hints for RedHat-based distros @@ -1138,6 +1243,8 @@ class SphinxDependencyChecker(MissingCheckers): re.compile("Kali"): self.give_debian_hin= ts, re.compile("Mint"): self.give_debian_hin= ts, =20 + re.compile("macOS"): self.give_macos_hint= s, + re.compile("openSUSE"): self.give_opensuse_h= ints, =20 re.compile("Mageia"): self.give_mageia_hin= ts, @@ -1458,7 +1565,11 @@ class SphinxDependencyChecker(MissingCheckers): self.check_program("dot", DepManager.SYSTEM_OPTIONAL) self.check_program("convert", DepManager.SYSTEM_OPTIONAL) =20 - self.check_python_module("yaml") + # PyYAML is installed from Documentation/sphinx/requirements.txt in + # the virtualenv recommended on macOS. Homebrew does not provide a + # PyYAML formula, so do not ask for a nonexistent brew package her= e. + if not (sys.platform =3D=3D "darwin" and self.virtualenv and self.= need_pip): + self.check_python_module("yaml") =20 if self.pdf: self.check_program("xelatex", DepManager.PDF_MANDATORY) --=20 2.50.1 (Apple Git-155) From nobody Tue Sep 29 08:25:35 2026 Received: from mail-pj1-f45.google.com (mail-pj1-f45.google.com [209.85.216.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 46EDE3E0C4C for ; Mon, 10 Aug 2026 14:33:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.45 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372408; cv=none; b=nT+LmF4pNpz+1CYidPu4GIynAj5Q5OotiV8+loDTEUrvhPX11OASIzXRqWQHuPFo7zsGn4dN5Y/+8OlvUclG84dmJTRpCSd1dr/rg7kX6872FS7a0lFk8YbD2uwvp6x4y6Ru8HIEdNZVSjUwKC9OpEBejxogDNRLE5p6fB38VxQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372408; c=relaxed/simple; bh=SkWJziYAltGYw0TJ8LmA/O3aXe/nbpzfJr3gzN3OpRc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rAIA4cgdCMol/GuxlrCbmKoaCksNLble6v6Rlxkt16bj3sb3WZFk+lVdbdGVQBkC4a5LU4A7Hzty0aQQ0GA4hPnb6zmFXDajKexL2XzFfHnf3cOQ8sF1PZnpNO/2Fuu9ENfb1wPwHL+DOj2WzByc+DyedffeXcSbR18d3AZt/hU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=GNSaq1mL; arc=none smtp.client-ip=209.85.216.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="GNSaq1mL" Received: by mail-pj1-f45.google.com with SMTP id 98e67ed59e1d1-38f620399a0so1674908a91.2 for ; Mon, 10 Aug 2026 07:33:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786372406; x=1786977206; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=3eGPyLBs9QZ3Nwm6ypDb5+mFyEwjns3mEiwXdV8ptF0=; b=GNSaq1mLmI2ROmYXZ/l5mgBpfoPgjNKryi35qJsNK5bTr26ACuah7ZUoDMGEWKWs4Q NLINFVRSM8twcHEk8VlF6IhMFbAZHs+dKcAftF2ay2ahKi8G/IH3fCDYQk3wbwvv7iMW aJ4m+q3vYR8MX50BG/euYuGxEH+P2HiVyXdsvfyVSGCKmZqae3anu38hU4xMuCqSP0Te cAqklaQNJFXVl8GqOHC1MCfkjlQ/JaI3XsJb/fPamwfBHdmW90jc2Z41fEV2EWdtsphc qVrRIbwDB/ec6YMFfmdgKQqXkZ8BNSfCrCl2Q70XQruwA9r4x+k2rxadwqc2zj5jHsy/ CHKA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786372407; x=1786977207; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=3eGPyLBs9QZ3Nwm6ypDb5+mFyEwjns3mEiwXdV8ptF0=; b=em9R8HIzvPaD+PXWJAa8myQ9paXIt3G8J11SKrsLIsRuc921FgCOIDq0GDBiAVATjV Ju5YqH5unqErE1Tvw+b+fUS9QUhWktf1nmgKNx6ZZumQysv5ZkwMzECLJ2AjVNVB8NFt j7NrmveWJ63MveKIskBjghy/syrjoyPNiEb5wZ2DceuHdGYrfcd83FySh5aKVMuHpzh7 L8zb+7pJ2NCksuO99BPdNBYaUd7+qE2bv2qJ7tVOT91vKhDbfnqanLnDW1KaOfMVRgRn nMH2ld/G+rra98Ud5ngLlgbKTvU2NNEjzmfeYMfeWjD9kLYU/PwjfX2VYrrJ7eWSKEcI Z4Hw== X-Forwarded-Encrypted: i=1; AHgh+Ro2WZ21qolmuW+n7oIffzF0GfhSuMSwaGLJM+vcDWMpGwoAHYD43mIRNorEw8Y4pDq+Egenl2OHYviRY5Q=@vger.kernel.org X-Gm-Message-State: AOJu0YwS9co/d/2o24iwjndLKM0r+Ag1LCiLx186MVoi3nxA/8tz+frK fGhGuwU0B0hhsaUSlLtmH7sDqw9fIfixiMGlMvwIht7bZ+b3SxLDA5Cc0+FNeDxp X-Gm-Gg: AR+sD11pGuY2mP9SzeghvvOATvLTIqhh+i4cbqIQ0//Z+QOw8TJ06fMx8swXA7F4Shp liKE/EVG40NMpoS/nT8EUMXnMypjfcoM1KLFCA5ldg/aOEeej/QSoDVmIqm83W4xcyfD0a/z/zs 1Xc+cRTbD5awFLmF4fZazoFLvoyJVCz31BmJrYyGvOBG6t3Js1MEtNjULYatZ8+qdU3OPPQw44T gb2i4jUM+pPGt9AIm7rkLg8LtdA1PQKDaz6waOgLITolyQfZKl5mWiwrOPwC2dnRV22JtCpKrhd dwsHmbyT3vfGI/nQLdHr7IZ8LCtgo5GlqLR381n7wi9gco4AdbuNgWD4U3kuhzPySN9h0psQlHu VDHiC+1d8g4pWRXIIRZtwREpi4rvMls0kFbzIelN1441Tle9okRX/6UjyfXJ6871RMeEczqqcdq 9bGqLtmX8O+jJ4y54ZSr8t/t15qidKTnRRkPhWbyOEYS8Sx5LJpRR2w1iJ99T93OCS7O4fpbZH2 J4= X-Received: by 2002:a17:90b:3bcb:b0:392:c868:35af with SMTP id 98e67ed59e1d1-392c8683878mr3727898a91.20.1786372406427; Mon, 10 Aug 2026 07:33:26 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1410cc132c1sm22197001c88.8.2026.08.10.07.33.24 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Mon, 10 Aug 2026 07:33:26 -0700 (PDT) From: Chen Miao To: corbet@lwn.net, alexs@kernel.org, si.yanteng@linux.dev, skhan@linuxfoundation.org, dzm91@hust.edu.cn, mchehab@kernel.org, wy@wyuan.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v2 2/5] docs: sphinx-pre-install: check GNU Make version Date: Mon, 10 Aug 2026 22:33:06 +0800 Message-ID: <20260810143311.57775-3-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260810143311.57775-1-chenmiao.ku@gmail.com> References: <20260810143311.57775-1-chenmiao.ku@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Document the requirement and the macOS gmake invocation. Signed-off-by: Chen Miao Reviewed-by: Mauro Carvalho Chehab --- Documentation/doc-guide/sphinx.rst | 4 ++- tools/docs/sphinx-pre-install | 41 +++++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 1e105542a..4fb716e77 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -147,7 +147,9 @@ documentation. After installing MacTeX, restart the ter= minal or run ``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visib= le. 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``. =20 Installing Sphinx Minimal Version --------------------------------- diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install index 1b9d77ec3..54f36c3b8 100755 --- a/tools/docs/sphinx-pre-install +++ b/tools/docs/sphinx-pre-install @@ -40,6 +40,7 @@ from kdoc.python_version import PythonVersion =20 RECOMMENDED_VERSION =3D PythonVersion("3.4.3").version MIN_PYTHON_VERSION =3D PythonVersion("3.7").version +MIN_MAKE_VERSION =3D PythonVersion("4.0").version =20 =20 class DepManager: @@ -308,6 +309,44 @@ class MissingCheckers(AncillaryMethods): =20 return None =20 + def get_make_version(self, cmd): + """Get the GNU Make version, or None if cmd is not GNU Make.""" + if not cmd: + return None + + try: + result =3D self.run( + [cmd, "--version"], + capture_output=3DTrue, + text=3DTrue, + check=3DTrue, + ) + except (OSError, subprocess.CalledProcessError): + return None + + match =3D re.search( + r"^GNU Make\s+([0-9]+(?:\.[0-9]+)*)", result.stdout, re.MULTIL= INE + ) + if not match: + return None + + return PythonVersion.parse_version(match.group(1)) + + def check_make(self): + """Check for GNU Make 4.0 or newer.""" + candidates =3D ( + os.environ.get("MAKE"), + self.which("gmake"), + self.which("make"), + ) + + for make in candidates: + version =3D self.get_make_version(make) + if version and version >=3D MIN_MAKE_VERSION: + 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 +1598,7 @@ class SphinxDependencyChecker(MissingCheckers): # Check for needed programs/tools self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY) =20 - self.check_program("make", DepManager.SYSTEM_MANDATORY) + self.check_make() self.check_program("which", DepManager.SYSTEM_MANDATORY) =20 self.check_program("dot", DepManager.SYSTEM_OPTIONAL) --=20 2.50.1 (Apple Git-155) From nobody Tue Sep 29 08:25:35 2026 Received: from mail-pg1-f179.google.com (mail-pg1-f179.google.com [209.85.215.179]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id F266F3F86E0 for ; Mon, 10 Aug 2026 14:33:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.179 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372411; cv=none; b=u/ZWjiGw28LEXfpz6jQnZfcS4xRKH25ZdcWtjy1TfMfC3Fbb1wdV203iatM7ELmVcoUp3P1nC+LAUGrQqDwkGvUNoSm6sZhqgZYLmAkKjPChhfih2lVW39fwPjt43oOv0Nl9beAax7JbJxDemVbpaw+qyRwn0WPXSdT1E+D5GpU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372411; c=relaxed/simple; bh=64TB55FHYFwfaYz9gCVrUPYWAOUkrsbqFhpR+gClBKM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=j2C/Ihm+z0oIWIYCTw/MM7aBSPalE8gc9rpqasJkJVLMY+JfZ0j9j2hS/UcBFu5AoFG/C+iej2UfeGF29NMWmBok9vjOLJK/RrjxTkTFezKqLJL+KPR2HCtSoCeIK/sj1Rqj8/Wk1zub+x7qYYTny6PnE+DxPCrxrsRdNhRy0Vw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=LzQvdwry; arc=none smtp.client-ip=209.85.215.179 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="LzQvdwry" Received: by mail-pg1-f179.google.com with SMTP id 41be03b00d2f7-cb5b8572b70so2174225a12.2 for ; Mon, 10 Aug 2026 07:33:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786372409; x=1786977209; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=mW6857ZUCKMxTWq8NsQePygvrLZZIX0lwqlDz2Pl/S8=; b=LzQvdwryqh/oRypoaAwf9nrotr1vFHaayuFEFk9n1CSCYkXdkCPJClrUF4SP0mU1dF KJOHdYwM5ux1pJjMJK8ZiYhT5Opkwp3/dkrsFa71AeubkmLePUBvUl4prVKcyfJLYK1l Fi8QTTPzG1sN4lZ0YtWCG31VvCxMzV0qvm9yc6vIIniQDLmazemLKFC7yBeu9KSzR/r8 6KgU33BcxI0T6gBzSP3b2ko3rWh9LVrJ9dNv6Jml3K8T5p786eGSFdqqo9UKn+vCnotK d2qXXHLTaGb5yl/bsk7NZ+IIOj/a1ikT3Au0fem+eZzsgaWhBklrlPrIiVYoWYXZTizC BxSQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786372409; x=1786977209; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=mW6857ZUCKMxTWq8NsQePygvrLZZIX0lwqlDz2Pl/S8=; b=ZhMLVp+fWr3JrD1zpz1+j3d5JLRkyh1QWG4Py7VPQF68lS9rAdfM68a8PD7fF1b9eQ ksAJwpq1nPslZkWqTdoLNuT198sadNzoK1X9HvZOksUDU4fAnnjXPMJgO3hvGjiZdoHA 5vndlrSAaZdACrONwjxIGcabX/NQQK9V8sxsl+j4hFeQ22ltHlO5ofKG7eWq1bw42Gkg M571HWuzXC2cqmqwb8FC7vHxICWo9HfygGOlf2ibsQM6VnWPAsDUUrTTHLaAkwDKn4YL EPRMHhU2r+fcG0YOBH5Uy5hPbgfErd/S2qJnQez04PtA2/6BtvMdDi2rLADwsViDxk3X k7yg== X-Forwarded-Encrypted: i=1; AHgh+RqL9yfPX3FRem01vf5zctZ14wwwVA0yDdPkbXRcfvYRHdRs6Exq4xN9k6kyOGnS+WzZNjd+jplriTjygng=@vger.kernel.org X-Gm-Message-State: AOJu0Yz9CZ0uw4PdCRUuShoJWCw3yrNyJfNM4X6GAB4vB/cWFM2VSD67 9e4AE501FFx2VT4ab2j0PdDlz4ISWFiftgSw2PffZ1naoGSlUiMrLV10 X-Gm-Gg: AR+sD10iiZrDpzOltRpS2ZCXIjsS4sSG71VO711j4eO/QdGGxpBeB5W43cF9VLJHbaL iyB1UIlrAyD2qzW6fZcztMxVh361P6MsDbHM9tdVVes+3jxZFXum5RjMerx7bclp8KRoahIJJXa Z7H8R2jpQFF8wKgKeZigLJApN+PAp6LuRPpH+NEWBpK8flpARwXMHnH7eu+oNKXoCgG4z+ym8E0 VmwFKIdI3Z3lwhFMRJLjWoX0ZZbrx3A8YnUGQawMlYhp68wQk8v6XHEQTqL1zbm/2n0dMGzKIgD cSP4gOUbkgDjjEGh0J+k2/OCWDTYHdVmPsETYjFU0LzhVBujURhf6wq3fW3V8+H0JvRSplnC7P2 Dsnd5y05hb7QXI0vm50i51fIWt/urpynAJU3nR9gOGlUE5Edx4jOkCNH4IExYS+E9iUnLtfpRog d+ValEQaDsFVhmoiZSMWTIp9+vLD/dccugw+owmcABT5iVOijNM1V2mPtYm4ozSG3D1k4MN4Pnq 9E= X-Received: by 2002:a05:6a21:3a44:b0:3cb:eb06:ce09 with SMTP id adf61e73a8af0-3cc1a38a664mr3122778637.25.1786372409128; Mon, 10 Aug 2026 07:33:29 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1410cc132c1sm22197001c88.8.2026.08.10.07.33.26 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Mon, 10 Aug 2026 07:33:28 -0700 (PDT) From: Chen Miao To: corbet@lwn.net, alexs@kernel.org, si.yanteng@linux.dev, skhan@linuxfoundation.org, dzm91@hust.edu.cn, mchehab@kernel.org, wy@wyuan.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v2 3/5] docs: sphinx-build-wrapper: prefer gmake Date: Mon, 10 Aug 2026 22:33:07 +0800 Message-ID: <20260810143311.57775-4-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260810143311.57775-1-chenmiao.ku@gmail.com> References: <20260810143311.57775-1-chenmiao.ku@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. This keeps the wrapper's selection consistent with sphinx-pre-install. Signed-off-by: Chen Miao --- tools/docs/sphinx-build-wrapper | 55 ++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index 1bb962202..aa6a297db 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -71,6 +71,7 @@ from jobserver import JobserverExec # pylint: dis= able=3DC0413,C0411,E0401 # VENV_DEFAULT =3D "sphinx_latest" MIN_PYTHON_VERSION =3D PythonVersion("3.7").version +MIN_MAKE_VERSION =3D PythonVersion("4.0").version PAPER =3D ["", "a4", "letter"] =20 TARGETS =3D { @@ -97,6 +98,46 @@ class SphinxBuilder: with the Kernel. """ =20 + @staticmethod + def get_make_version(cmd): + """Return the GNU Make version, or None for another make.""" + if not cmd: + return None + + try: + result =3D subprocess.run( + [cmd, "--version"], + stdout=3Dsubprocess.PIPE, + stderr=3Dsubprocess.PIPE, + text=3DTrue, + check=3DTrue, + ) + except (OSError, subprocess.CalledProcessError): + return None + + match =3D re.search( + r"^GNU Make\s+([0-9]+(?:\.[0-9]+)*)", result.stdout, re.MULTIL= INE + ) + if not match: + return None + + return PythonVersion.parse_version(match.group(1)) + + def get_make(self): + """Select the first GNU Make 4.0 or newer in preference order.""" + candidates =3D [ + self.env.get("MAKE"), + shutil.which("gmake"), + shutil.which("make"), + ] + + for cmd in candidates: + version =3D self.get_make_version(cmd) + if version and version >=3D MIN_MAKE_VERSION: + return cmd + + sys.exit("GNU Make 4.0 or newer is required") + def get_path(self, path, use_cwd=3DFalse, abs_path=3DFalse): """ Ancillary routine to handle patches the right way, as shell does. @@ -569,9 +610,10 @@ class SphinxBuilder: texinfo directory. """ =20 + make =3D self.get_make() for output_dir in output_dirs: try: - subprocess.run(["make", "info"], cwd=3Doutput_dir, check= =3DTrue) + subprocess.run([make, "info"], cwd=3Doutput_dir, check=3DT= rue) except subprocess.CalledProcessError as e: sys.exit(f"Error generating info docs: {e}") =20 @@ -787,12 +829,11 @@ class SphinxBuilder: =20 if rustdoc and target in ["htmldocs", "epubdocs"]: print("Building rust docs") - if "MAKE" in self.env: - cmd =3D [self.env["MAKE"]] - else: - cmd =3D ["make", "LLVM=3D1"] - - cmd +=3D [ "rustdoc"] + make =3D self.get_make() + cmd =3D [make] + if make !=3D self.env.get("MAKE"): + cmd.append("LLVM=3D1") + cmd.append("rustdoc") if self.verbose: print(" ".join(cmd)) =20 --=20 2.50.1 (Apple Git-155) From nobody Tue Sep 29 08:25:35 2026 Received: from mail-pf1-f177.google.com (mail-pf1-f177.google.com [209.85.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A6E0D3FA5FA for ; Mon, 10 Aug 2026 14:33:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.177 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372414; cv=none; b=fFW8kpFQkkelRZkDJe8Pe7fodtv9xwMjM9jAXlZIHMJvk9YzgxVWDKEAHBZEF5qfGU3h5WJdM3AKPkHFkUoWksFmSKV7/4SUI7M69brKHGi6ZOYBlTI0G5LVP3PBZCZJeWrDiqb6D++tetbOz0XubFclfO/4ztBLVge9BpAxH6s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786372414; c=relaxed/simple; bh=vAS3XXy80kygIF9Q312sEQcYcNWCvzeW4fKWAXXwzmE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=KvQnhuT/Yx2YoWE0gZV8Z96Uv5BiNnoroVQS12iTW4+5kJEmLkqQYbILi55r8OqOi+oSGaecduMUS1Ks2LruIUFjEfbdLjpx0/KFS3+9NrV5qPUC3dbz0eRi3+WdDg2ObshYVCQiFWbbT/oO8bfadlEqOW5jjkc4/3M0qHxRqQA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Cet86NRS; arc=none smtp.client-ip=209.85.210.177 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Cet86NRS" Received: by mail-pf1-f177.google.com with SMTP id d2e1a72fcca58-8486672f03cso1870246b3a.0 for ; Mon, 10 Aug 2026 07:33:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786372412; x=1786977212; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=rY7zCmLlC8EX8bVm77K2UlgL+HheFi3M6EBapeAXM2A=; b=Cet86NRSfWzecA6rjkoYXiXxVRDjFeSeQkbCvLoPwTpJ9EXWpnUOkiXpyUPLUF4DP4 ou7slsWcpfniWgnI+YTJE0p9t0E0egawCHNNJhq3TUhx3X79zhHaYMSUpImKdYfJYIM8 e8fWvV9Z1NWZMFN1ET2YVEDAAMtSq5TGd2Aj7qhtcLXBCzEKfEL/gIRwIsM2XD2LguTQ n3vL5K+EbQNkhKflFs3Laxg0+n4UW51MWccd++XSHCuBc4UeV796Z+fexZAU7bO/9dOj /mLC1kf8uNeQTELKN895vkD0mWoLYjKzj58zrX7ZSZvWU9Wdx+nTGTH/4CqF15H4ZmjW 42bw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786372412; x=1786977212; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=rY7zCmLlC8EX8bVm77K2UlgL+HheFi3M6EBapeAXM2A=; b=IVoMVEIpwMfVOFwDV3+//0OsKy1ZWWonCXnSF0nmO3cfT3F019LKZ1bza2gAJwvG4/ T9n33TTRVWmW43Zr86hsh0K84KtyzommrmP4Ce8g/0sESnTNd4jLVQzHFE6QiSukauSA pIJ07rt4um6AI24h9IYiz2gytAXQZx8xd5/qkI9yrZcU/sHMSymwq5BWLa8w5MMI8DdZ mbE6tuyfg8vVFZRE4s7pfjWOu4Yf75DOJBvMb01el1r+hvXgS9s1HohWTgo4VoW5MDwK IALf3Ad0VOsqnGY2rtI6O+TomoUlfRFdiA5hApuUNG+UmVXul3GOyQ5VeFjpMmD5GxUB iY0A== X-Forwarded-Encrypted: i=1; AHgh+Ro8/1vAlQdtWeuHG0L7hcpKNyLFrzHVllnHdP1AaYHdpRl9FxRZUQub9vpAU3VdsWYyTEXhAaPLIPanKVw=@vger.kernel.org X-Gm-Message-State: AOJu0YyR7pukleO+EWOIMzchZIW9J+b/YBjTAA4f/Ghm7PNA49Y8YzPK 1NQHLwi1dpZJUTB3PE5B2kT9McQwLDpDupgQdckQAcGfTmNwZjXJe86F X-Gm-Gg: AR+sD12d23vT0RC/tIwVyZVKEMqGONWsedFLpCcixSCdkeQwml3TAtJMaQIQtLv8ary PL/SHCqI2nm+EcFaOsQSTYCpXd3RbsH3sUmzu1X2qCAWn9kvBvcDUy2FwMdkYrNBv51RQOghu3z 17SrqOuvhQtSKCzdHvVjJKwCPkLBGzfltYTeWQfDMSx8AY+YsUY8AoMSIin8g1fQu90F7YMndxU aMYq2QqRcBw4z4wcuQUDqZdCCDJiWadKtEWxEYBO7ExAbmr483bmJ3PH6NoX2QvAvKwyixfYGhZ xNH+dxjLC05mcgd8rGgomJ6ezqcrKdvSOQShvhaXSe+x7lyXRM2Kc6XTzALNuE2MK5WIjrZmn8q Uu2+YMgmgKFx8dk9fo+2ZveLHj5FEfV75I7AW4o262bqBCp74imLoLlIl0ShyX6B4b0k6uE1Csg m++4pAGogNcsWiP/CMCksFAvNEs97iPvox+nCEWYeUULy+zyN8PCMJ6H0Xvvci9YdLWuEuOUiQr TCweOztGpT+Wg== X-Received: by 2002:a05:6a20:e211:b0:3c8:e140:63a8 with SMTP id adf61e73a8af0-3cc1a315881mr2311626637.23.1786372411945; Mon, 10 Aug 2026 07:33:31 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1410cc132c1sm22197001c88.8.2026.08.10.07.33.29 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Mon, 10 Aug 2026 07:33:31 -0700 (PDT) From: Chen Miao To: corbet@lwn.net, alexs@kernel.org, si.yanteng@linux.dev, skhan@linuxfoundation.org, dzm91@hust.edu.cn, mchehab@kernel.org, wy@wyuan.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v2 4/5] docs/zh_CN: doc-guide: document macOS Sphinx setup Date: Mon, 10 Aug 2026 22:33:08 +0800 Message-ID: <20260810143311.57775-5-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260810143311.57775-1-chenmiao.ku@gmail.com> References: <20260810143311.57775-1-chenmiao.ku@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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. Signed-off-by: Chen Miao --- .../translations/zh_CN/doc-guide/sphinx.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Docume= ntation/translations/zh_CN/doc-guide/sphinx.rst index 3375c6f3a..e6d42d970 100644 --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -110,6 +110,22 @@ PDF=E5=92=8CLaTeX=E6=9E=84=E5=BB=BA =20 =E4=BD=BF=E7=94=A8Sphinx=E7=9A=84=E7=B3=BB=E7=BB=9F=E6=89=93=E5=8C=85=EF= =BC=8C=E8=80=8C=E4=B8=8D=E6=98=AFPython=E8=99=9A=E6=8B=9F=E7=8E=AF=E5=A2=83= =E3=80=82 =20 +macOS =E9=BB=98=E8=AE=A4=E4=BD=BF=E7=94=A8=E4=B8=8D=E5=8C=BA=E5=88=86=E6= =96=87=E4=BB=B6=E5=90=8D=E5=A4=A7=E5=B0=8F=E5=86=99=E7=9A=84 APFS =E5=8D=B7= =EF=BC=8C=E8=80=8C=E5=86=85=E6=A0=B8=E6=BA=90=E7=A0=81=E6=A0=91=E4=B8=AD=E5= =AD=98=E5=9C=A8=E4=BB=85=E5=A4=A7=E5=B0=8F=E5=86=99 +=E4=B8=8D=E5=90=8C=E7=9A=84=E6=96=87=E4=BB=B6=E3=80=82=E5=85=8B=E9=9A=86= =E6=BA=90=E7=A0=81=E5=89=8D=EF=BC=8C=E8=AF=B7=E7=94=A8 ``diskutil apfs list= `` =E6=89=BE=E5=88=B0 APFS =E5=AE=B9=E5=99=A8=E6=A0=87=E8=AF=86=E7=AC=A6=EF= =BC=8C +=E5=B0=86=E4=B8=8B=E9=9D=A2=E7=9A=84 ``diskX`` =E6=9B=BF=E6=8D=A2=E4=B8=BA= =E8=AF=A5=E6=A0=87=E8=AF=86=E7=AC=A6=EF=BC=8C=E5=B9=B6=E5=88=9B=E5=BB=BA=E4= =B8=80=E4=B8=AA=E9=A2=9D=E5=A4=96=E7=9A=84=E5=A4=A7=E5=B0=8F=E5=86=99=E6=95= =8F=E6=84=9F=E5=8D=B7:: + + diskutil apfs addVolume diskX APFSX Linux + +=E5=9C=A8 macOS =E4=B8=8A=EF=BC=8C=E8=AF=A5=E8=84=9A=E6=9C=AC=E4=BD=BF=E7= =94=A8 Homebrew =E5=AE=89=E8=A3=85=E7=B3=BB=E7=BB=9F=E4=BE=9D=E8=B5=96=EF= =BC=8C=E8=BE=93=E5=87=BA=E7=9A=84 Homebrew =E5=91=BD=E4=BB=A4=E4=B8=8D=E9= =9C=80=E8=A6=81 +``sudo``=E3=80=82PDF =E5=B7=A5=E5=85=B7=E9=93=BE=E7=94=B1 ``mactex-no-gui`= ` cask =E6=8F=90=E4=BE=9B=EF=BC=8C=E6=89=80=E9=9C=80=E7=9A=84 DejaVu =E5=92= =8C Noto CJK +=E5=AD=97=E4=BD=93=E5=88=99=E9=80=9A=E8=BF=87 Homebrew font cask =E5=AE=89= =E8=A3=85=EF=BC=9B=E5=A6=82=E6=9E=9C=E5=8F=AA=E6=9E=84=E5=BB=BA HTML =E6=96= =87=E6=A1=A3=EF=BC=8C=E8=AF=B7=E4=BD=BF=E7=94=A8 ``--no-pdf``=E3=80=82 +=E5=AE=89=E8=A3=85 MacTeX =E5=90=8E=EF=BC=8C=E8=AF=B7=E9=87=8D=E6=96=B0=E5= =90=AF=E5=8A=A8=E7=BB=88=E7=AB=AF=EF=BC=8C=E6=88=96=E8=BF=90=E8=A1=8C +``eval "$(/usr/libexec/path_helper)"`` =E4=BD=BF=E5=91=BD=E4=BB=A4=E8=A1= =8C=E5=B7=A5=E5=85=B7=E5=8F=AF=E8=A7=81=E3=80=82macOS =E7=94=A8=E6=88=B7=E5= =BB=BA=E8=AE=AE=E4=BD=BF=E7=94=A8 +=E9=BB=98=E8=AE=A4=E7=9A=84 Python =E8=99=9A=E6=8B=9F=E7=8E=AF=E5=A2=83=EF= =BC=8C=E5=9B=A0=E4=B8=BA PyYAML =E4=BC=9A=E4=BB=8E +``Documentation/sphinx/requirements.txt`` =E5=AE=89=E8=A3=85=EF=BC=8C=E8= =80=8C=E4=B8=8D=E6=98=AF=E9=80=9A=E8=BF=87 Homebrew =E5=AE=89=E8=A3=85=E3= =80=82 +=E8=AF=A5=E8=84=9A=E6=9C=AC=E8=BF=98=E4=BC=9A=E6=A3=80=E6=9F=A5 GNU Make 4= .0 =E6=88=96=E6=9B=B4=E9=AB=98=E7=89=88=E6=9C=AC=EF=BC=9B=E5=A6=82=E6=9E=9C= Homebrew =E5=B0=86=E5=85=B6=E5=AE=89=E8=A3=85=E4=B8=BA +``gmake``=EF=BC=8C=E8=AF=B7=E4=BD=BF=E7=94=A8 ``gmake htmldocs``=EF=BC=8C= =E8=80=8C=E4=B8=8D=E6=98=AF ``make htmldocs``=E3=80=82 + Sphinx=E6=9E=84=E5=BB=BA =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -409,4 +425,3 @@ Documentation/doc-guide/kernel-doc.rst =E3=80=82 ; Mon, 10 Aug 2026 07:33:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786372415; x=1786977215; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=Nks8VC3vHUBzywbcvluMteExgRFIxGN8FNe5HK/cCDk=; b=Odc9+CzuwJBhBObWPmOcmafPmzHBTu5LuAtHN/Vl/bqLGFhV3w5kIkhP7dANkMABKc BbbLwG4fOfeCqyvDm0aZAXGorMdi2TQggMC6mXOTXxpK0G7evicSuzyHFhPFaSuqJwn8 zhwx/XkRt5RiemL7XnpO7rgwNEfD1GVgYqPvNlUikCI6osZ0+V8KHtFrjV3wsJ2GQgtz z3YhsBBaCJ7HE6c+qGq3WW5iYfB0ZSEQNktEKBLHCN8N2sfUEGXaDznojQT99AKOKY4w BE91iLkE0rdYH+swEtJzjqao0AHBk4E5yATyNGEpXZ89zFAuniU4MnLjq4n7zGnMAnQz +Pyg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786372415; x=1786977215; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=Nks8VC3vHUBzywbcvluMteExgRFIxGN8FNe5HK/cCDk=; b=imMaZM8oLFW29XD+1rlaXueDWLjhOdY8z3C1Gbrya0uggQMLrWhdGxEDnWdQjpZfLa 4rVixIE0rw7oB1UqLJL/0D/PCJE/SJf4OWSpoxSkc6B5IDG4dxYIQCqSJJknUhj2xnXC 3Br3iZLM6+Wf970O4FYL7hwMnUtqYPP4V675VcMdlHQU8JKTxTxkJFgU0QkwcgXA3G9J sKLgY3pmENoVD2OmXSQz4TOV2RBcbroKPlPGglH91YF0qveR5w7FzJZDb5WjS36eCZ2I p0DcVmwzsqkpOKg6Jgw6FEuJFDBu2IBQFsHE281ryTowAIumt8inU99335QACtUZwxkr klaw== X-Forwarded-Encrypted: i=1; AHgh+Rpv0LmjX4Mp3uAsAF4oz0VsXcVdD5RxXz148nSWgbkwVosia7CgXULSqsrBcWiSnl/rnlKqab3YKFul2DQ=@vger.kernel.org X-Gm-Message-State: AOJu0YxpByiI1mIR4YaP/vKAkpRRzn00EF6oYDeHYWXM5OPv8E2IQ8ir Wf7W+LgJ0BRLR4lpLb31FaGMEpSZOoZ5cQNXUR6ZjBYvmz5Z0qLP2OSU X-Gm-Gg: AR+sD111v2qdA4oLaxyeM1KDwA49OPNbKBIHIiDThkA4WXEjyhkEZIOAT+49rQi7s9u o6ExfKJZ/elU57LfL6rwtU+Ic7gMuklCfEtLNTrVekIJCQB//hAN1e2i+QiStxjlwy0pyv/vqe3 Cg0HWchNVdh92nJmJohAt7V6TPPIy/7bfMMJF8sDyigfX3SjEd1jfrMdAr2Yyro5CLgD+0Cuq86 paI95AsVOYnZiojBvOMbaCV1u5u8jMWbRyeyjE+pOYrPguf1t++Aw4ZVxB2zxHuIJCpOGdx09OL p5NPecKNSaE9Z+FIwbwBKLZXvYgnOwzUqMBNqsIHqw/v6YMVEjrRyVG7K9Y4eKF7DEjSVZFdArA InF6xyllR/Fq/Vg2Uz4QSHwao29aYwctlAC2KWASMRciqaLcH95A/75hmu8XWeyvk3V8N98xQ70 zcN5Y1BBSw4avsnAQ3J+yuWg24RK/M9YEmF7YzP0wxgNDPOrAT+2mxDqgdH6yQAS+XfgcxJSEcA X0= X-Received: by 2002:a17:90b:4e8d:b0:38d:ec31:4840 with SMTP id 98e67ed59e1d1-3903c5932femr46548870a91.13.1786372414681; Mon, 10 Aug 2026 07:33:34 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-1410cc132c1sm22197001c88.8.2026.08.10.07.33.32 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Mon, 10 Aug 2026 07:33:34 -0700 (PDT) From: Chen Miao To: corbet@lwn.net, alexs@kernel.org, si.yanteng@linux.dev, skhan@linuxfoundation.org, dzm91@hust.edu.cn, mchehab@kernel.org, wy@wyuan.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v2 5/5] docs/zh_CN: how-to: document case-sensitive APFS setup Date: Mon, 10 Aug 2026 22:33:09 +0800 Message-ID: <20260810143311.57775-6-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260810143311.57775-1-chenmiao.ku@gmail.com> References: <20260810143311.57775-1-chenmiao.ku@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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. Signed-off-by: Chen Miao --- Documentation/translations/zh_CN/how-to.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/tr= anslations/zh_CN/how-to.rst index 9ec2384e1..e1d3d2b8b 100644 --- a/Documentation/translations/zh_CN/how-to.rst +++ b/Documentation/translations/zh_CN/how-to.rst @@ -102,6 +102,14 @@ Linux =E5=8F=91=E8=A1=8C=E7=89=88=E5=92=8C=E7=AE=80=E5= =8D=95=E5=9C=B0=E4=BD=BF=E7=94=A8 Linux =E5=91=BD=E4=BB=A4=E8=A1=8C=EF=BC= =8C=E9=82=A3=E4=B9=88=E5=8F=AF=E4=BB=A5=E8=BF=85=E9=80=9F=E5=BC=80=E5=A7=8B= =E4=BA=86 =E5=BC=80=E5=A4=B4=E7=9A=84=E5=91=BD=E4=BB=A4=E3=80=82**=E8=AF=B7=E6=B3=A8= =E6=84=8F**=EF=BC=8C=E6=9C=80=E6=96=B0=E7=89=88=E6=9C=AC Sphinx =E7=9A=84= =E6=96=87=E6=A1=A3=E7=BC=96=E8=AF=91=E9=80=9F=E5=BA=A6=E6=9C=89=E6=9E=81=E5= =A4=A7=E6=8F=90=E5=8D=87=EF=BC=8C=E5=BC=BA=E7=83=88=E5=BB=BA=E8=AE=AE =E6=82=A8=E9=80=9A=E8=BF=87 pip/pypi =E5=AE=89=E8=A3=85=E6=9C=80=E6=96=B0= =E7=89=88=E6=9C=AC Sphinx=E3=80=82 =20 +macOS =E9=BB=98=E8=AE=A4=E4=BD=BF=E7=94=A8=E4=B8=8D=E5=8C=BA=E5=88=86=E6= =96=87=E4=BB=B6=E5=90=8D=E5=A4=A7=E5=B0=8F=E5=86=99=E7=9A=84 APFS =E5=8D=B7= =EF=BC=8C=E8=80=8C=E5=86=85=E6=A0=B8=E6=BA=90=E7=A0=81=E6=A0=91=E4=B8=AD=E5= =AD=98=E5=9C=A8=E4=BB=85=E5=A4=A7=E5=B0=8F=E5=86=99 +=E4=B8=8D=E5=90=8C=E7=9A=84=E6=96=87=E4=BB=B6=E3=80=82=E5=9C=A8=E6=89=A7= =E8=A1=8C ``git clone`` =E5=89=8D=EF=BC=8C=E5=8F=AF=E5=9C=A8=E7=8E=B0=E6=9C= =89 APFS =E5=AE=B9=E5=99=A8=E4=B8=AD=E5=88=9B=E5=BB=BA=E4=B8=80=E4=B8=AA=E9= =A2=9D=E5=A4=96=E7=9A=84=E5=A4=A7=E5=B0=8F=E5=86=99 +=E6=95=8F=E6=84=9F=E5=8D=B7=EF=BC=88=E5=85=88=E7=94=A8 ``diskutil apfs lis= t`` =E6=89=BE=E5=88=B0=E5=AE=B9=E5=99=A8=E6=A0=87=E8=AF=86=E7=AC=A6=EF=BC= =8C=E5=B9=B6=E5=B0=86=E4=B8=8B=E9=9D=A2=E7=9A=84 ``diskX`` =E6=9B=BF=E6=8D= =A2=E4=B8=BA=E8=AF=A5=E6=A0=87=E8=AF=86=E7=AC=A6=EF=BC=89:: + + diskutil apfs addVolume diskX APFSX Linux + +=E7=84=B6=E5=90=8E=E5=B0=86=E5=86=85=E6=A0=B8=E6=BA=90=E7=A0=81=E5=85=8B= =E9=9A=86=E5=88=B0=E6=96=B0=E5=8D=B7=E4=B8=AD=E3=80=82 + =E5=A6=82=E6=9E=9C=E6=82=A8=E5=A4=84=E4=BA=8E=E4=B8=80=E4=B8=AA=E5=A4=9A= =E7=94=A8=E6=88=B7=E7=8E=AF=E5=A2=83=E4=B8=AD=EF=BC=8C=E4=B8=BA=E4=BA=86=E9= =81=BF=E5=85=8D=E5=AF=B9=E5=85=B6=E4=BB=96=E4=BA=BA=E9=80=A0=E6=88=90=E5=BD= =B1=E5=93=8D=EF=BC=8C=E5=BB=BA=E8=AE=AE=E6=82=A8=E9=85=8D=E7=BD=AE=E5=8D=95= =E7=94=A8=E6=88=B7 sphinx =E8=99=9A=E6=8B=9F=E7=8E=AF=E5=A2=83=EF=BC=8C=E5=8D=B3=E5=8F=AA=E9= =9C=80=E8=A6=81=E6=89=A7=E8=A1=8C:: =20 --=20 2.50.1 (Apple Git-155)