From nobody Tue Sep 29 10:31:56 2026 Received: from mail-pj1-f51.google.com (mail-pj1-f51.google.com [209.85.216.51]) (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 C47663C7696 for ; Sun, 9 Aug 2026 10:19:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786270780; cv=none; b=XVTdy5PLAYrOIfSensCCd7+yUp1sxdxxhdbxUfo9XHLKQlVGeusEo8xLGiFNs8Cp6Vej4BZf8NpiVlkQDbIfZtoXkccoNswCY6fCwpcx8Ccddr3usZQttvKfIeEgrLrm/NyFYdg0/ZdpmgcF/IEXqVlZEks6eXGdWt88haioQfA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786270780; c=relaxed/simple; bh=XFpa9qqJHXQ75q8ftQFv3NfSfTXAQFOerS7OCU49TIU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=S3s29PLNOXem62F/zi9YIZRAt1IHdDwB8nTvXhBSuCav4AQ1Y9kAiYqwCsfrD+xoTtdfojUuJGI62lCSlPT7SKeBZVM2umibyu7AudIt5zCqaMSUOzssyq51fTKr7RxsngtJvoNKqC38cBvUL0h+rQfsgY3KXsvTxvvtMAs6FB8= 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=VyHv7c7C; arc=none smtp.client-ip=209.85.216.51 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="VyHv7c7C" Received: by mail-pj1-f51.google.com with SMTP id 98e67ed59e1d1-38dc69c74b8so870365a91.0 for ; Sun, 09 Aug 2026 03:19:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786270778; x=1786875578; 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=j0GQIEu3grCj2nut7YybPJeaOsz3yt22QKb2C8hAm64=; b=VyHv7c7Cuakcji0XWr4pXZ07xwrATIupaNHN6P/s5CdgdmZ410T4d4his2R4eFj3UH tFusVhnFhAOMYgNeG6j8Znyj9HiqUhC3ui5UugmP+GJIMHhdZuoiiqpypv7MrmcNbGc2 usVP/n5XCMdfgYgdhK6xQn69CjB40w4EQrobxuo0VVw8uUOBKDUqrDFYkY6RXel0/39s AUpQzE/27xgrydOujU5qmZlbQ9bYdmui7sMN3kSkv+7adV8g8MDH30hZ/RGysTe/1FBZ fscJXoSw/jYgqJpLJjJTuyV5fkADo1+Ea3WM8X1LUb1ri8DZMfJ38movnW/xGMFqtJw1 xefw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786270778; x=1786875578; 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=j0GQIEu3grCj2nut7YybPJeaOsz3yt22QKb2C8hAm64=; b=hRiv7K0NZQXR8504qYlqRRNyZLyaIWDRnZqSDVFSvBs9cMeK3cXsBPdzyYNvBnY6c1 Q+5vld2/BmPY1Ypilm3Q2wV2PoIFaDM2e9ru80xPF/3hhW6BeemLSG9iJmBybUnayARj 90HWvSj2YZDyaZteArDIEBX2XKht+r2xdJ74sJi0PgRLKwsuMGF4lAtx8vMFm2NXnzl3 zEp+bHoweOvEX9DBXIf7LlEbUTc5mRfkGf5Vz7yI301AWPqIXMSKHvNu85J4hOcMKaYF oeUkm+ZCR17x2nc0ynHJG+XlKr4YFt4lCzYEwbJJu2vhldHztxpXzNzfxqYaOkhtM+OL dAYQ== X-Forwarded-Encrypted: i=1; AHgh+RoqE8QTXL6yd1e+F9kweaD0RsTjQncuX8y/koZZZmUQUZQ4PtoL7/9AFVM7vpwCi+8P2l5Lx4NlIcqfKT4=@vger.kernel.org X-Gm-Message-State: AOJu0YwpAqPXfVEd9GvvZqsNG+A26uJPAh0aIivLNUUGY1HfSaS5wMOz oMXkNnvKSWxXS3HM9ZUazU8wBvcTHaXh/8O6ysQB+5us8FQ6ZTGKMoHSAYbSzZdz X-Gm-Gg: AR+sD11VrSfPyBHAmuwVLoh9P4M1RP4e8Ko1LnhKDh5sgtLNM8M8aCWzvmcxlWJV0mc Sj2H56nBORoR0ILe5u3Q0NyPp+y1K7WPCYCJwEg6JJVobwonRNt8ZKtcL0QmERviIe1LNU25Ykt 1QN0iwpl5+Z8c19vc+kSCgVGbQykfyGD5rg5ul2imGh7JaQY+acjzjvwhtG/w3Jdrylvi67K4YX kZ2i37bfFxMrAg99rTFqLQ2+94WRJKkNdLEBzBMmQnG+S7UBkQolx9zHxgF9/j86I+SUPyDQ33L GGbLuIvKSYv+DSb1QVai0vVptsVN+K93jrnuwrdU3dDyPTwTkKtL8zTiZ2wsK2E4D1gzC+hXjms QW/u/29+Pod3SlgKf7zr8R+Upg4K/jEKGslpgWpZ/43VSkqq23gk7wz3EFw+xRs2U/7oc96U7UZ MGqxFUGTSZpcDNnDktAJSpzVoIVe2BksuyIA40LGskrk+8s/chBRwzlee7TM6cgLeabrIVQeCGm Xw= X-Received: by 2002:a17:90b:3a81:b0:37f:f8c5:93c2 with SMTP id 98e67ed59e1d1-3903c634c04mr28765977a91.21.1786270777871; Sun, 09 Aug 2026 03:19:37 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-315be8a9220sm31496134eec.7.2026.08.09.03.19.35 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Sun, 09 Aug 2026 03:19:37 -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 Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support Date: Sun, 9 Aug 2026 18:19:20 +0800 Message-ID: <20260809101923.13176-2-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260809101923.13176-1-chenmiao.ku@gmail.com> References: <20260809101923.13176-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 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 MacTeX as a cask without sudo. Keep PyYAML in the virtual environment requirements because Homebrew does not provide a PyYAML formula. Document the macOS setup and the --no-pdf option. Signed-off-by: Chen Miao --- Documentation/doc-guide/sphinx.rst | 7 ++ .../translations/zh_CN/doc-guide/sphinx.rst | 5 ++ Documentation/translations/zh_CN/how-to.rst | 6 ++ tools/docs/sphinx-pre-install | 89 ++++++++++++++++++- 4 files changed, 106 insertions(+), 1 deletion(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 51c370260..62aca56b8 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -131,6 +131,13 @@ It supports two optional parameters: ``--no-virtualenv`` Use OS packaging for Sphinx instead of Python virtual environment. =20 +On macOS, the script uses Homebrew for system dependencies. Homebrew +commands are printed without ``sudo``. The PDF dependencies are provided by +the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentatio= n. +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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Docume= ntation/translations/zh_CN/doc-guide/sphinx.rst index 3375c6f3a..154142318 100644 --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -110,6 +110,11 @@ 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 +=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 =E4=BE=9D=E8=B5=96=E9=80=9A=E8=BF=87 ``mactex`` cask = =E6=8F=90=E4=BE=9B=EF=BC=9B=E5=A6=82=E6=9E=9C=E5=8F=AA=E6=9E=84=E5=BB=BA HT= ML =E6=96=87=E6=A1=A3=EF=BC=8C=E8=AF=B7=E4=BD=BF=E7=94=A8 +``--no-pdf``=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 + Sphinx=E6=9E=84=E5=BB=BA =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/tr= anslations/zh_CN/how-to.rst index 9ec2384e1..e8c91d81a 100644 --- a/Documentation/translations/zh_CN/how-to.rst +++ b/Documentation/translations/zh_CN/how-to.rst @@ -102,6 +102,12 @@ 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 +=E5=A6=82=E6=9E=9C=E6=82=A8=E4=BD=BF=E7=94=A8 macOS=EF=BC=8C=E8=84=9A=E6= =9C=AC=E4=BC=9A=E4=BD=BF=E7=94=A8 Homebrew =E8=BE=93=E5=87=BA=E5=AE=89=E8= =A3=85=E5=91=BD=E4=BB=A4=EF=BC=8CHomebrew =E5=91=BD=E4=BB=A4=E4=B8=8D=E9=9C= =80=E8=A6=81 +sudo=E3=80=82PDF =E6=9E=84=E5=BB=BA=E6=89=80=E9=9C=80=E7=9A=84 MacTeX =E9= =80=9A=E8=BF=87 Homebrew 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 +=E5=8F=AF=E4=BB=A5=E6=89=A7=E8=A1=8C ``./tools/docs/sphinx-pre-install --n= o-pdf``=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 H= omebrew =E5=AE=89=E8=A3=85=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 diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install index 965c9b093..51a296cc7 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,69 @@ 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. + + Homebrew formulae and casks must not be installed with sudo. MacTeX + is a cask, while the other dependencies are formulae. + """ + if not self.which("brew"): + if not self.distro_msg: + self.deps.add_package("Homebrew", DepManager.SYSTEM_MANDAT= ORY) + self.deps.check_missing({}) + self.deps.warn_install() + self.distro_msg =3D \ + "Homebrew is required for macOS support. Install it fr= om " \ + "https://brew.sh/ and re-run this script." + return None + + progs =3D { + "Pod::Usage": "perl", + "convert": "imagemagick", + "dot": "graphviz", + "ensurepip": "python", + "python-sphinx": "sphinx-doc", + "rsvg-convert": "librsvg", + "xelatex": "mactex", + "latexmk": "mactex", + } + + 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() + for prog in self.deps.missing: + if prog =3D=3D "yaml": + self.distro_msg =3D \ + "PyYAML is not provided as a Homebrew formula. Use the= " \ + "default virtualenv mode so it is installed from " \ + "Documentation/sphinx/requirements.txt." + continue + + package =3D progs.get(prog, prog) + if package =3D=3D "mactex": + 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: + return None + + return "\nYou should run:\n" + "\n".join(commands) + def give_redhat_hints(self): """ Provide package installation hints for RedHat-based distros @@ -1138,6 +1219,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 +1541,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 10:31:56 2026 Received: from mail-pg1-f169.google.com (mail-pg1-f169.google.com [209.85.215.169]) (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 9F5EF391E7C for ; Sun, 9 Aug 2026 10:19:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.169 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786270784; cv=none; b=gj9ni4Pj8dwQ2s9Nhr6yIwX5mujnTsqX98ki2KS6xF/WvtDEf1vaNDoWndHH+Wc/W3VquqN2LPEZFfpY+1vxC9OrUXLOeKSsj8sUhBmyCTu4ndZBqYs/HQaWMJwTMKJs9ofltYd4U/iZsGMI5crhvRO1e2gaU5B2vXIUlU9MDf0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786270784; c=relaxed/simple; bh=/i6kEpz5wmIoaseuOyVhaNR4V1C7KIvR8SZtaPFOafU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=FWSTfcT8bg//1bUsvtpvkjdCGM89K7h59LXwcKJd/JRAJlH3XqhoWfclYMtkrlQNAqp0EKp6wbtjReh3DYcfbQmlLUBbJ9uxV5AvCxUBbW+SGhtJFsAN2Qkp2WLAtBfCjR92KcHAtr61MHUeuIwno7R00Pe+J/uUPyxh+f8Zs/0= 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=MD8gvEG1; arc=none smtp.client-ip=209.85.215.169 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="MD8gvEG1" Received: by mail-pg1-f169.google.com with SMTP id 41be03b00d2f7-ca88130e09aso612772a12.3 for ; Sun, 09 Aug 2026 03:19:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786270782; x=1786875582; 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=QPwYJ1xuRDlGdV5WCrmZ+pmRm2w/eGmXKPl/ug4pFzw=; b=MD8gvEG1S4t/EuEALsziJ670Hz8OlFs1HqeBNS7nXYDZWEnHd9lD3OMKTJGYgcWITw +B9+ECDn0b3bg3obZrBe01PQDhMA72R3RvJJ5wq3YdWBD97earaBDqV3xF1DQOsfHSzr uFtSJXMrEThfHfwjQlLXSUE6y2TpTEmqXUojhK09DLrjyAHEIgmQKSaPoZst/rLkz+gJ lvv35UtcA3rqPhXtwIK/9gvbfDmLd/TLn+znl/VjtUPA3PGXD1csKzrfLlg3nuKaSz/G S9D9ba11zQt/hdrgEIzWHPAhH0T5pB0J6fplL3qWwC7LWWH2D4L+ooJr0P6qlcocOoWe IuAQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786270782; x=1786875582; 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=QPwYJ1xuRDlGdV5WCrmZ+pmRm2w/eGmXKPl/ug4pFzw=; b=Bg2IIPDU78WgVnbqRlUpoXHPp0nXTGnLAgolafn6LoqMlNIB1hxLZcJrmCw6GzNIUH 2CoZErKYn4PMEKoQB79AHGlbOevg6Sbi9fvQgXJEhAOTfeCY2He+wPXRjgMhcx8uoUU1 vOAI7YrT+qGYLPikdG4E3OTAYQ+s/IZXFbo1Efbg6ko7rw4f/9Fd7BRyqsyRXikdo4kb NzWuxMKD4wVaFNaNDq0N1Anl/mB5scVL917OqP6aXf5lg70/5eWc4TU60RaU5meZfWuo tJ3Bl9hMqZhIW0G1BBluvyOY1ywm9Y725gA++ksF+jNS1TakjEErnxnCaxPwuzdd/w6F fXfA== X-Forwarded-Encrypted: i=1; AHgh+RpYKjQOPmx95Rjz8mO4F3V63Ib0vnU9ZXxV29/Pe7C1Puor5HneRlYWyacLRs7f1qs8wzRutYTAq6GY9Sg=@vger.kernel.org X-Gm-Message-State: AOJu0YzXKHGiNY+JGhsxVc3e9JF/cjgMSN7NIWtHWfECe7hTM9rqpO3A mst0TDIB37FNKJoKCqMMpxHFPqJa2RELueH5ympfYTD5svaurBxti3zG X-Gm-Gg: AR+sD124+CdH2HONgQPmv3d/FIzU1O+mbUxYggNm5yvczVUUyE0yW8G6xqefWg2gL6w NvS/zMX9gtMavnbYUN93K6Ex1Xi2SHEODBqA8XteA7bj/JQoBFicjmFZMfnwO1e61FiWY6a131f hCC9a0AciQ8Gfkau92+nBpQdF2/TsnlGcNTi7yPHPIoQTGn1I4N+53DSim+fb2nW40Wjq0oTX0J JH9S6wCFCHTD9tg532KlAMUAlRWYygpvdMGdms2ukS7atDivX+vAQEYXvmHUCGfutqRLFyNJ09t Miil3QO86l+cOiZYRWqb0/ZJ9wHexoZBPsX236VnY/XpYQ2U0X80NQ/5cQnPAoqO+0rFmyarMHc CTVNIdGezfmx866IN7/g576E7nmbeYmh4N1/xCz74nC9J1OtgLbY8ypK0yzNYNgo6k/bFClUlo2 2y8CwPHoq5qwyT60YLoE0FcV645ZhHUTDHAw4i/2M3WCekUX+nlQw0HG43EuBl2yNBK3KEZsbzD Ho= X-Received: by 2002:a05:6a20:9e48:b0:3c3:875d:704d with SMTP id adf61e73a8af0-3cb85ee77c2mr46113590637.25.1786270781667; Sun, 09 Aug 2026 03:19:41 -0700 (PDT) Received: from localhost.localdomain ([64.186.250.142]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-315be8a9220sm31496134eec.7.2026.08.09.03.19.38 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Sun, 09 Aug 2026 03:19:41 -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 Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Chen Miao Subject: [PATCH v1 2/2] docs: sphinx-pre-install: check GNU Make version Date: Sun, 9 Aug 2026 18:19:21 +0800 Message-ID: <20260809101923.13176-3-chenmiao.ku@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260809101923.13176-1-chenmiao.ku@gmail.com> References: <20260809101923.13176-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 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. If make is missing or too old, report it as a missing dependency. Also accept a compatible gmake command, which is how Homebrew provides GNU Make on macOS. Document the requirement and the macOS gmake fallback. Signed-off-by: Chen Miao --- Documentation/doc-guide/sphinx.rst | 4 +- .../translations/zh_CN/doc-guide/sphinx.rst | 2 + Documentation/translations/zh_CN/how-to.rst | 3 +- tools/docs/sphinx-pre-install | 52 ++++++++++++++++++- 4 files changed, 58 insertions(+), 3 deletions(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 62aca56b8..d9b9e025f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -136,7 +136,9 @@ commands are printed without ``sudo``. The PDF dependen= cies are provided by the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentatio= n. 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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Docume= ntation/translations/zh_CN/doc-guide/sphinx.rst index 154142318..93f27d35a 100644 --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -114,6 +114,8 @@ PDF=E5=92=8CLaTeX=E6=9E=84=E5=BB=BA ``sudo``=E3=80=82PDF =E4=BE=9D=E8=B5=96=E9=80=9A=E8=BF=87 ``mactex`` cask = =E6=8F=90=E4=BE=9B=EF=BC=9B=E5=A6=82=E6=9E=9C=E5=8F=AA=E6=9E=84=E5=BB=BA HT= ML =E6=96=87=E6=A1=A3=EF=BC=8C=E8=AF=B7=E4=BD=BF=E7=94=A8 ``--no-pdf``=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=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 =20 Sphinx=E6=9E=84=E5=BB=BA =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/tr= anslations/zh_CN/how-to.rst index e8c91d81a..84f277124 100644 --- a/Documentation/translations/zh_CN/how-to.rst +++ b/Documentation/translations/zh_CN/how-to.rst @@ -106,7 +106,8 @@ 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 sudo=E3=80=82PDF =E6=9E=84=E5=BB=BA=E6=89=80=E9=9C=80=E7=9A=84 MacTeX =E9= =80=9A=E8=BF=87 Homebrew 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 =E5=8F=AF=E4=BB=A5=E6=89=A7=E8=A1=8C ``./tools/docs/sphinx-pre-install --n= o-pdf``=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 H= omebrew =E5=AE=89=E8=A3=85=E3=80=82 +=E5=AE=89=E8=A3=85=EF=BC=8C=E8=80=8C=E4=B8=8D=E6=98=AF=E9=80=9A=E8=BF=87 H= omebrew =E5=AE=89=E8=A3=85=E3=80=82=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 =20 =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:: diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install index 51a296cc7..079655078 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,55 @@ 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 (subprocess.CalledProcessError, FileNotFoundError): + 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.""" + make =3D self.which("make") + version =3D self.get_make_version(make) + + if version and version >=3D MIN_MAKE_VERSION: + return + + # macOS commonly has an incompatible /usr/bin/make, while Homebrew + # installs GNU Make as gmake. Also accept gmake on other systems w= hen + # it is the only compatible command available. + gmake =3D self.which("gmake") + gmake_version =3D self.get_make_version(gmake) + if gmake_version and gmake_version >=3D MIN_MAKE_VERSION: + make_name =3D os.path.basename(make) if make else "make" + gmake_name =3D os.path.basename(gmake) + make_ver =3D PythonVersion.ver_str(version) if version else "u= nknown" + gmake_ver =3D PythonVersion.ver_str(gmake_version) + print( + f"Note: {make_name} ({make_ver}) does not meet the GNU Mak= e " + f"requirement; use {gmake_name} ({gmake_ver}) instead." + ) + return + + self.deps.add_package("make", DepManager.SYSTEM_MANDATORY) + def check_perl_module(self, prog, dtype): """ Does perl have a dependency? Is it available? @@ -1535,7 +1585,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)