From mboxrd@z Thu Jan 1 00:00:00 1970 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: 8bit 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/sphinx.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. +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 --------------------------------- 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. """ + if sys.platform == "darwin": + sw_vers = self.which("sw_vers") + if sw_vers: + try: + result = self.run( + [sw_vers, "-productVersion"], + capture_output=True, + text=True, + check=True, + ) + version = result.stdout.strip() + if version: + return f"macOS {version}" + except (subprocess.CalledProcessError, FileNotFoundError): + pass + + return "macOS" + system_release = "" if self.which("lsb_release"): @@ -716,6 +734,93 @@ class SphinxDependencyChecker(MissingCheckers): return self.get_install_progs(progs, "apt-get install") + def give_macos_hints(self): + """Provide package installation hints for macOS using Homebrew.""" + progs = { + "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 = [ + os.path.expanduser("~/Library/Fonts"), + "/Library/Fonts", + "/System/Library/Fonts", + ] + pdf_fonts = { + "font-dejavu": ["DejaVuSans.ttf"], + "font-noto-sans-cjk": ["NotoSansCJK.ttc"], + } + + for package, names in pdf_fonts.items(): + files = [ + os.path.join(font_dir, name) + for font_dir in font_dirs + for name in names + ] + self.check_missing_file(files, package, DepManager.PDF_MANDATORY) + + install = self.deps.check_missing(progs) + + if self.verbose_warn_install: + self.deps.warn_install() + + if not install: + return None + + formulae = set() + casks = set() + notes = [] + for package in install.split(): + if package == "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 == "mactex-no-gui" or package.startswith("font-"): + casks.add(package) + else: + formulae.add(package) + + commands = [] + if formulae: + commands.append("\tbrew install " + " ".join(sorted(formulae))) + if casks: + commands.append("\tbrew install --cask " + " ".join(sorted(casks))) + + if not commands: + self.distro_msg = "\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 = "\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 = "\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_hints, re.compile("Mint"): self.give_debian_hints, + re.compile("macOS"): self.give_macos_hints, + re.compile("openSUSE"): self.give_opensuse_hints, re.compile("Mageia"): self.give_mageia_hints, @@ -1458,7 +1565,11 @@ class SphinxDependencyChecker(MissingCheckers): self.check_program("dot", DepManager.SYSTEM_OPTIONAL) self.check_program("convert", DepManager.SYSTEM_OPTIONAL) - 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 here. + if not (sys.platform == "darwin" and self.virtualenv and self.need_pip): + self.check_python_module("yaml") if self.pdf: self.check_program("xelatex", DepManager.PDF_MANDATORY) -- 2.50.1 (Apple Git-155)