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