linux/scripts/sphinx-pre-install

1064 lines
25 KiB
Plaintext
Raw Normal View History

#!/usr/bin/env perl
treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 157 Based on 3 normalized pattern(s): this program is free software you can redistribute it and or modify it under the terms of the gnu general public license as published by the free software foundation either version 2 of the license or at your option any later version this program is distributed in the hope that it will be useful but without any warranty without even the implied warranty of merchantability or fitness for a particular purpose see the gnu general public license for more details this program is free software you can redistribute it and or modify it under the terms of the gnu general public license as published by the free software foundation either version 2 of the license or at your option any later version [author] [kishon] [vijay] [abraham] [i] [kishon]@[ti] [com] this program is distributed in the hope that it will be useful but without any warranty without even the implied warranty of merchantability or fitness for a particular purpose see the gnu general public license for more details this program is free software you can redistribute it and or modify it under the terms of the gnu general public license as published by the free software foundation either version 2 of the license or at your option any later version [author] [graeme] [gregory] [gg]@[slimlogic] [co] [uk] [author] [kishon] [vijay] [abraham] [i] [kishon]@[ti] [com] [based] [on] [twl6030]_[usb] [c] [author] [hema] [hk] [hemahk]@[ti] [com] this program is distributed in the hope that it will be useful but without any warranty without even the implied warranty of merchantability or fitness for a particular purpose see the gnu general public license for more details extracted by the scancode license scanner the SPDX license identifier GPL-2.0-or-later has been chosen to replace the boilerplate/reference in 1105 file(s). Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Allison Randal <allison@lohutok.net> Reviewed-by: Richard Fontana <rfontana@redhat.com> Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org> Cc: linux-spdx@vger.kernel.org Link: https://lkml.kernel.org/r/20190527070033.202006027@linutronix.de Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2019-05-27 06:55:06 +00:00
# SPDX-License-Identifier: GPL-2.0-or-later
use strict;
# Copyright (c) 2017-2020 Mauro Carvalho Chehab <mchehab@kernel.org>
#
my $prefix = "./";
$prefix = "$ENV{'srctree'}/" if ($ENV{'srctree'});
my $conf = $prefix . "Documentation/conf.py";
my $requirement_file = $prefix . "Documentation/sphinx/requirements.txt";
my $virtenv_prefix = "sphinx_";
#
# Static vars
#
my %missing;
my $system_release;
my $need = 0;
my $optional = 0;
my $need_symlink = 0;
my $need_sphinx = 0;
my $need_pip = 0;
my $need_virtualenv = 0;
my $rec_sphinx_upgrade = 0;
my $verbose_warn_install = 1;
my $install = "";
my $virtenv_dir = "";
my $python_cmd = "";
my $activate_cmd;
my $min_version;
my $cur_version;
my $rec_version = "1.7.9"; # PDF won't build here
my $min_pdf_version = "2.4.4"; # Min version where pdf builds
my $latest_avail_ver;
#
# Command line arguments
#
my $pdf = 1;
my $virtualenv = 1;
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
my $version_check = 0;
#
# List of required texlive packages on Fedora and OpenSuse
#
my %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',
'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',
'ctexhook.sty' => 'texlive-ctex',
);
#
# Subroutines that checks if a feature exists
#
sub check_missing(%)
{
my %map = %{$_[0]};
foreach my $prog (sort keys %missing) {
my $is_optional = $missing{$prog};
# 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 && !$pdf) {
$optional--;
next;
}
if ($verbose_warn_install) {
if ($is_optional) {
print "Warning: better to also install \"$prog\".\n";
} else {
print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
}
}
if (defined($map{$prog})) {
$install .= " " . $map{$prog};
} else {
$install .= " " . $prog;
}
}
$install =~ s/^\s//;
}
sub add_package($$)
{
my $package = shift;
my $is_optional = shift;
$missing{$package} = $is_optional;
if ($is_optional) {
$optional++;
} else {
$need++;
}
}
sub check_missing_file($$$)
{
my $files = shift;
my $package = shift;
my $is_optional = shift;
for (@$files) {
return if(-e $_);
}
add_package($package, $is_optional);
}
sub findprog($)
{
foreach(split(/:/, $ENV{PATH})) {
return "$_/$_[0]" if(-x "$_/$_[0]");
}
}
sub find_python_no_venv()
{
my $prog = shift;
my $cur_dir = qx(pwd);
$cur_dir =~ s/\s+$//;
foreach my $dir (split(/:/, $ENV{PATH})) {
next if ($dir =~ m,($cur_dir)/sphinx,);
return "$dir/python3" if(-x "$dir/python3");
}
foreach my $dir (split(/:/, $ENV{PATH})) {
next if ($dir =~ m,($cur_dir)/sphinx,);
return "$dir/python" if(-x "$dir/python");
}
return "python";
}
sub check_program($$)
{
my $prog = shift;
my $is_optional = shift;
return $prog if findprog($prog);
add_package($prog, $is_optional);
}
sub check_perl_module($$)
{
my $prog = shift;
my $is_optional = shift;
my $err = system("perl -M$prog -e 1 2>/dev/null /dev/null");
return if ($err == 0);
add_package($prog, $is_optional);
}
sub check_python_module($$)
{
my $prog = shift;
my $is_optional = shift;
return if (!$python_cmd);
my $err = system("$python_cmd -c 'import $prog' 2>/dev/null /dev/null");
return if ($err == 0);
add_package($prog, $is_optional);
}
sub check_rpm_missing($$)
{
my @pkgs = @{$_[0]};
my $is_optional = $_[1];
foreach my $prog(@pkgs) {
my $err = system("rpm -q '$prog' 2>/dev/null >/dev/null");
add_package($prog, $is_optional) if ($err);
}
}
sub check_pacman_missing($$)
{
my @pkgs = @{$_[0]};
my $is_optional = $_[1];
foreach my $prog(@pkgs) {
my $err = system("pacman -Q '$prog' 2>/dev/null >/dev/null");
add_package($prog, $is_optional) if ($err);
}
}
sub check_missing_tex($)
{
my $is_optional = shift;
my $kpsewhich = findprog("kpsewhich");
foreach my $prog(keys %texlive) {
my $package = $texlive{$prog};
if (!$kpsewhich) {
add_package($package, $is_optional);
next;
}
my $file = qx($kpsewhich $prog);
add_package($package, $is_optional) if ($file =~ /^\s*$/);
}
}
sub get_sphinx_fname()
{
my $fname = "sphinx-build";
return $fname if findprog($fname);
$fname = "sphinx-build-3";
if (findprog($fname)) {
$need_symlink = 1;
return $fname;
}
return "";
}
sub get_sphinx_version($)
{
my $cmd = shift;
my $ver;
open IN, "$cmd --version 2>&1 |";
while (<IN>) {
if (m/^\s*sphinx-build\s+([\d\.]+)((\+\/[\da-f]+)|(b\d+))?$/) {
$ver=$1;
last;
}
# Sphinx 1.2.x uses a different format
if (m/^\s*Sphinx.*\s+([\d\.]+)$/) {
$ver=$1;
last;
}
}
close IN;
return $ver;
}
sub check_sphinx()
{
my $default_version;
open IN, $conf or die "Can't open $conf";
while (<IN>) {
if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
$min_version=$1;
last;
}
}
close IN;
die "Can't get needs_sphinx version from $conf" if (!$min_version);
open IN, $requirement_file or die "Can't open $requirement_file";
while (<IN>) {
if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
$default_version=$1;
last;
}
}
close IN;
die "Can't get default sphinx version from $requirement_file" if (!$default_version);
$virtenv_dir = $virtenv_prefix . $default_version;
my $sphinx = get_sphinx_fname();
if ($sphinx eq "") {
$need_sphinx = 1;
return;
}
$cur_version = get_sphinx_version($sphinx);
die ("$sphinx returned an error") if (!$cur_version);
die "$sphinx didn't return its version" if (!$cur_version);
if ($cur_version lt $min_version) {
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
$cur_version, $min_version, $default_version;
$need_sphinx = 1;
return;
}
return if ($cur_version lt $rec_version);
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
# On version check mode, just assume Sphinx has all mandatory deps
exit (0) if ($version_check);
}
#
# Ancillary subroutines
#
sub catcheck($)
{
my $res = "";
$res = qx(cat $_[0]) if (-r $_[0]);
return $res;
}
sub which($)
{
my $file = shift;
my @path = split ":", $ENV{PATH};
foreach my $dir(@path) {
my $name = $dir.'/'.$file;
return $name if (-x $name );
}
return undef;
}
#
# Subroutines that check distro-specific hints
#
sub give_debian_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
"ensurepip" => "python3-venv",
"virtualenv" => "virtualenv",
"dot" => "graphviz",
"convert" => "imagemagick",
"Pod::Usage" => "perl-modules",
"xelatex" => "texlive-xetex",
"rsvg-convert" => "librsvg2-bin",
);
if ($pdf) {
check_missing_file(["/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty"],
"texlive-lang-chinese", 2);
check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"],
"fonts-dejavu", 2);
check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"],
"fonts-noto-cjk", 2);
}
check_program("dvipng", 2) if ($pdf);
check_missing(\%map);
return if (!$need && !$optional);
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo apt-get install $install\n");
}
sub give_redhat_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
"Pod::Usage" => "perl-Pod-Usage",
"xelatex" => "texlive-xetex-bin",
"rsvg-convert" => "librsvg2-tools",
);
my @fedora26_opt_pkgs = (
"graphviz-gd", # Fedora 26: needed for PDF support
);
my @fedora_tex_pkgs = (
"texlive-collection-fontsrecommended",
"texlive-collection-latex",
"texlive-xecjk",
"dejavu-sans-fonts",
"dejavu-serif-fonts",
"dejavu-sans-mono-fonts",
);
#
# Checks valid for RHEL/CentOS version 7.x.
#
my $old = 0;
my $rel;
$rel = $1 if ($system_release =~ /release\s+(\d+)/);
if (!($system_release =~ /Fedora/)) {
$map{"virtualenv"} = "python-virtualenv";
if ($rel && $rel < 8) {
$old = 1;
$pdf = 0;
printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n");
printf("If you want to build PDF, please read:\n");
printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n");
}
} else {
if ($rel && $rel < 26) {
$old = 1;
}
}
if (!$rel) {
printf("Couldn't identify release number\n");
$old = 1;
$pdf = 0;
}
if ($pdf) {
check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
"google-noto-sans-cjk-ttc-fonts", 2);
}
check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old);
check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf);
check_missing_tex(2) if ($pdf);
check_missing(\%map);
return if (!$need && !$optional);
if (!$old) {
# dnf, for Fedora 18+
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo dnf install -y $install\n");
} else {
# yum, for RHEL (and clones) or Fedora version < 18
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo yum install -y $install\n");
}
}
sub give_opensuse_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
"Pod::Usage" => "perl-Pod-Usage",
"xelatex" => "texlive-xetex-bin",
);
# On Tumbleweed, this package is also named rsvg-convert
$map{"rsvg-convert"} = "rsvg-view" if (!($system_release =~ /Tumbleweed/));
my @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",
);
$map{"latexmk"} = "texlive-latexmk-bin";
# 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
check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
check_missing_tex(2) if ($pdf);
check_missing(\%map);
return if (!$need && !$optional);
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo zypper install --no-recommends $install\n");
}
sub give_mageia_hints()
{
my %map = (
"python-sphinx" => "python3-sphinx",
"virtualenv" => "python3-virtualenv",
"dot" => "graphviz",
"convert" => "ImageMagick",
"Pod::Usage" => "perl-Pod-Usage",
"xelatex" => "texlive",
"rsvg-convert" => "librsvg2",
);
my @tex_pkgs = (
"texlive-fontsextra",
);
$map{"latexmk"} = "texlive-collection-basic";
my $packager_cmd;
my $noto_sans;
if ($system_release =~ /OpenMandriva/) {
$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";
}
if ($pdf) {
check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/TTF/NotoSans-Regular.ttf"],
$noto_sans, 2);
}
check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
check_missing(\%map);
return if (!$need && !$optional);
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo $packager_cmd $install\n");
}
sub give_arch_linux_hints()
{
my %map = (
"virtualenv" => "python-virtualenv",
"dot" => "graphviz",
"convert" => "imagemagick",
"xelatex" => "texlive-bin",
"latexmk" => "texlive-core",
"rsvg-convert" => "extra/librsvg",
);
my @archlinux_tex_pkgs = (
"texlive-core",
"texlive-latexextra",
"ttf-dejavu",
);
check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
if ($pdf) {
check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
"noto-fonts-cjk", 2);
}
check_missing(\%map);
return if (!$need && !$optional);
printf("You should run:\n") if ($verbose_warn_install);
printf("\n\tsudo pacman -S $install\n");
}
sub give_gentoo_hints()
{
my %map = (
"virtualenv" => "dev-python/virtualenv",
"dot" => "media-gfx/graphviz",
"convert" => "media-gfx/imagemagick",
"xelatex" => "dev-texlive/texlive-xetex media-fonts/dejavu",
"rsvg-convert" => "gnome-base/librsvg",
);
check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"],
"media-fonts/dejavu", 2) if ($pdf);
if ($pdf) {
check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
"/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc"],
"media-fonts/noto-cjk", 2);
}
check_missing(\%map);
return if (!$need && !$optional);
printf("You should run:\n") if ($verbose_warn_install);
printf("\n");
my $imagemagick = "media-gfx/imagemagick svg png";
my $cairo = "media-gfx/graphviz cairo pdf";
my $portage_imagemagick = "/etc/portage/package.use/imagemagick";
my $portage_cairo = "/etc/portage/package.use/graphviz";
if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") {
printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n")
}
if (qx(grep graphviz $portage_cairo 2>/dev/null) eq "") {
printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n");
}
printf("\tsudo emerge --ask $install\n");
}
sub check_distros()
{
# Distro-specific hints
if ($system_release =~ /Red Hat Enterprise Linux/) {
give_redhat_hints;
return;
}
if ($system_release =~ /CentOS/) {
give_redhat_hints;
return;
}
if ($system_release =~ /Scientific Linux/) {
give_redhat_hints;
return;
}
if ($system_release =~ /Oracle Linux Server/) {
give_redhat_hints;
return;
}
if ($system_release =~ /Fedora/) {
give_redhat_hints;
return;
}
if ($system_release =~ /Ubuntu/) {
give_debian_hints;
return;
}
if ($system_release =~ /Debian/) {
give_debian_hints;
return;
}
if ($system_release =~ /openSUSE/) {
give_opensuse_hints;
return;
}
if ($system_release =~ /Mageia/) {
give_mageia_hints;
return;
}
if ($system_release =~ /OpenMandriva/) {
give_mageia_hints;
return;
}
if ($system_release =~ /Arch Linux/) {
give_arch_linux_hints;
return;
}
if ($system_release =~ /Gentoo/) {
give_gentoo_hints;
return;
}
#
# Fall-back to generic hint code for other distros
# That's far from ideal, specially for LaTeX dependencies.
#
my %map = (
"sphinx-build" => "sphinx"
);
check_missing_tex(2) if ($pdf);
check_missing(\%map);
print "I don't know distro $system_release.\n";
print "So, I can't provide you a hint with the install procedure.\n";
print "There are likely missing dependencies.\n";
}
#
# Common dependencies
#
sub deactivate_help()
{
printf "\n If you want to exit the virtualenv, you can use:\n";
printf "\tdeactivate\n";
}
sub get_virtenv()
{
my $ver;
my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate";
my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate";
@activates = sort {$b cmp $a} @activates;
foreach my $f (@activates) {
next if ($f lt $min_activate);
my $sphinx_cmd = $f;
$sphinx_cmd =~ s/activate/sphinx-build/;
next if (! -f $sphinx_cmd);
my $ver = get_sphinx_version($sphinx_cmd);
if (!$ver) {
$f =~ s#/bin/activate##;
print("Warning: virtual environment $f is not working.\nPython version upgrade? Remove it with:\n\n\trm -rf $f\n\n");
}
if ($need_sphinx && ($ver ge $min_version)) {
return ($f, $ver);
} elsif ($ver gt $cur_version) {
return ($f, $ver);
}
}
return ("", "");
}
sub recommend_sphinx_upgrade()
{
my $venv_ver;
# Avoid running sphinx-builds from venv if $cur_version is good
if ($cur_version && ($cur_version ge $rec_version)) {
$latest_avail_ver = $cur_version;
return;
}
# Get the highest version from sphinx_*/bin/sphinx-build and the
# corresponding command to activate the venv/virtenv
($activate_cmd, $venv_ver) = get_virtenv();
# Store the highest version from Sphinx existing virtualenvs
if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) {
$latest_avail_ver = $venv_ver;
} else {
$latest_avail_ver = $cur_version if ($cur_version);
}
# As we don't know package version of Sphinx, and there's no
# virtual environments, don't check if upgrades are needed
if (!$virtualenv) {
return if (!$latest_avail_ver);
}
# Either there are already a virtual env or a new one should be created
$need_pip = 1;
return if (!$latest_avail_ver);
# Return if the reason is due to an upgrade or not
if ($latest_avail_ver lt $rec_version) {
$rec_sphinx_upgrade = 1;
}
return $latest_avail_ver;
}
#
# 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
sub recommend_sphinx_version($)
{
my $virtualenv_cmd = shift;
# Version is OK. Nothing to do.
if ($cur_version && ($cur_version ge $rec_version)) {
if ($cur_version lt $min_pdf_version) {
print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
}
return;
};
if (!$need_sphinx) {
# sphinx-build is present and its version is >= $min_version
#only recommend enabling a newer virtenv version if makes sense.
if ($latest_avail_ver gt $cur_version) {
printf "\nYou may also use the newer Sphinx version $latest_avail_ver with:\n";
printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/);
printf "\t. $activate_cmd\n";
deactivate_help();
return;
}
return if ($latest_avail_ver ge $rec_version);
}
if (!$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.
return if (!$latest_avail_ver);
# 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 ($latest_avail_ver gt $cur_version) {
printf "\nYou may also use the Sphinx virtualenv version $latest_avail_ver with:\n";
printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/);
printf "\t. $activate_cmd\n";
deactivate_help();
return;
}
print "\n";
} else {
$need++ if ($need_sphinx);
}
# Suggest newer versions if current ones are too old
if ($latest_avail_ver && $latest_avail_ver ge $min_version) {
# If there's a good enough version, ask the user to enable it
if ($latest_avail_ver ge $rec_version) {
printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n";
printf "\t. $activate_cmd\n";
deactivate_help();
if ($latest_avail_ver lt $min_pdf_version) {
print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
}
return;
}
# Version is above the minimal required one, but may be
# below the recommended one. So, print warnings/notes
if ($latest_avail_ver lt $rec_version) {
print "Warning: It is recommended at least Sphinx version $rec_version.\n";
}
}
# At this point, either it needs Sphinx or upgrade is recommended,
# both via pip
if ($rec_sphinx_upgrade) {
if (!$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\n";
}
$python_cmd = find_python_no_venv();
printf "\t$virtualenv_cmd $virtenv_dir\n";
printf "\t. $virtenv_dir/bin/activate\n";
printf "\tpip install -r $requirement_file\n";
deactivate_help();
printf "\n2) As a package with:\n";
my $old_need = $need;
my $old_optional = $optional;
%missing = ();
$pdf = 0;
$optional = 0;
$install = "";
$verbose_warn_install = 0;
add_package("python-sphinx", 0);
check_distros();
$need = $old_need;
$optional = $old_optional;
printf "\n Please note that Sphinx >= 3.0 will currently produce false-positive\n";
printf " warning when the same name is used for more than one type (functions,\n";
printf " structs, enums,...). This is known Sphinx bug. For more details, see:\n";
printf "\thttps://github.com/sphinx-doc/sphinx/pull/8313\n";
}
sub check_needs()
{
# Check if Sphinx is already accessible from current environment
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
check_sphinx();
if ($system_release) {
print "Detected OS: $system_release.\n";
} else {
print "Unknown OS\n";
}
printf "Sphinx version: %s\n\n", $cur_version if ($cur_version);
# Check python command line, trying first python3
$python_cmd = findprog("python3");
$python_cmd = check_program("python", 0) if (!$python_cmd);
# Check the type of virtual env, depending on Python version
if ($python_cmd) {
if ($virtualenv) {
my $tmp = qx($python_cmd --version 2>&1);
if ($tmp =~ m/(\d+\.)(\d+\.)/) {
if ($1 < 3) {
# Fail if it finds python2 (or worse)
die "Python 3 is required to build the kernel docs\n";
}
if ($1 == 3 && $2 < 3) {
# Need Python 3.3 or upper for venv
$need_virtualenv = 1;
}
} else {
die "Warning: couldn't identify $python_cmd version!";
}
} else {
add_package("python-sphinx", 0);
}
}
my $venv_ver = recommend_sphinx_upgrade();
my $virtualenv_cmd;
if ($need_pip) {
# Set virtualenv command line, if python < 3.3
if ($need_virtualenv) {
$virtualenv_cmd = findprog("virtualenv-3");
$virtualenv_cmd = findprog("virtualenv-3.5") if (!$virtualenv_cmd);
if (!$virtualenv_cmd) {
check_program("virtualenv", 0);
$virtualenv_cmd = "virtualenv";
}
} else {
$virtualenv_cmd = "$python_cmd -m venv";
check_python_module("ensurepip", 0);
}
}
# Check for needed programs/tools
check_perl_module("Pod::Usage", 0);
check_program("make", 0);
check_program("gcc", 0);
check_program("dot", 1);
check_program("convert", 1);
# Extra PDF files - should use 2 for is_optional
check_program("xelatex", 2) if ($pdf);
check_program("rsvg-convert", 2) if ($pdf);
check_program("latexmk", 2) if ($pdf);
# Do distro-specific checks and output distro-install commands
check_distros();
if (!$python_cmd) {
if ($need == 1) {
die "Can't build as $need mandatory dependency is missing";
} elsif ($need) {
die "Can't build as $need mandatory dependencies are missing";
}
}
# Check if sphinx-build is called sphinx-build-3
if ($need_symlink) {
printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",
which("sphinx-build-3");
}
recommend_sphinx_version($virtualenv_cmd);
printf "\n";
print "All optional dependencies are met.\n" if (!$optional);
if ($need == 1) {
die "Can't build as $need mandatory dependency is missing";
} elsif ($need) {
die "Can't build as $need mandatory dependencies are missing";
}
print "Needed package dependencies are met.\n";
}
#
# Main
#
while (@ARGV) {
my $arg = shift(@ARGV);
if ($arg eq "--no-virtualenv") {
$virtualenv = 0;
} elsif ($arg eq "--no-pdf"){
$pdf = 0;
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
} elsif ($arg eq "--version-check"){
$version_check = 1;
} else {
scripts/sphinx-pre-install: always check if version is compatible with build Call the script every time a make docs target is selected, on a simplified check mode. With this change, the script will set two vars: $min_version - obtained from `needs_sphinx` var inside conf.py (currently, '1.3') $rec_version - obtained from sphinx/requirements.txt. With those changes, a target like "make htmldocs" will do: 1) If no sphinx-build/sphinx-build3 is found, it will run the script on normal mode as before, checking for all system dependencies and providing install hints for the needed programs and will abort the build; 2) If no sphinx-build/sphinx-build3 is found, but there is a sphinx_${VER}/bin/activate file, and if ${VER} >= $min_version (string comparation), it will run in full mode, and will recommend to activate the virtualenv. If there are multiple virtualenvs, it will string sort the versions, recommending the highest version and will abort the build; 3) If Sphinx is detected but has a version lower than $min_version, it will run in full mode - with will recommend creating a virtual env using sphinx/requirements.txt, and will abort the build. 4) If Sphinx is detected and version is lower than $rec_version, it will run in full mode and will recommend creating a virtual env using sphinx/requirements.txt. In this case, it **won't** abort the build. 5) If Sphinx is detected and version is equal or righer than $rec_version it will return just after detecting the version ("quick mode"), not checking if are there any missing dependencies. Just like before, if one wants to install Sphinx from the distro, it has to call the script manually and use `--no-virtualenv` argument to get the hints for his OS: You should run: sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme While here, add a small help for the three optional arguments for the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29 23:09:26 +00:00
print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
print "Where:\n";
print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
exit -1;
}
}
#
# Determine the system type. There's no standard 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
#
$system_release = qx(lsb_release -d) if which("lsb_release");
$system_release =~ s/Description:\s*// if ($system_release);
$system_release = catcheck("/etc/system-release") if !$system_release;
$system_release = catcheck("/etc/redhat-release") if !$system_release;
$system_release = catcheck("/etc/lsb-release") if !$system_release;
$system_release = catcheck("/etc/gentoo-release") if !$system_release;
# This seems more common than LSB these days
if (!$system_release) {
my %os_var;
if (open IN, "cat /etc/os-release|") {
while (<IN>) {
if (m/^([\w\d\_]+)=\"?([^\"]*)\"?\n/) {
$os_var{$1}=$2;
}
}
$system_release = $os_var{"NAME"};
if (defined($os_var{"VERSION_ID"})) {
$system_release .= " " . $os_var{"VERSION_ID"} if (defined($os_var{"VERSION_ID"}));
} else {
$system_release .= " " . $os_var{"VERSION"};
}
}
}
$system_release = catcheck("/etc/issue") if !$system_release;
$system_release =~ s/\s+$//;
check_needs;