public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-11-27 01:11:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
linux/scripts/sphinx-pre-install.py
Mauro Carvalho Chehab fb22e438b2 scripts: sphinx-pre-install: move get_system_release() 
The code at get_system_release() is actually a helper function,
independent from the actual Sphinx verification checker. Move
it to MissingCheckers class, where other checkers are present.

With that, the entire distro-specific handler logic, with
all its complexity is confined at SphinxDependencyChecker
class.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/4b42a85bbb6575bb34a58cf66019038c4afa1d5b.1754992972.git.mchehab+huawei@kernel.org
2025-08-13 10:19:17 -06:00

1368 lines
47 KiB
Python
Executable file
Raw Blame History

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (c) 2017-2025 Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
#
# pylint: disable=C0103,C0114,C0115,C0116,C0301
# pylint: disable=R0902,R0904,R0912,R0915,R1705,R1710,E1121
# Note: this script requires at least Python 3.6 to run.
# Don't add changes not compatible with it, it is meant to report
# incompatible python versions.
import argparse
import os
import re
import subprocess
import sys
from glob import glob
def parse_version(version):
"""Convert a major.minor.patch version into a tuple"""
return tuple(int(x) for x in version.split("."))
def ver_str(version):
"""Returns a version tuple as major.minor.patch"""
return ".".join([str(x) for x in version])
RECOMMENDED_VERSION = parse_version("3.4.3")
MIN_PYTHON_VERSION = parse_version("3.7")
class DepManager:
# Internal types of dependencies.
_SYS_TYPE = 0
_PHY_TYPE = 1
_PDF_TYPE = 2
# Let's define keys as a tuple with the type and mandatory/optional.
# This way, checking for optional or type is easy.
SYSTEM_MANDATORY = (_SYS_TYPE, True)
PYTHON_MANDATORY = (_PHY_TYPE, True)
PDF_MANDATORY = (_PDF_TYPE, True)
# Currently we're not using all optional types, but let's keep all
# combinations here, as we may end needing them in the future. Also,
# it allows a name() function that handles all possibilities.
SYSTEM_OPTIONAL = (_SYS_TYPE, False)
PYTHON_OPTIONAL = (_PHY_TYPE, False)
PDF_OPTIONAL = (_PDF_TYPE, True)
def __init__(self, pdf):
self.missing = {}
self.run = {}
self.need = 0
self.optional = 0
self.pdf = pdf
@staticmethod
def name(dtype):
if dtype[0] == DepManager._SYS_TYPE:
msg = "build"
elif dtype[0] == DepManager._PHY_TYPE:
msg = "Python"
else:
msg = "PDF"
if dtype[1]:
return f"ERROR: {msg} mandatory deps missing"
else:
out = f"Warning: {msg} optional deps missing"
@staticmethod
def is_optional(dtype):
return not dtype[1]
@staticmethod
def is_pdf(dtype):
if (dtype[0] == DepManager._PDF_TYPE):
return True
return False
def add_package(self, package, dtype):
is_optional = DepManager.is_optional(dtype)
self.missing[package] = dtype
if is_optional:
self.optional += 1
else:
self.need += 1
def del_package(self, package):
if package in self.missing:
del self.missing[package]
def clear_deps(self):
"""
Clear dependencies without changing needed/optional.
This is an ackward way to have a separate section to recommend
a package after system main dependencies.
TODO: rework the logic to prevent needing it
"""
self.missing = {}
def check_missing(self, progs):
self.run = {}
for prog, dtype in sorted(self.missing.items()):
# At least on some LTS distros like CentOS 7, texlive doesn't
# provide all packages we need. When such distros are
# detected, we have to disable PDF output.
#
# So, we need to ignore the packages that distros would
# need for LaTeX to work
if DepManager.is_pdf(dtype) and not self.pdf:
self.optional -= 1
continue
if not dtype in self.run:
self.run[dtype] = []
self.run[dtype].append(progs.get(prog, prog))
install = []
for dtype in self.run.keys():
install += self.run[dtype]
return " ".join(sorted(set(install)))
def warn_install(self):
output_msg = ""
for dtype in sorted(self.run.keys()):
progs = " ".join(sorted(set(self.run[dtype])))
try:
name = DepManager.name(dtype)
output_msg += f'{name}:\t{progs}\n'
except KeyError:
raise KeyError(f"ERROR!!!: invalid dtype for {progs}: {dtype}")
if output_msg:
print(f"\n{output_msg}\n")
class AncillaryMethods:
"""
Ancillary methods that checks for missing dependencies for different
types of types, like binaries, python modules, rpm deps, etc.
"""
@staticmethod
def which(prog):
for path in os.environ.get("PATH", "").split(":"):
full_path = os.path.join(path, prog)
if os.access(full_path, os.X_OK):
return full_path
return None
@staticmethod
def get_python_version(cmd):
result = SphinxDependencyChecker.run([cmd, "--version"],
capture_output=True, text=True)
version = result.stdout.strip()
match = re.search(r"(\d+\.\d+\.\d+)", version)
if match:
return parse_version(match.group(1))
print(f"Can't parse version {version}")
return (0, 0, 0)
@staticmethod
def find_python():
patterns = [
"python3.[0-9]",
"python3.[0-9][0-9]",
]
new_python_cmd = None
# Seek for a python binary newer than MIN_PYTHON_VERSION
for path in os.getenv("PATH", "").split(":"):
for pattern in patterns:
for cmd in glob(os.path.join(path, pattern)):
if os.path.isfile(cmd) and os.access(cmd, os.X_OK):
version = SphinxDependencyChecker.get_python_version(cmd)
if version >= MIN_PYTHON_VERSION:
return(cmd)
@staticmethod
def check_python():
cur_ver = sys.version_info[:3]
if cur_ver >= MIN_PYTHON_VERSION:
ver = ver_str(cur_ver)
print(f"Python version: {ver}")
# This could be useful for debugging purposes
if SphinxDependencyChecker.which("docutils"):
result = SphinxDependencyChecker.run(["docutils", "--version"],
capture_output=True, text=True)
ver = result.stdout.strip()
match = re.search(r"(\d+\.\d+\.\d+)", ver)
if match:
ver = match.group(1)
print(f"Docutils version: {ver}")
return
python_ver = ver_str(cur_ver)
new_python_cmd = SphinxDependencyChecker.find_python()
if not new_python_cmd:
print(f"ERROR: Python version {python_ver} is not spported anymore")
print(f" Can't find a new version. This script may fail")
return
# Restart script using the newer version
script_path = os.path.abspath(sys.argv[0])
args = [new_python_cmd, script_path] + sys.argv[1:]
print(f"Python {python_ver} not supported. Changing to {new_python_cmd}")
try:
os.execv(new_python_cmd, args)
except OSError as e:
sys.exit(f"Failed to restart with {new_python_cmd}: {e}")
@staticmethod
def run(*args, **kwargs):
"""Excecute a command, hiding its output by default"""
capture_output = kwargs.pop('capture_output', False)
if capture_output:
if 'stdout' not in kwargs:
kwargs['stdout'] = subprocess.PIPE
if 'stderr' not in kwargs:
kwargs['stderr'] = subprocess.PIPE
else:
if 'stdout' not in kwargs:
kwargs['stdout'] = subprocess.DEVNULL
if 'stderr' not in kwargs:
kwargs['stderr'] = subprocess.DEVNULL
# Don't break with older Python versions
if 'text' in kwargs and sys.version_info < (3, 7):
kwargs['universal_newlines'] = kwargs.pop('text')
return subprocess.run(*args, **kwargs)
class MissingCheckers(AncillaryMethods):
def __init__(self, args, texlive):
self.pdf = args.pdf
self.virtualenv = args.virtualenv
self.version_check = args.version_check
self.texlive = texlive
self.deps = DepManager(self.pdf)
self.need_symlink = 0
self.need_sphinx = 0
self.verbose_warn_install = 1
self.virtenv_dir = ""
self.install = ""
#
# Methods to check if a feature exists
#
def check_missing_file(self, files, package, dtype):
for f in files:
if os.path.exists(f):
return
self.deps.add_package(package, dtype)
def check_program(self, prog, dtype):
found = self.which(prog)
if found:
return found
self.deps.add_package(prog, dtype)
return None
def check_perl_module(self, prog, dtype):
# While testing with lxc download template, one of the
# distros (Oracle) didn't have perl - nor even an option to install
# before installing oraclelinux-release-el9 package.
#
# Check it before running an error. If perl is not there,
# add it as a mandatory package, as some parts of the doc builder
# needs it.
if not self.which("perl"):
self.deps.add_package("perl", DepManager.SYSTEM_MANDATORY)
self.deps.add_package(prog, dtype)
return
try:
self.run(["perl", f"-M{prog}", "-e", "1"], check=True)
except subprocess.CalledProcessError:
self.deps.add_package(prog, dtype)
def check_python_module(self, module, is_optional=False):
if is_optional:
dtype = DepManager.PYTHON_OPTIONAL
else:
dtype = DepManager.PYTHON_MANDATORY
try:
self.run([self.python_cmd, "-c", f"import {module}"], check=True)
except subprocess.CalledProcessError:
self.deps.add_package(module, dtype)
def check_rpm_missing(self, pkgs, dtype):
for prog in pkgs:
try:
self.run(["rpm", "-q", prog], check=True)
except subprocess.CalledProcessError:
self.deps.add_package(prog, dtype)
def check_pacman_missing(self, pkgs, dtype):
for prog in pkgs:
try:
self.run(["pacman", "-Q", prog], check=True)
except subprocess.CalledProcessError:
self.deps.add_package(prog, dtype)
def check_missing_tex(self, is_optional=False):
if is_optional:
dtype = DepManager.PDF_OPTIONAL
else:
dtype = DepManager.PDF_MANDATORY
kpsewhich = self.which("kpsewhich")
for prog, package in self.texlive.items():
# If kpsewhich is not there, just add it to deps
if not kpsewhich:
self.deps.add_package(package, dtype)
continue
# Check if the package is needed
try:
result = self.run(
[kpsewhich, prog], stdout=subprocess.PIPE, text=True, check=True
)
# Didn't find. Add it
if not result.stdout.strip():
self.deps.add_package(package, dtype)
except subprocess.CalledProcessError:
# kpsewhich returned an error. Add it, just in case
self.deps.add_package(package, dtype)
def get_sphinx_fname(self):
if "SPHINXBUILD" in os.environ:
return os.environ["SPHINXBUILD"]
fname = "sphinx-build"
if self.which(fname):
return fname
fname = "sphinx-build-3"
if self.which(fname):
self.need_symlink = 1
return fname
return ""
def get_sphinx_version(self, cmd):
try:
result = self.run([cmd, "--version"],
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True, check=True)
except (subprocess.CalledProcessError, FileNotFoundError):
return None
for line in result.stdout.split("\n"):
match = re.match(r"^sphinx-build\s+([\d\.]+)(?:\+(?:/[\da-f]+)|b\d+)?\s*$", line)
if match:
return parse_version(match.group(1))
match = re.match(r"^Sphinx.*\s+([\d\.]+)\s*$", line)
if match:
return parse_version(match.group(1))
def check_sphinx(self, conf):
try:
with open(conf, "r", encoding="utf-8") as f:
for line in f:
match = re.match(r"^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]", line)
if match:
self.min_version = parse_version(match.group(1))
break
except IOError:
sys.exit(f"Can't open {self.conf}")
if not self.min_version:
sys.exit(f"Can't get needs_sphinx version from {self.conf}")
self.virtenv_dir = self.virtenv_prefix[0] + "latest"
sphinx = self.get_sphinx_fname()
if not sphinx:
self.need_sphinx = 1
return
self.cur_version = self.get_sphinx_version(sphinx)
if not self.cur_version:
sys.exit(f"{sphinx} didn't return its version")
if self.cur_version < self.min_version:
curver = ver_str(self.cur_version)
minver = ver_str(self.min_version)
print(f"ERROR: Sphinx version is {curver}. It should be >= {minver}")
self.need_sphinx = 1
return
# On version check mode, just assume Sphinx has all mandatory deps
if self.version_check and self.cur_version >= RECOMMENDED_VERSION:
sys.exit(0)
def catcheck(self, filename):
if os.path.exists(filename):
with open(filename, "r", encoding="utf-8") as f:
return f.read().strip()
return ""
def check_missing(self, progs):
self.install += self.deps.check_missing(progs)
if self.verbose_warn_install:
self.deps.warn_install()
if not self.deps.need and not self.deps.optional:
return False
return True
def get_system_release(self):
"""
Determine the system type. There's no unique way that would work
with all distros with a minimal package install. So, several
methods are used here.
By default, it will use lsb_release function. If not available, it will
fail back to reading the known different places where the distro name
is stored.
Several modern distros now have /etc/os-release, which usually have
a decent coverage.
"""
system_release = ""
if self.which("lsb_release"):
result = self.run(["lsb_release", "-d"], capture_output=True, text=True)
system_release = result.stdout.replace("Description:", "").strip()
release_files = [
"/etc/system-release",
"/etc/redhat-release",
"/etc/lsb-release",
"/etc/gentoo-release",
]
if not system_release:
for f in release_files:
system_release = self.catcheck(f)
if system_release:
break
# This seems more common than LSB these days
if not system_release:
os_var = {}
try:
with open("/etc/os-release", "r", encoding="utf-8") as f:
for line in f:
match = re.match(r"^([\w\d\_]+)=\"?([^\"]*)\"?\n", line)
if match:
os_var[match.group(1)] = match.group(2)
system_release = os_var.get("NAME", "")
if "VERSION_ID" in os_var:
system_release += " " + os_var["VERSION_ID"]
elif "VERSION" in os_var:
system_release += " " + os_var["VERSION"]
except IOError:
pass
if not system_release:
system_release = self.catcheck("/etc/issue")
system_release = system_release.strip()
return system_release
class SphinxDependencyChecker(MissingCheckers):
def __init__(self, args):
# List of required texlive packages on Fedora and OpenSuse
texlive = {
"amsfonts.sty": "texlive-amsfonts",
"amsmath.sty": "texlive-amsmath",
"amssymb.sty": "texlive-amsfonts",
"amsthm.sty": "texlive-amscls",
"anyfontsize.sty": "texlive-anyfontsize",
"atbegshi.sty": "texlive-oberdiek",
"bm.sty": "texlive-tools",
"capt-of.sty": "texlive-capt-of",
"cmap.sty": "texlive-cmap",
"ctexhook.sty": "texlive-ctex",
"ecrm1000.tfm": "texlive-ec",
"eqparbox.sty": "texlive-eqparbox",
"eu1enc.def": "texlive-euenc",
"fancybox.sty": "texlive-fancybox",
"fancyvrb.sty": "texlive-fancyvrb",
"float.sty": "texlive-float",
"fncychap.sty": "texlive-fncychap",
"footnote.sty": "texlive-mdwtools",
"framed.sty": "texlive-framed",
"luatex85.sty": "texlive-luatex85",
"multirow.sty": "texlive-multirow",
"needspace.sty": "texlive-needspace",
"palatino.sty": "texlive-psnfss",
"parskip.sty": "texlive-parskip",
"polyglossia.sty": "texlive-polyglossia",
"tabulary.sty": "texlive-tabulary",
"threeparttable.sty": "texlive-threeparttable",
"titlesec.sty": "texlive-titlesec",
"ucs.sty": "texlive-ucs",
"upquote.sty": "texlive-upquote",
"wrapfig.sty": "texlive-wrapfig",
}
super().__init__(args, texlive)
self.need_pip = 0
self.rec_sphinx_upgrade = 0
self.system_release = self.get_system_release()
self.python_cmd = ""
self.activate_cmd = ""
# Some distros may not have a Sphinx shipped package compatible with
# our minimal requirements
self.package_supported = True
# Recommend a new python version
self.recommend_python = None
# Certain hints are meant to be shown only once
self.first_hint = True
self.min_version = (0, 0, 0)
self.cur_version = (0, 0, 0)
self.latest_avail_ver = (0, 0, 0)
self.venv_ver = (0, 0, 0)
prefix = os.environ.get("srctree", ".") + "/"
self.conf = prefix + "Documentation/conf.py"
self.requirement_file = prefix + "Documentation/sphinx/requirements.txt"
self.virtenv_prefix = ["sphinx_", "Sphinx_" ]
#
# Distro-specific hints methods
#
def give_debian_hints(self):
progs = {
"Pod::Usage": "perl-modules",
"convert": "imagemagick",
"dot": "graphviz",
"ensurepip": "python3-venv",
"python-sphinx": "python3-sphinx",
"rsvg-convert": "librsvg2-bin",
"virtualenv": "virtualenv",
"xelatex": "texlive-xetex",
"yaml": "python3-yaml",
}
if self.pdf:
pdf_pkgs = {
"texlive-lang-chinese": [
"/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty",
],
"fonts-dejavu": [
"/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
],
"fonts-noto-cjk": [
"/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc",
],
}
for package, files in pdf_pkgs.items():
self.check_missing_file(files, package, DepManager.PDF_MANDATORY)
self.check_program("dvipng", DepManager.PDF_MANDATORY)
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print(f"\n\tsudo apt-get install {self.install}")
def give_redhat_hints(self):
progs = {
"Pod::Usage": "perl-Pod-Usage",
"convert": "ImageMagick",
"dot": "graphviz",
"python-sphinx": "python3-sphinx",
"rsvg-convert": "librsvg2-tools",
"virtualenv": "python3-virtualenv",
"xelatex": "texlive-xetex-bin",
"yaml": "python3-pyyaml",
}
fedora_tex_pkgs = [
"dejavu-sans-fonts",
"dejavu-sans-mono-fonts",
"dejavu-serif-fonts",
"texlive-collection-fontsrecommended",
"texlive-collection-latex",
"texlive-xecjk",
]
fedora = False
rel = None
match = re.search(r"(release|Linux)\s+(\d+)", self.system_release)
if match:
rel = int(match.group(2))
if not rel:
print("Couldn't identify release number")
self.pdf = False
elif re.search("Fedora", self.system_release):
# Fedora 38 and upper use this CJK font
noto_sans_redhat = "google-noto-sans-cjk-fonts"
fedora = True
else:
# Almalinux, CentOS, RHEL, ...
# at least up to version 9 (and Fedora < 38), that's the CJK font
noto_sans_redhat = "google-noto-sans-cjk-ttc-fonts"
progs["virtualenv"] = "python-virtualenv"
if not rel or rel < 8:
print("ERROR: Distro not supported. Too old?")
return
# RHEL 8 uses Python 3.6, which is not compatible with
# the build system anymore. Suggest Python 3.11
if rel == 8:
self.deps.add_package("python39", DepManager.SYSTEM_MANDATORY)
self.recommend_python = True
if self.first_hint:
print("Note: RHEL-based distros typically require extra repositories.\n" \
"For most, enabling epel and crb are enough:\n" \
"\tsudo dnf install -y epel-release", \
"\tsudo dnf config-manager --set-enabled crb\n" \
"Yet, some may have other required repositories. Those commands could be useful:\n" \
"\tsudo dnf repolist all\n" \
"\tsudo dnf repoquery --available --info <pkgs>\n",
"\tsudo dnf config-manager --set-enabled '*' # enable all - probably not what you want")
self.first_hint = False
if self.pdf:
pdf_pkgs = [
"/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc",
]
self.check_missing_file(pdf_pkgs, noto_sans_redhat, DepManager.PDF_MANDATORY)
self.check_rpm_missing(fedora_tex_pkgs, DepManager.PDF_MANDATORY)
self.check_missing_tex(DepManager.PDF_MANDATORY)
# There's no texlive-ctex on RHEL 8 repositories. This will
# likely affect CJK pdf build only.
if not fedora and rel == 8:
self.deps.del_package("texlive-ctex")
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print(f"\n\tsudo dnf install -y {self.install}")
def give_opensuse_hints(self):
progs = {
"Pod::Usage": "perl-Pod-Usage",
"convert": "ImageMagick",
"dot": "graphviz",
"python-sphinx": "python3-sphinx",
"virtualenv": "python3-virtualenv",
"xelatex": "texlive-xetex-bin",
"yaml": "python3-pyyaml",
}
suse_tex_pkgs = [
"texlive-babel-english",
"texlive-caption",
"texlive-colortbl",
"texlive-courier",
"texlive-dvips",
"texlive-helvetic",
"texlive-makeindex",
"texlive-metafont",
"texlive-metapost",
"texlive-palatino",
"texlive-preview",
"texlive-times",
"texlive-zapfchan",
"texlive-zapfding",
]
progs["latexmk"] = "texlive-latexmk-bin"
match = re.search(r"(Leap)\s+(\d+).(\d)", self.system_release)
if match:
rel = int(match.group(2))
# Leap 15.x uses Python 3.6, which is not compatible with
# the build system anymore. Suggest Python 3.11
if rel == 15:
if not self.which(self.python_cmd):
self.recommend_python = True
self.deps.add_package(self.python_cmd, DepManager.SYSTEM_MANDATORY)
progs.update({
"python-sphinx": "python311-Sphinx",
"virtualenv": "python311-virtualenv",
"yaml": "python311-PyYAML",
})
else:
# Tumbleweed defaults to Python 3.11
progs.update({
"python-sphinx": "python313-Sphinx",
"virtualenv": "python313-virtualenv",
"yaml": "python313-PyYAML",
})
# FIXME: add support for installing CJK fonts
#
# I tried hard, but was unable to find a way to install
# "Noto Sans CJK SC" on openSUSE
if self.pdf:
self.check_rpm_missing(suse_tex_pkgs, DepManager.PDF_MANDATORY)
if self.pdf:
self.check_missing_tex()
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print(f"\n\tsudo zypper install --no-recommends {self.install}")
def give_mageia_hints(self):
progs = {
"Pod::Usage": "perl-Pod-Usage",
"convert": "ImageMagick",
"dot": "graphviz",
"python-sphinx": "python3-sphinx",
"rsvg-convert": "librsvg2",
"virtualenv": "python3-virtualenv",
"xelatex": "texlive",
"yaml": "python3-yaml",
}
tex_pkgs = [
"texlive-fontsextra",
]
if re.search(r"OpenMandriva", self.system_release):
packager_cmd = "dnf install"
noto_sans = "noto-sans-cjk-fonts"
tex_pkgs = ["texlive-collection-fontsextra"]
# Tested on OpenMandriva Lx 4.3
progs["convert"] = "imagemagick"
progs["yaml"] = "python-pyyaml"
else:
packager_cmd = "urpmi"
noto_sans = "google-noto-sans-cjk-ttc-fonts"
progs["latexmk"] = "texlive-collection-basic"
if self.pdf:
pdf_pkgs = [
"/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/TTF/NotoSans-Regular.ttf",
]
self.check_missing_file(pdf_pkgs, noto_sans, DepManager.PDF_MANDATORY)
self.check_rpm_missing(tex_pkgs, DepManager.PDF_MANDATORY)
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print(f"\n\tsudo {packager_cmd} {self.install}")
def give_arch_linux_hints(self):
progs = {
"convert": "imagemagick",
"dot": "graphviz",
"latexmk": "texlive-core",
"rsvg-convert": "extra/librsvg",
"virtualenv": "python-virtualenv",
"xelatex": "texlive-xetex",
"yaml": "python-yaml",
}
archlinux_tex_pkgs = [
"texlive-core",
"texlive-latexextra",
"ttf-dejavu",
]
if self.pdf:
self.check_pacman_missing(archlinux_tex_pkgs, DepManager.PDF_MANDATORY)
self.check_missing_file(
["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
"noto-fonts-cjk",
2,
)
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print(f"\n\tsudo pacman -S {self.install}")
def give_gentoo_hints(self):
progs = {
"convert": "media-gfx/imagemagick",
"dot": "media-gfx/graphviz",
"rsvg-convert": "gnome-base/librsvg",
"virtualenv": "dev-python/virtualenv",
"xelatex": "dev-texlive/texlive-xetex media-fonts/dejavu",
"yaml": "dev-python/pyyaml",
"python-sphinx": "dev-python/sphinx",
}
if self.pdf:
pdf_pkgs = {
"media-fonts/dejavu": [
"/usr/share/fonts/dejavu/DejaVuSans.ttf",
],
"media-fonts/noto-cjk": [
"/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
"/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc",
],
}
for package, files in pdf_pkgs.items():
self.check_missing_file(files, package, DepManager.PDF_MANDATORY)
if self.check_missing(progs):
return
if self.verbose_warn_install:
print("You should run:")
print("\n")
# Handling dependencies is a nightmare, as Gentoo refuses to emerge
# some packages if there's no package.use file describing them.
# To make it worse, compilation flags shall also be present there
# for some packages. If USE is not perfect, error/warning messages
# like those are shown:
#
# !!! The following binary packages have been ignored due to non matching USE:
#
# =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_13 qt6 svg
# =media-gfx/graphviz-12.2.1-r1 X pdf python_single_target_python3_12 -python_single_target_python3_13 qt6 svg
# =media-gfx/graphviz-12.2.1-r1 X pdf qt6 svg
# =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 qt6 svg
# =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 python_single_target_python3_12 -python_single_target_python3_13 qt6 svg
# =media-fonts/noto-cjk-20190416 X
# =app-text/texlive-core-2024-r1 X cjk -xetex
# =app-text/texlive-core-2024-r1 X -xetex
# =app-text/texlive-core-2024-r1 -xetex
# =dev-libs/zziplib-0.13.79-r1 sdl
#
# And will ignore such packages, installing the remaining ones. That
# affects mostly the image extension and PDF generation.
# Package dependencies and the minimal needed args:
portages = {
"graphviz": "media-gfx/graphviz",
"imagemagick": "media-gfx/imagemagick",
"media-libs": "media-libs/harfbuzz icu",
"media-fonts": "media-fonts/noto-cjk",
"texlive": "app-text/texlive-core xetex",
"zziblib": "dev-libs/zziplib sdl",
}
if self.first_hint:
use_base = "/etc/portage/package.use"
files = glob(f"{use_base}/*")
for fname, portage in portages.items():
install = False
while install == False:
if not files:
# No files under package.usage. Install all
install = True
break
args = portage.split(" ")
name = args.pop(0)
cmd = ["grep", "-l", "-E", rf"^{name}\b" ] + files
result = self.run(cmd, stdout=subprocess.PIPE, text=True)
if result.returncode or not result.stdout.strip():
# File containing portage name not found
install = True
break
# Ensure that needed USE flags are present
if args:
match_fname = result.stdout.strip()
with open(match_fname, 'r', encoding='utf8',
errors='backslashreplace') as fp:
for line in fp:
for arg in args:
if arg.startswith("-"):
continue
if not re.search(rf"\s*{arg}\b", line):
# Needed file argument not found
install = True
break
# Everything looks ok, don't install
break
# emit a code to setup missing USE
if install:
print(f"\tsudo su -c 'echo \"{portage}\" > {use_base}/{fname}'")
self.first_hint = False
# Now, we can use emerge and let it respect USE
print(f"\tsudo emerge --ask --changed-use --binpkg-respect-use=y {self.install}")
#
# Dispatch the check to an os_specific hinter
#
def check_distros(self):
# OS-specific hints logic
os_hints = {
re.compile("Red Hat Enterprise Linux"): self.give_redhat_hints,
re.compile("Fedora"): self.give_redhat_hints,
re.compile("AlmaLinux"): self.give_redhat_hints,
re.compile("Amazon Linux"): self.give_redhat_hints,
re.compile("CentOS"): self.give_redhat_hints,
re.compile("openEuler"): self.give_redhat_hints,
re.compile("Oracle Linux Server"): self.give_redhat_hints,
re.compile("Rocky Linux"): self.give_redhat_hints,
re.compile("Springdale Open Enterprise"): self.give_redhat_hints,
re.compile("Ubuntu"): self.give_debian_hints,
re.compile("Debian"): self.give_debian_hints,
re.compile("Devuan"): self.give_debian_hints,
re.compile("Kali"): self.give_debian_hints,
re.compile("Mint"): self.give_debian_hints,
re.compile("openSUSE"): self.give_opensuse_hints,
re.compile("Mageia"): self.give_mageia_hints,
re.compile("OpenMandriva"): self.give_mageia_hints,
re.compile("Arch Linux"): self.give_arch_linux_hints,
re.compile("Gentoo"): self.give_gentoo_hints,
}
# If the OS is detected, use per-OS hint logic
for regex, os_hint in os_hints.items():
if regex.search(self.system_release):
os_hint()
return
#
# Fall-back to generic hint code for other distros
# That's far from ideal, specially for LaTeX dependencies.
#
progs = {"sphinx-build": "sphinx"}
if self.pdf:
self.check_missing_tex()
self.check_missing(progs)
print(f"I don't know distro {self.system_release}.")
print("So, I can't provide you a hint with the install procedure.")
print("There are likely missing dependencies.")
#
# Common dependencies
#
def deactivate_help(self):
print("\n If you want to exit the virtualenv, you can use:")
print("\tdeactivate")
def get_virtenv(self):
cwd = os.getcwd()
activates = []
# Add all sphinx prefixes with possible version numbers
for p in self.virtenv_prefix:
activates += glob(f"{cwd}/{p}[0-9]*/bin/activate")
activates.sort(reverse=True, key=str.lower)
# Place sphinx_latest first, if it exists
for p in self.virtenv_prefix:
activates = glob(f"{cwd}/{p}*latest/bin/activate") + activates
ver = (0, 0, 0)
for f in activates:
# Discard too old Sphinx virtual environments
match = re.search(r"(\d+)\.(\d+)\.(\d+)", f)
if match:
ver = (int(match.group(1)), int(match.group(2)), int(match.group(3)))
if ver < self.min_version:
continue
sphinx_cmd = f.replace("activate", "sphinx-build")
if not os.path.isfile(sphinx_cmd):
continue
ver = self.get_sphinx_version(sphinx_cmd)
if not ver:
venv_dir = f.replace("/bin/activate", "")
print(f"Warning: virtual environment {venv_dir} is not working.\n" \
"Python version upgrade? Remove it with:\n\n" \
"\trm -rf {venv_dir}\n\n")
else:
if self.need_sphinx and ver >= self.min_version:
return (f, ver)
elif parse_version(ver) > self.cur_version:
return (f, ver)
return ("", ver)
def recommend_sphinx_upgrade(self):
# Avoid running sphinx-builds from venv if cur_version is good
if self.cur_version and self.cur_version >= RECOMMENDED_VERSION:
self.latest_avail_ver = self.cur_version
return None
# Get the highest version from sphinx_*/bin/sphinx-build and the
# corresponding command to activate the venv/virtenv
self.activate_cmd, self.venv_ver = self.get_virtenv()
# Store the highest version from Sphinx existing virtualenvs
if self.activate_cmd and self.venv_ver > self.cur_version:
self.latest_avail_ver = self.venv_ver
else:
if self.cur_version:
self.latest_avail_ver = self.cur_version
else:
self.latest_avail_ver = (0, 0, 0)
# As we don't know package version of Sphinx, and there's no
# virtual environments, don't check if upgrades are needed
if not self.virtualenv:
if not self.latest_avail_ver:
return None
return self.latest_avail_ver
# Either there are already a virtual env or a new one should be created
self.need_pip = 1
if not self.latest_avail_ver:
return None
# Return if the reason is due to an upgrade or not
if self.latest_avail_ver != (0, 0, 0):
if self.latest_avail_ver < RECOMMENDED_VERSION:
self.rec_sphinx_upgrade = 1
return self.latest_avail_ver
def recommend_package(self):
print("\n2) As a package with:")
old_need = self.deps.need
old_optional = self.deps.optional
self.pdf = False
self.optional = 0
self.install = ""
old_verbose = self.verbose_warn_install
self.verbose_warn_install = 0
self.deps.clear_deps()
self.deps.add_package("python-sphinx", DepManager.PYTHON_MANDATORY)
self.check_distros()
self.need = old_need
self.optional = old_optional
self.verbose_warn_install = old_verbose
def recommend_sphinx_version(self, virtualenv_cmd):
# The logic here is complex, as it have to deal with different versions:
# - minimal supported version;
# - minimal PDF version;
# - recommended version.
# It also needs to work fine with both distro's package and venv/virtualenv
if self.recommend_python:
print("\nPython version is incompatible with doc build.\n" \
"Please upgrade it and re-run.\n")
return
# Version is OK. Nothing to do.
if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION:
return
if self.latest_avail_ver:
latest_avail_ver = ver_str(self.latest_avail_ver)
if not self.need_sphinx:
# sphinx-build is present and its version is >= $min_version
# only recommend enabling a newer virtenv version if makes sense.
if self.latest_avail_ver and self.latest_avail_ver > self.cur_version:
print(f"\nYou may also use the newer Sphinx version {latest_avail_ver} with:")
if f"{self.virtenv_prefix}" in os.getcwd():
print("\tdeactivate")
print(f"\t. {self.activate_cmd}")
self.deactivate_help()
return
if self.latest_avail_ver and self.latest_avail_ver >= RECOMMENDED_VERSION:
return
if not self.virtualenv:
# No sphinx either via package or via virtenv. As we can't
# Compare the versions here, just return, recommending the
# user to install it from the package distro.
if not self.latest_avail_ver or self.latest_avail_ver == (0, 0, 0):
return
# User doesn't want a virtenv recommendation, but he already
# installed one via virtenv with a newer version.
# So, print commands to enable it
if self.latest_avail_ver > self.cur_version:
print(f"\nYou may also use the Sphinx virtualenv version {latest_avail_ver} with:")
if f"{self.virtenv_prefix}" in os.getcwd():
print("\tdeactivate")
print(f"\t. {self.activate_cmd}")
self.deactivate_help()
return
print("\n")
else:
if self.need_sphinx:
self.deps.need += 1
# Suggest newer versions if current ones are too old
if self.latest_avail_ver and self.latest_avail_ver >= self.min_version:
if self.latest_avail_ver >= RECOMMENDED_VERSION:
print(f"\nNeed to activate Sphinx (version {latest_avail_ver}) on virtualenv with:")
print(f"\t. {self.activate_cmd}")
self.deactivate_help()
return
# Version is above the minimal required one, but may be
# below the recommended one. So, print warnings/notes
if self.latest_avail_ver < RECOMMENDED_VERSION:
print(f"Warning: It is recommended at least Sphinx version {RECOMMENDED_VERSION}.")
# At this point, either it needs Sphinx or upgrade is recommended,
# both via pip
if self.rec_sphinx_upgrade:
if not self.virtualenv:
print("Instead of install/upgrade Python Sphinx pkg, you could use pip/pypi with:\n\n")
else:
print("To upgrade Sphinx, use:\n\n")
else:
print("\nSphinx needs to be installed either:\n1) via pip/pypi with:\n")
if not virtualenv_cmd:
print(" Currently not possible.\n")
print(" Please upgrade Python to a newer version and run this script again")
else:
print(f"\t{virtualenv_cmd} {self.virtenv_dir}")
print(f"\t. {self.virtenv_dir}/bin/activate")
print(f"\tpip install -r {self.requirement_file}")
self.deactivate_help()
if self.package_supported:
self.recommend_package()
print("\n" \
" Please note that Sphinx currentlys produce false-positive\n" \
" warnings when the same name is used for more than one type (functions,\n" \
" structs, enums,...). This is known Sphinx bug. For more details, see:\n" \
"\thttps://github.com/sphinx-doc/sphinx/pull/8313")
def check_needs(self):
self.python_cmd = sys.executable
# Check if Sphinx is already accessible from current environment
self.check_sphinx(self.conf)
if self.system_release:
print(f"Detected OS: {self.system_release}.")
else:
print("Unknown OS")
if self.cur_version != (0, 0, 0):
ver = ver_str(self.cur_version)
print(f"Sphinx version: {ver}\n")
# Check the type of virtual env, depending on Python version
virtualenv_cmd = None
if sys.version_info < MIN_PYTHON_VERSION:
min_ver = ver_str(MIN_PYTHON_VERSION)
print(f"ERROR: at least python {min_ver} is required to build the kernel docs")
self.need_sphinx = 1
self.venv_ver = self.recommend_sphinx_upgrade()
if self.need_pip:
if sys.version_info < MIN_PYTHON_VERSION:
self.need_pip = False
print("Warning: python version is not supported.")
else:
virtualenv_cmd = f"{self.python_cmd} -m venv"
self.check_python_module("ensurepip")
# Check for needed programs/tools
self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY)
self.check_program("make", DepManager.SYSTEM_MANDATORY)
self.check_program("gcc", DepManager.SYSTEM_MANDATORY)
self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
self.check_python_module("yaml")
if self.pdf:
self.check_program("xelatex", DepManager.PDF_MANDATORY)
self.check_program("rsvg-convert", DepManager.PDF_MANDATORY)
self.check_program("latexmk", DepManager.PDF_MANDATORY)
# Do distro-specific checks and output distro-install commands
self.check_distros()
if not self.python_cmd:
if self.need == 1:
sys.exit("Can't build as 1 mandatory dependency is missing")
elif self.need:
sys.exit(f"Can't build as {self.need} mandatory dependencies are missing")
# Check if sphinx-build is called sphinx-build-3
if self.need_symlink:
sphinx_path = self.which("sphinx-build-3")
if sphinx_path:
print(f"\tsudo ln -sf {sphinx_path} /usr/bin/sphinx-build\n")
self.recommend_sphinx_version(virtualenv_cmd)
print("")
if not self.optional:
print("All optional dependencies are met.")
if self.need == 1:
sys.exit("Can't build as 1 mandatory dependency is missing")
elif self.need:
sys.exit(f"Can't build as {self.need} mandatory dependencies are missing")
print("Needed package dependencies are met.")
DESCRIPTION = """
Process some flags related to Sphinx installation and documentation build.
"""
def main():
parser = argparse.ArgumentParser(description=DESCRIPTION)
parser.add_argument(
"--no-virtualenv",
action="store_false",
dest="virtualenv",
help="Recommend installing Sphinx instead of using a virtualenv",
)
parser.add_argument(
"--no-pdf",
action="store_false",
dest="pdf",
help="Don't check for dependencies required to build PDF docs",
)
parser.add_argument(
"--version-check",
action="store_true",
dest="version_check",
help="If version is compatible, don't check for missing dependencies",
)
args = parser.parse_args()
checker = SphinxDependencyChecker(args)
checker.check_python()
checker.check_needs()
if __name__ == "__main__":
main()
Reference in a new issue View git blame Copy permalink