mirror of
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-11-27 01:11:31 +00:00
42e3f9f360
According with its website: https://scientificlinux.org/ Scientific Linux reached end of life in June 30, 2024. Also, it was based on RHEL 7, which is not compatible with our build system anymore. So, drop support for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dde5e0c95017022840f8a522ce44759e51f52aa1.1754992972.git.mchehab+huawei@kernel.org
1178 lines
40 KiB
Python
Executable file
1178 lines
40 KiB
Python
Executable file
#!/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 SphinxDependencyChecker:
|
|
# 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",
|
|
}
|
|
|
|
def __init__(self, args):
|
|
self.pdf = args.pdf
|
|
self.virtualenv = args.virtualenv
|
|
self.version_check = args.version_check
|
|
|
|
self.missing = {}
|
|
|
|
self.need = 0
|
|
self.optional = 0
|
|
self.need_symlink = 0
|
|
self.need_sphinx = 0
|
|
self.need_pip = 0
|
|
self.rec_sphinx_upgrade = 0
|
|
self.verbose_warn_install = 1
|
|
|
|
self.system_release = ""
|
|
self.install = ""
|
|
self.virtenv_dir = ""
|
|
self.python_cmd = ""
|
|
self.activate_cmd = ""
|
|
|
|
# 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_" ]
|
|
|
|
#
|
|
# Ancillary methods that don't depend on self
|
|
#
|
|
|
|
@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)
|
|
|
|
#
|
|
# Methods to check if a feature exists
|
|
#
|
|
|
|
# Note: is_optional has 3 states:
|
|
# - 0: mandatory
|
|
# - 1: optional, but nice to have
|
|
# - 2: LaTeX optional - pdf builds without it, but may have visual impact
|
|
|
|
def check_missing(self, progs):
|
|
for prog, is_optional 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 is_optional == 2 and not self.pdf:
|
|
self.optional -= 1
|
|
continue
|
|
|
|
if self.verbose_warn_install:
|
|
if is_optional:
|
|
print(f'Warning: better to also install "{prog}".')
|
|
else:
|
|
print(f'ERROR: please install "{prog}", otherwise, build won\'t work.')
|
|
|
|
self.install += " " + progs.get(prog, prog)
|
|
|
|
self.install = self.install.lstrip()
|
|
|
|
def add_package(self, package, is_optional):
|
|
self.missing[package] = is_optional
|
|
if is_optional:
|
|
self.optional += 1
|
|
else:
|
|
self.need += 1
|
|
|
|
def check_missing_file(self, files, package, is_optional):
|
|
for f in files:
|
|
if os.path.exists(f):
|
|
return
|
|
self.add_package(package, is_optional)
|
|
|
|
def check_program(self, prog, is_optional):
|
|
found = self.which(prog)
|
|
if found:
|
|
return found
|
|
|
|
self.add_package(prog, is_optional)
|
|
|
|
return None
|
|
|
|
def check_perl_module(self, prog, is_optional):
|
|
# 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.add_package("perl", 0)
|
|
self.add_package(prog, is_optional)
|
|
return
|
|
|
|
try:
|
|
self.run(["perl", f"-M{prog}", "-e", "1"], check=True)
|
|
except subprocess.CalledProcessError:
|
|
self.add_package(prog, is_optional)
|
|
|
|
def check_python_module(self, module, is_optional):
|
|
# FIXME: is it needed at the Python version? Maybe due to venv?
|
|
if not self.python_cmd:
|
|
return
|
|
|
|
try:
|
|
self.run([self.python_cmd, "-c", f"import {module}"], check=True)
|
|
except subprocess.CalledProcessError:
|
|
self.add_package(module, is_optional)
|
|
|
|
def check_rpm_missing(self, pkgs, is_optional):
|
|
for prog in pkgs:
|
|
try:
|
|
self.run(["rpm", "-q", prog], check=True)
|
|
except subprocess.CalledProcessError:
|
|
self.add_package(prog, is_optional)
|
|
|
|
def check_pacman_missing(self, pkgs, is_optional):
|
|
for prog in pkgs:
|
|
try:
|
|
self.run(["pacman", "-Q", prog], check=True)
|
|
except subprocess.CalledProcessError:
|
|
self.add_package(prog, is_optional)
|
|
|
|
def check_missing_tex(self, is_optional):
|
|
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.add_package(package, is_optional)
|
|
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.add_package(package, is_optional)
|
|
|
|
except subprocess.CalledProcessError:
|
|
# kpsewhich returned an error. Add it, just in case
|
|
self.add_package(package, is_optional)
|
|
|
|
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):
|
|
try:
|
|
with open(self.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 ""
|
|
|
|
#
|
|
# 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, 2)
|
|
|
|
self.check_program("dvipng", 2)
|
|
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
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",
|
|
}
|
|
|
|
fedora26_opt_pkgs = [
|
|
"graphviz-gd", # Fedora 26: needed for PDF support
|
|
]
|
|
|
|
fedora_tex_pkgs = [
|
|
"dejavu-sans-fonts",
|
|
"dejavu-sans-mono-fonts",
|
|
"dejavu-serif-fonts",
|
|
"texlive-collection-fontsrecommended",
|
|
"texlive-collection-latex",
|
|
"texlive-xecjk",
|
|
]
|
|
|
|
old = 0
|
|
rel = None
|
|
pkg_manager = "dnf"
|
|
|
|
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")
|
|
old = 1
|
|
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"
|
|
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:
|
|
old = 1
|
|
self.pdf = False
|
|
|
|
print("ERROR: Distro not supported. Too old?")
|
|
return
|
|
|
|
# TODO: check if RHEL8 still works.
|
|
# On my tests with docker "redhat/ubi8" image, there's no
|
|
# python3-sphinx (or similar) package. It comes with Python 3.6,
|
|
# but there are other python packages over there, so it may be
|
|
# possible to work with venv.
|
|
|
|
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, 2)
|
|
|
|
if not old:
|
|
self.check_rpm_missing(fedora26_opt_pkgs, 2)
|
|
self.check_rpm_missing(fedora_tex_pkgs, 2)
|
|
|
|
self.check_missing_tex(2)
|
|
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
return
|
|
|
|
if self.verbose_warn_install:
|
|
print("You should run:")
|
|
|
|
if old:
|
|
# dnf is there since Fedora 18+ and RHEL 8
|
|
pkg_manager = "yum"
|
|
|
|
print(f"\n\tsudo {pkg_manager} 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.add_package(self.python_cmd, 0)
|
|
|
|
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, 2)
|
|
if self.pdf:
|
|
self.check_missing_tex(2)
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
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"]
|
|
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, 2)
|
|
self.check_rpm_missing(tex_pkgs, 2)
|
|
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
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, 2)
|
|
|
|
self.check_missing_file(
|
|
["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
|
|
"noto-fonts-cjk",
|
|
2,
|
|
)
|
|
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
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, 2)
|
|
|
|
self.check_missing(progs)
|
|
|
|
if not self.need and not self.optional:
|
|
return
|
|
|
|
if self.verbose_warn_install:
|
|
print("You should run:")
|
|
print("\n")
|
|
|
|
|
|
portages = [
|
|
"media-gfx/imagemagick",
|
|
"media-gfx/graphviz",
|
|
]
|
|
|
|
if self.first_hint:
|
|
for p in portages:
|
|
result = self.run(["grep", p, "/etc/portage/package.use/*"],
|
|
stdout=subprocess.PIPE, text=True)
|
|
if not result.stdout.strip():
|
|
print(f"\tsudo emerge -av1 {p}")
|
|
|
|
self.first_hint = False
|
|
|
|
print(f"\tsudo emerge --ask {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(2)
|
|
|
|
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_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
|
|
|
|
# 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.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()
|
|
|
|
print("\n2) As a package with:")
|
|
|
|
old_need = self.need
|
|
old_optional = self.optional
|
|
self.missing = {}
|
|
self.pdf = False
|
|
self.optional = 0
|
|
self.install = ""
|
|
old_verbose = self.verbose_warn_install
|
|
self.verbose_warn_install = 0
|
|
|
|
self.add_package("python-sphinx", 0)
|
|
|
|
self.check_distros()
|
|
|
|
self.need = old_need
|
|
self.optional = old_optional
|
|
self.verbose_warn_install = old_verbose
|
|
|
|
print("\n" \
|
|
" Please note that Sphinx >= 3.0 will currently produce false-positive\n" \
|
|
" warning 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.get_system_release()
|
|
self.python_cmd = sys.executable
|
|
|
|
# Check if Sphinx is already accessible from current environment
|
|
self.check_sphinx()
|
|
|
|
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", 0)
|
|
|
|
# Check for needed programs/tools
|
|
self.check_perl_module("Pod::Usage", 0)
|
|
self.check_python_module("yaml", 0)
|
|
self.check_program("make", 0)
|
|
self.check_program("gcc", 0)
|
|
self.check_program("dot", 1)
|
|
self.check_program("convert", 1)
|
|
|
|
if self.pdf:
|
|
# Extra PDF files - should use 2 for LaTeX is_optional
|
|
self.check_program("xelatex", 2)
|
|
self.check_program("rsvg-convert", 2)
|
|
self.check_program("latexmk", 2)
|
|
|
|
# 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.")
|
|
|
|
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.
|
|
"""
|
|
|
|
if self.which("lsb_release"):
|
|
result = self.run(["lsb_release", "-d"], capture_output=True, text=True)
|
|
self.system_release = result.stdout.replace("Description:", "").strip()
|
|
|
|
release_files = [
|
|
"/etc/system-release",
|
|
"/etc/redhat-release",
|
|
"/etc/lsb-release",
|
|
"/etc/gentoo-release",
|
|
]
|
|
|
|
if not self.system_release:
|
|
for f in release_files:
|
|
self.system_release = self.catcheck(f)
|
|
if self.system_release:
|
|
break
|
|
|
|
# This seems more common than LSB these days
|
|
if not self.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)
|
|
|
|
self.system_release = os_var.get("NAME", "")
|
|
if "VERSION_ID" in os_var:
|
|
self.system_release += " " + os_var["VERSION_ID"]
|
|
elif "VERSION" in os_var:
|
|
self.system_release += " " + os_var["VERSION"]
|
|
except IOError:
|
|
pass
|
|
|
|
if not self.system_release:
|
|
self.system_release = self.catcheck("/etc/issue")
|
|
|
|
self.system_release = self.system_release.strip()
|
|
|
|
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()
|