scripts/sphinx-pre-install

   1 #!/usr/bin/perl
   2 # SPDX-License-Identifier: GPL-2.0-or-later
   3 use strict;
   4
   5 # Copyright (c) 2017-2019 Mauro Carvalho Chehab <mchehab@kernel.org>
   6 #
   7
   8 my $conf = "Documentation/conf.py";
   9 my $requirement_file = "Documentation/sphinx/requirements.txt";
  10 my $virtenv_prefix = "sphinx_";
  11
  12 #
  13 # Static vars
  14 #
  15
  16 my %missing;
  17 my $system_release;
  18 my $need = 0;
  19 my $optional = 0;
  20 my $need_symlink = 0;
  21 my $need_sphinx = 0;
  22 my $rec_sphinx_upgrade = 0;
  23 my $install = "";
  24 my $virtenv_dir = "";
  25 my $min_version;
  26
  27 #
  28 # Command line arguments
  29 #
  30
  31 my $pdf = 1;
  32 my $virtualenv = 1;
  33 my $version_check = 0;
  34
  35 #
  36 # List of required texlive packages on Fedora and OpenSuse
  37 #
  38
  39 my %texlive = (
  40         'amsfonts.sty'       => 'texlive-amsfonts',
  41         'amsmath.sty'        => 'texlive-amsmath',
  42         'amssymb.sty'        => 'texlive-amsfonts',
  43         'amsthm.sty'         => 'texlive-amscls',
  44         'anyfontsize.sty'    => 'texlive-anyfontsize',
  45         'atbegshi.sty'       => 'texlive-oberdiek',
  46         'bm.sty'             => 'texlive-tools',
  47         'capt-of.sty'        => 'texlive-capt-of',
  48         'cmap.sty'           => 'texlive-cmap',
  49         'ecrm1000.tfm'       => 'texlive-ec',
  50         'eqparbox.sty'       => 'texlive-eqparbox',
  51         'eu1enc.def'         => 'texlive-euenc',
  52         'fancybox.sty'       => 'texlive-fancybox',
  53         'fancyvrb.sty'       => 'texlive-fancyvrb',
  54         'float.sty'          => 'texlive-float',
  55         'fncychap.sty'       => 'texlive-fncychap',
  56         'footnote.sty'       => 'texlive-mdwtools',
  57         'framed.sty'         => 'texlive-framed',
  58         'luatex85.sty'       => 'texlive-luatex85',
  59         'multirow.sty'       => 'texlive-multirow',
  60         'needspace.sty'      => 'texlive-needspace',
  61         'palatino.sty'       => 'texlive-psnfss',
  62         'parskip.sty'        => 'texlive-parskip',
  63         'polyglossia.sty'    => 'texlive-polyglossia',
  64         'tabulary.sty'       => 'texlive-tabulary',
  65         'threeparttable.sty' => 'texlive-threeparttable',
  66         'titlesec.sty'       => 'texlive-titlesec',
  67         'ucs.sty'            => 'texlive-ucs',
  68         'upquote.sty'        => 'texlive-upquote',
  69         'wrapfig.sty'        => 'texlive-wrapfig',
  70 );
  71
  72 #
  73 # Subroutines that checks if a feature exists
  74 #
  75
  76 sub check_missing(%)
  77 {
  78         my %map = %{$_[0]};
  79
  80         foreach my $prog (sort keys %missing) {
  81                 my $is_optional = $missing{$prog};
  82
  83                 if ($is_optional) {
  84                         print "Warning: better to also install \"$prog\".\n";
  85                 } else {
  86                         print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
  87                 }
  88                 if (defined($map{$prog})) {
  89                         $install .= " " . $map{$prog};
  90                 } else {
  91                         $install .= " " . $prog;
  92                 }
  93         }
  94
  95         $install =~ s/^\s//;
  96 }
  97
  98 sub add_package($$)
  99 {
 100         my $package = shift;
 101         my $is_optional = shift;
 102
 103         $missing{$package} = $is_optional;
 104         if ($is_optional) {
 105                 $optional++;
 106         } else {
 107                 $need++;
 108         }
 109 }
 110
 111 sub check_missing_file($$$)
 112 {
 113         my $file = shift;
 114         my $package = shift;
 115         my $is_optional = shift;
 116
 117         return if(-e $file);
 118
 119         add_package($package, $is_optional);
 120 }
 121
 122 sub findprog($)
 123 {
 124         foreach(split(/:/, $ENV{PATH})) {
 125                 return "$_/$_[0]" if(-x "$_/$_[0]");
 126         }
 127 }
 128
 129 sub check_program($$)
 130 {
 131         my $prog = shift;
 132         my $is_optional = shift;
 133
 134         return if findprog($prog);
 135
 136         add_package($prog, $is_optional);
 137 }
 138
 139 sub check_perl_module($$)
 140 {
 141         my $prog = shift;
 142         my $is_optional = shift;
 143
 144         my $err = system("perl -M$prog -e 1 2>/dev/null /dev/null");
 145         return if ($err == 0);
 146
 147         add_package($prog, $is_optional);
 148 }
 149
 150 sub check_python_module($$)
 151 {
 152         my $prog = shift;
 153         my $is_optional = shift;
 154
 155         my $err = system("python3 -c 'import $prog' 2>/dev/null /dev/null");
 156         return if ($err == 0);
 157         my $err = system("python -c 'import $prog' 2>/dev/null /dev/null");
 158         return if ($err == 0);
 159
 160         add_package($prog, $is_optional);
 161 }
 162
 163 sub check_rpm_missing($$)
 164 {
 165         my @pkgs = @{$_[0]};
 166         my $is_optional = $_[1];
 167
 168         foreach my $prog(@pkgs) {
 169                 my $err = system("rpm -q '$prog' 2>/dev/null >/dev/null");
 170                 add_package($prog, $is_optional) if ($err);
 171         }
 172 }
 173
 174 sub check_pacman_missing($$)
 175 {
 176         my @pkgs = @{$_[0]};
 177         my $is_optional = $_[1];
 178
 179         foreach my $prog(@pkgs) {
 180                 my $err = system("pacman -Q '$prog' 2>/dev/null >/dev/null");
 181                 add_package($prog, $is_optional) if ($err);
 182         }
 183 }
 184
 185 sub check_missing_tex($)
 186 {
 187         my $is_optional = shift;
 188         my $kpsewhich = findprog("kpsewhich");
 189
 190         foreach my $prog(keys %texlive) {
 191                 my $package = $texlive{$prog};
 192                 if (!$kpsewhich) {
 193                         add_package($package, $is_optional);
 194                         next;
 195                 }
 196                 my $file = qx($kpsewhich $prog);
 197                 add_package($package, $is_optional) if ($file =~ /^\s*$/);
 198         }
 199 }
 200
 201 sub get_sphinx_fname()
 202 {
 203         my $fname = "sphinx-build";
 204         return $fname if findprog($fname);
 205
 206         $fname = "sphinx-build-3";
 207         if (findprog($fname)) {
 208                 $need_symlink = 1;
 209                 return $fname;
 210         }
 211
 212         if ($virtualenv) {
 213                 my $prog = findprog("virtualenv-3");
 214                 $prog = findprog("virtualenv-3.5") if (!$prog);
 215
 216                 check_program("virtualenv", 0) if (!$prog);
 217                 $need_sphinx = 1;
 218         } else {
 219                 add_package("python-sphinx", 0);
 220         }
 221
 222         return "";
 223 }
 224
 225 sub check_sphinx()
 226 {
 227         my $rec_version;
 228         my $cur_version;
 229
 230         open IN, $conf or die "Can't open $conf";
 231         while (<IN>) {
 232                 if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
 233                         $min_version=$1;
 234                         last;
 235                 }
 236         }
 237         close IN;
 238
 239         die "Can't get needs_sphinx version from $conf" if (!$min_version);
 240
 241         open IN, $requirement_file or die "Can't open $requirement_file";
 242         while (<IN>) {
 243                 if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
 244                         $rec_version=$1;
 245                         last;
 246                 }
 247         }
 248         close IN;
 249
 250         die "Can't get recommended sphinx version from $requirement_file" if (!$min_version);
 251
 252         $virtenv_dir = $virtenv_prefix . $rec_version;
 253
 254         my $sphinx = get_sphinx_fname();
 255         return if ($sphinx eq "");
 256
 257         open IN, "$sphinx --version 2>&1 |" or die "$sphinx returned an error";
 258         while (<IN>) {
 259                 if (m/^\s*sphinx-build\s+([\d\.]+)$/) {
 260                         $cur_version=$1;
 261                         last;
 262                 }
 263                 # Sphinx 1.2.x uses a different format
 264                 if (m/^\s*Sphinx.*\s+([\d\.]+)$/) {
 265                         $cur_version=$1;
 266                         last;
 267                 }
 268         }
 269         close IN;
 270
 271         die "$sphinx didn't return its version" if (!$cur_version);
 272
 273         if ($cur_version lt $min_version) {
 274                 printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
 275                        $cur_version, $min_version, $rec_version;;
 276                 $need_sphinx = 1;
 277                 return;
 278         }
 279
 280         if ($cur_version lt $rec_version) {
 281                 printf "Sphinx version %s\n", $cur_version;
 282                 print "Warning: It is recommended at least Sphinx version $rec_version.\n";
 283                 $rec_sphinx_upgrade = 1;
 284                 return;
 285         }
 286
 287         # On version check mode, just assume Sphinx has all mandatory deps
 288         exit (0) if ($version_check);
 289 }
 290
 291 #
 292 # Ancillary subroutines
 293 #
 294
 295 sub catcheck($)
 296 {
 297   my $res = "";
 298   $res = qx(cat $_[0]) if (-r $_[0]);
 299   return $res;
 300 }
 301
 302 sub which($)
 303 {
 304         my $file = shift;
 305         my @path = split ":", $ENV{PATH};
 306
 307         foreach my $dir(@path) {
 308                 my $name = $dir.'/'.$file;
 309                 return $name if (-x $name );
 310         }
 311         return undef;
 312 }
 313
 314 #
 315 # Subroutines that check distro-specific hints
 316 #
 317
 318 sub give_debian_hints()
 319 {
 320         my %map = (
 321                 "python-sphinx"         => "python3-sphinx",
 322                 "sphinx_rtd_theme"      => "python3-sphinx-rtd-theme",
 323                 "virtualenv"            => "virtualenv",
 324                 "dot"                   => "graphviz",
 325                 "convert"               => "imagemagick",
 326                 "Pod::Usage"            => "perl-modules",
 327                 "xelatex"               => "texlive-xetex",
 328                 "rsvg-convert"          => "librsvg2-bin",
 329         );
 330
 331         if ($pdf) {
 332                 check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
 333                                    "fonts-dejavu", 1);
 334         }
 335
 336         check_program("dvipng", 1) if ($pdf);
 337         check_missing(\%map);
 338
 339         return if (!$need && !$optional);
 340         printf("You should run:\n\n\tsudo apt-get install $install\n");
 341 }
 342
 343 sub give_redhat_hints()
 344 {
 345         my %map = (
 346                 "python-sphinx"         => "python3-sphinx",
 347                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 348                 "virtualenv"            => "python3-virtualenv",
 349                 "dot"                   => "graphviz",
 350                 "convert"               => "ImageMagick",
 351                 "Pod::Usage"            => "perl-Pod-Usage",
 352                 "xelatex"               => "texlive-xetex-bin",
 353                 "rsvg-convert"          => "librsvg2-tools",
 354         );
 355
 356         my @fedora26_opt_pkgs = (
 357                 "graphviz-gd",          # Fedora 26: needed for PDF support
 358         );
 359
 360         my @fedora_tex_pkgs = (
 361                 "texlive-collection-fontsrecommended",
 362                 "texlive-collection-latex",
 363                 "dejavu-sans-fonts",
 364                 "dejavu-serif-fonts",
 365                 "dejavu-sans-mono-fonts",
 366         );
 367
 368         #
 369         # Checks valid for RHEL/CentOS version 7.x.
 370         #
 371         if (! $system_release =~ /Fedora/) {
 372                 $map{"virtualenv"} = "python-virtualenv";
 373         }
 374
 375         my $release;
 376
 377         $release = $1 if ($system_release =~ /Fedora\s+release\s+(\d+)/);
 378
 379         check_rpm_missing(\@fedora26_opt_pkgs, 1) if ($pdf && $release >= 26);
 380         check_rpm_missing(\@fedora_tex_pkgs, 1) if ($pdf);
 381         check_missing_tex(1) if ($pdf);
 382         check_missing(\%map);
 383
 384         return if (!$need && !$optional);
 385
 386         if ($release >= 18) {
 387                 # dnf, for Fedora 18+
 388                 printf("You should run:\n\n\tsudo dnf install -y $install\n");
 389         } else {
 390                 # yum, for RHEL (and clones) or Fedora version < 18
 391                 printf("You should run:\n\n\tsudo yum install -y $install\n");
 392         }
 393 }
 394
 395 sub give_opensuse_hints()
 396 {
 397         my %map = (
 398                 "python-sphinx"         => "python3-sphinx",
 399                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 400                 "virtualenv"            => "python3-virtualenv",
 401                 "dot"                   => "graphviz",
 402                 "convert"               => "ImageMagick",
 403                 "Pod::Usage"            => "perl-Pod-Usage",
 404                 "xelatex"               => "texlive-xetex-bin",
 405                 "rsvg-convert"          => "rsvg-view",
 406         );
 407
 408         my @suse_tex_pkgs = (
 409                 "texlive-babel-english",
 410                 "texlive-caption",
 411                 "texlive-colortbl",
 412                 "texlive-courier",
 413                 "texlive-dvips",
 414                 "texlive-helvetic",
 415                 "texlive-makeindex",
 416                 "texlive-metafont",
 417                 "texlive-metapost",
 418                 "texlive-palatino",
 419                 "texlive-preview",
 420                 "texlive-times",
 421                 "texlive-zapfchan",
 422                 "texlive-zapfding",
 423         );
 424
 425         check_rpm_missing(\@suse_tex_pkgs, 1) if ($pdf);
 426         check_missing_tex(1) if ($pdf);
 427         check_missing(\%map);
 428
 429         return if (!$need && !$optional);
 430         printf("You should run:\n\n\tsudo zypper install --no-recommends $install\n");
 431 }
 432
 433 sub give_mageia_hints()
 434 {
 435         my %map = (
 436                 "python-sphinx"         => "python3-sphinx",
 437                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 438                 "virtualenv"            => "python3-virtualenv",
 439                 "dot"                   => "graphviz",
 440                 "convert"               => "ImageMagick",
 441                 "Pod::Usage"            => "perl-Pod-Usage",
 442                 "xelatex"               => "texlive",
 443                 "rsvg-convert"          => "librsvg2-tools",
 444         );
 445
 446         my @tex_pkgs = (
 447                 "texlive-fontsextra",
 448         );
 449
 450         check_rpm_missing(\@tex_pkgs, 1) if ($pdf);
 451         check_missing(\%map);
 452
 453         return if (!$need && !$optional);
 454         printf("You should run:\n\n\tsudo urpmi $install\n");
 455 }
 456
 457 sub give_arch_linux_hints()
 458 {
 459         my %map = (
 460                 "sphinx_rtd_theme"      => "python-sphinx_rtd_theme",
 461                 "virtualenv"            => "python-virtualenv",
 462                 "dot"                   => "graphviz",
 463                 "convert"               => "imagemagick",
 464                 "xelatex"               => "texlive-bin",
 465                 "rsvg-convert"          => "extra/librsvg",
 466         );
 467
 468         my @archlinux_tex_pkgs = (
 469                 "texlive-core",
 470                 "texlive-latexextra",
 471                 "ttf-dejavu",
 472         );
 473         check_pacman_missing(\@archlinux_tex_pkgs, 1) if ($pdf);
 474         check_missing(\%map);
 475
 476         return if (!$need && !$optional);
 477         printf("You should run:\n\n\tsudo pacman -S $install\n");
 478 }
 479
 480 sub give_gentoo_hints()
 481 {
 482         my %map = (
 483                 "sphinx_rtd_theme"      => "dev-python/sphinx_rtd_theme",
 484                 "virtualenv"            => "dev-python/virtualenv",
 485                 "dot"                   => "media-gfx/graphviz",
 486                 "convert"               => "media-gfx/imagemagick",
 487                 "xelatex"               => "dev-texlive/texlive-xetex media-fonts/dejavu",
 488                 "rsvg-convert"          => "gnome-base/librsvg",
 489         );
 490
 491         check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf",
 492                            "media-fonts/dejavu", 1) if ($pdf);
 493
 494         check_missing(\%map);
 495
 496         return if (!$need && !$optional);
 497
 498         printf("You should run:\n\n");
 499         printf("\tsudo su -c 'echo \"media-gfx/imagemagick svg png\" > /etc/portage/package.use/imagemagick'\n");
 500         printf("\tsudo su -c 'echo \"media-gfx/graphviz cairo pdf\" > /etc/portage/package.use/graphviz'\n");
 501         printf("\tsudo emerge --ask $install\n");
 502
 503 }
 504
 505 sub check_distros()
 506 {
 507         # Distro-specific hints
 508         if ($system_release =~ /Red Hat Enterprise Linux/) {
 509                 give_redhat_hints;
 510                 return;
 511         }
 512         if ($system_release =~ /CentOS/) {
 513                 give_redhat_hints;
 514                 return;
 515         }
 516         if ($system_release =~ /Scientific Linux/) {
 517                 give_redhat_hints;
 518                 return;
 519         }
 520         if ($system_release =~ /Oracle Linux Server/) {
 521                 give_redhat_hints;
 522                 return;
 523         }
 524         if ($system_release =~ /Fedora/) {
 525                 give_redhat_hints;
 526                 return;
 527         }
 528         if ($system_release =~ /Ubuntu/) {
 529                 give_debian_hints;
 530                 return;
 531         }
 532         if ($system_release =~ /Debian/) {
 533                 give_debian_hints;
 534                 return;
 535         }
 536         if ($system_release =~ /openSUSE/) {
 537                 give_opensuse_hints;
 538                 return;
 539         }
 540         if ($system_release =~ /Mageia/) {
 541                 give_mageia_hints;
 542                 return;
 543         }
 544         if ($system_release =~ /Arch Linux/) {
 545                 give_arch_linux_hints;
 546                 return;
 547         }
 548         if ($system_release =~ /Gentoo/) {
 549                 give_gentoo_hints;
 550                 return;
 551         }
 552
 553         #
 554         # Fall-back to generic hint code for other distros
 555         # That's far from ideal, specially for LaTeX dependencies.
 556         #
 557         my %map = (
 558                 "sphinx-build" => "sphinx"
 559         );
 560         check_missing_tex(1) if ($pdf);
 561         check_missing(\%map);
 562         print "I don't know distro $system_release.\n";
 563         print "So, I can't provide you a hint with the install procedure.\n";
 564         print "There are likely missing dependencies.\n";
 565 }
 566
 567 #
 568 # Common dependencies
 569 #
 570
 571 sub check_needs()
 572 {
 573         # Check for needed programs/tools
 574         check_sphinx();
 575
 576         if ($system_release) {
 577                 print "Detected OS: $system_release.\n\n";
 578         } else {
 579                 print "Unknown OS\n\n";
 580         }
 581
 582         print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade);
 583
 584         # Check for needed programs/tools
 585         check_perl_module("Pod::Usage", 0);
 586         check_program("make", 0);
 587         check_program("gcc", 0);
 588         check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv);
 589         check_program("xelatex", 1) if ($pdf);
 590         check_program("dot", 1);
 591         check_program("convert", 1);
 592         check_program("rsvg-convert", 1) if ($pdf);
 593         check_program("latexmk", 1) if ($pdf);
 594
 595         check_distros();
 596
 597         if ($need_symlink) {
 598                 printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",
 599                        which("sphinx-build-3");
 600         }
 601         if ($need_sphinx || $rec_sphinx_upgrade) {
 602                 my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate";
 603                 my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate";
 604
 605                 @activates = sort {$b cmp $a} @activates;
 606
 607                 if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) {
 608                         printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n";
 609                         printf "\t. $activates[0]\n";
 610                         exit (1);
 611                 } else {
 612                         my $rec_activate = "$virtenv_dir/bin/activate";
 613                         my $virtualenv = findprog("virtualenv-3");
 614                         $virtualenv = findprog("virtualenv-3.5") if (!$virtualenv);
 615                         $virtualenv = findprog("virtualenv") if (!$virtualenv);
 616                         $virtualenv = "virtualenv" if (!$virtualenv);
 617
 618                         printf "\t$virtualenv $virtenv_dir\n";
 619                         printf "\t. $rec_activate\n";
 620                         printf "\tpip install -r $requirement_file\n";
 621
 622                         $need++ if (!$rec_sphinx_upgrade);
 623                 }
 624         }
 625         printf "\n";
 626
 627         print "All optional dependencies are met.\n" if (!$optional);
 628
 629         if ($need == 1) {
 630                 die "Can't build as $need mandatory dependency is missing";
 631         } elsif ($need) {
 632                 die "Can't build as $need mandatory dependencies are missing";
 633         }
 634
 635         print "Needed package dependencies are met.\n";
 636 }
 637
 638 #
 639 # Main
 640 #
 641
 642 while (@ARGV) {
 643         my $arg = shift(@ARGV);
 644
 645         if ($arg eq "--no-virtualenv") {
 646                 $virtualenv = 0;
 647         } elsif ($arg eq "--no-pdf"){
 648                 $pdf = 0;
 649         } elsif ($arg eq "--version-check"){
 650                 $version_check = 1;
 651         } else {
 652                 print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
 653                 print "Where:\n";
 654                 print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
 655                 print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
 656                 print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
 657                 exit -1;
 658         }
 659 }
 660
 661 #
 662 # Determine the system type. There's no standard unique way that would
 663 # work with all distros with a minimal package install. So, several
 664 # methods are used here.
 665 #
 666 # By default, it will use lsb_release function. If not available, it will
 667 # fail back to reading the known different places where the distro name
 668 # is stored
 669 #
 670
 671 $system_release = qx(lsb_release -d) if which("lsb_release");
 672 $system_release =~ s/Description:\s*// if ($system_release);
 673 $system_release = catcheck("/etc/system-release") if !$system_release;
 674 $system_release = catcheck("/etc/redhat-release") if !$system_release;
 675 $system_release = catcheck("/etc/lsb-release") if !$system_release;
 676 $system_release = catcheck("/etc/gentoo-release") if !$system_release;
 677 $system_release = catcheck("/etc/issue") if !$system_release;
 678 $system_release =~ s/\s+$//;
 679
 680 check_needs;