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-2020 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 $need_venv = 0;
  26 my $need_virtualenv = 0;
  27 my $rec_sphinx_upgrade = 0;
  28 my $install = "";
  29 my $virtenv_dir = "";
  30 my $python_cmd = "";
  31 my $min_version;
  32 my $cur_version;
  33 my $rec_version = "1.7.9";      # PDF won't build here
  34 my $min_pdf_version = "2.4.4";  # Min version where pdf builds
  35
  36 #
  37 # Command line arguments
  38 #
  39
  40 my $pdf = 1;
  41 my $virtualenv = 1;
  42 my $version_check = 0;
  43
  44 #
  45 # List of required texlive packages on Fedora and OpenSuse
  46 #
  47
  48 my %texlive = (
  49         'amsfonts.sty'       => 'texlive-amsfonts',
  50         'amsmath.sty'        => 'texlive-amsmath',
  51         'amssymb.sty'        => 'texlive-amsfonts',
  52         'amsthm.sty'         => 'texlive-amscls',
  53         'anyfontsize.sty'    => 'texlive-anyfontsize',
  54         'atbegshi.sty'       => 'texlive-oberdiek',
  55         'bm.sty'             => 'texlive-tools',
  56         'capt-of.sty'        => 'texlive-capt-of',
  57         'cmap.sty'           => 'texlive-cmap',
  58         'ecrm1000.tfm'       => 'texlive-ec',
  59         'eqparbox.sty'       => 'texlive-eqparbox',
  60         'eu1enc.def'         => 'texlive-euenc',
  61         'fancybox.sty'       => 'texlive-fancybox',
  62         'fancyvrb.sty'       => 'texlive-fancyvrb',
  63         'float.sty'          => 'texlive-float',
  64         'fncychap.sty'       => 'texlive-fncychap',
  65         'footnote.sty'       => 'texlive-mdwtools',
  66         'framed.sty'         => 'texlive-framed',
  67         'luatex85.sty'       => 'texlive-luatex85',
  68         'multirow.sty'       => 'texlive-multirow',
  69         'needspace.sty'      => 'texlive-needspace',
  70         'palatino.sty'       => 'texlive-psnfss',
  71         'parskip.sty'        => 'texlive-parskip',
  72         'polyglossia.sty'    => 'texlive-polyglossia',
  73         'tabulary.sty'       => 'texlive-tabulary',
  74         'threeparttable.sty' => 'texlive-threeparttable',
  75         'titlesec.sty'       => 'texlive-titlesec',
  76         'ucs.sty'            => 'texlive-ucs',
  77         'upquote.sty'        => 'texlive-upquote',
  78         'wrapfig.sty'        => 'texlive-wrapfig',
  79 );
  80
  81 #
  82 # Subroutines that checks if a feature exists
  83 #
  84
  85 sub check_missing(%)
  86 {
  87         my %map = %{$_[0]};
  88
  89         foreach my $prog (sort keys %missing) {
  90                 my $is_optional = $missing{$prog};
  91
  92                 # At least on some LTS distros like CentOS 7, texlive doesn't
  93                 # provide all packages we need. When such distros are
  94                 # detected, we have to disable PDF output.
  95                 #
  96                 # So, we need to ignore the packages that distros would
  97                 # need for LaTeX to work
  98                 if ($is_optional == 2 && !$pdf) {
  99                         $optional--;
 100                         next;
 101                 }
 102
 103                 if ($is_optional) {
 104                         print "Warning: better to also install \"$prog\".\n";
 105                 } else {
 106                         print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
 107                 }
 108                 if (defined($map{$prog})) {
 109                         $install .= " " . $map{$prog};
 110                 } else {
 111                         $install .= " " . $prog;
 112                 }
 113         }
 114
 115         $install =~ s/^\s//;
 116 }
 117
 118 sub add_package($$)
 119 {
 120         my $package = shift;
 121         my $is_optional = shift;
 122
 123         $missing{$package} = $is_optional;
 124         if ($is_optional) {
 125                 $optional++;
 126         } else {
 127                 $need++;
 128         }
 129 }
 130
 131 sub check_missing_file($$$)
 132 {
 133         my $files = shift;
 134         my $package = shift;
 135         my $is_optional = shift;
 136
 137         for (@$files) {
 138                 return if(-e $_);
 139         }
 140
 141         add_package($package, $is_optional);
 142 }
 143
 144 sub findprog($)
 145 {
 146         foreach(split(/:/, $ENV{PATH})) {
 147                 return "$_/$_[0]" if(-x "$_/$_[0]");
 148         }
 149 }
 150
 151 sub find_python_no_venv()
 152 {
 153         my $prog = shift;
 154
 155         my $cur_dir = qx(pwd);
 156         $cur_dir =~ s/\s+$//;
 157
 158         foreach my $dir (split(/:/, $ENV{PATH})) {
 159                 next if ($dir =~ m,($cur_dir)/sphinx,);
 160                 return "$dir/python3" if(-x "$dir/python3");
 161         }
 162         foreach my $dir (split(/:/, $ENV{PATH})) {
 163                 next if ($dir =~ m,($cur_dir)/sphinx,);
 164                 return "$dir/python" if(-x "$dir/python");
 165         }
 166         return "python";
 167 }
 168
 169 sub check_program($$)
 170 {
 171         my $prog = shift;
 172         my $is_optional = shift;
 173
 174         return $prog if findprog($prog);
 175
 176         add_package($prog, $is_optional);
 177 }
 178
 179 sub check_perl_module($$)
 180 {
 181         my $prog = shift;
 182         my $is_optional = shift;
 183
 184         my $err = system("perl -M$prog -e 1 2>/dev/null /dev/null");
 185         return if ($err == 0);
 186
 187         add_package($prog, $is_optional);
 188 }
 189
 190 sub check_python_module($$)
 191 {
 192         my $prog = shift;
 193         my $is_optional = shift;
 194
 195         return if (!$python_cmd);
 196
 197         my $err = system("$python_cmd -c 'import $prog' 2>/dev/null /dev/null");
 198         return if ($err == 0);
 199
 200         add_package($prog, $is_optional);
 201 }
 202
 203 sub check_rpm_missing($$)
 204 {
 205         my @pkgs = @{$_[0]};
 206         my $is_optional = $_[1];
 207
 208         foreach my $prog(@pkgs) {
 209                 my $err = system("rpm -q '$prog' 2>/dev/null >/dev/null");
 210                 add_package($prog, $is_optional) if ($err);
 211         }
 212 }
 213
 214 sub check_pacman_missing($$)
 215 {
 216         my @pkgs = @{$_[0]};
 217         my $is_optional = $_[1];
 218
 219         foreach my $prog(@pkgs) {
 220                 my $err = system("pacman -Q '$prog' 2>/dev/null >/dev/null");
 221                 add_package($prog, $is_optional) if ($err);
 222         }
 223 }
 224
 225 sub check_missing_tex($)
 226 {
 227         my $is_optional = shift;
 228         my $kpsewhich = findprog("kpsewhich");
 229
 230         foreach my $prog(keys %texlive) {
 231                 my $package = $texlive{$prog};
 232                 if (!$kpsewhich) {
 233                         add_package($package, $is_optional);
 234                         next;
 235                 }
 236                 my $file = qx($kpsewhich $prog);
 237                 add_package($package, $is_optional) if ($file =~ /^\s*$/);
 238         }
 239 }
 240
 241 sub get_sphinx_fname()
 242 {
 243         my $fname = "sphinx-build";
 244         return $fname if findprog($fname);
 245
 246         $fname = "sphinx-build-3";
 247         if (findprog($fname)) {
 248                 $need_symlink = 1;
 249                 return $fname;
 250         }
 251
 252         return "";
 253 }
 254
 255 sub get_sphinx_version($)
 256 {
 257         my $cmd = shift;
 258         my $ver;
 259
 260         open IN, "$cmd --version 2>&1 |";
 261         while (<IN>) {
 262                 if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) {
 263                         $ver=$1;
 264                         last;
 265                 }
 266                 # Sphinx 1.2.x uses a different format
 267                 if (m/^\s*Sphinx.*\s+([\d\.]+)$/) {
 268                         $ver=$1;
 269                         last;
 270                 }
 271         }
 272         close IN;
 273         return $ver;
 274 }
 275
 276 sub check_sphinx()
 277 {
 278         my $default_version;
 279
 280         open IN, $conf or die "Can't open $conf";
 281         while (<IN>) {
 282                 if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
 283                         $min_version=$1;
 284                         last;
 285                 }
 286         }
 287         close IN;
 288
 289         die "Can't get needs_sphinx version from $conf" if (!$min_version);
 290
 291         open IN, $requirement_file or die "Can't open $requirement_file";
 292         while (<IN>) {
 293                 if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
 294                         $default_version=$1;
 295                         last;
 296                 }
 297         }
 298         close IN;
 299
 300         die "Can't get default sphinx version from $requirement_file" if (!$default_version);
 301
 302         $virtenv_dir = $virtenv_prefix . $default_version;
 303
 304         my $sphinx = get_sphinx_fname();
 305         if ($sphinx eq "") {
 306                 $need_sphinx = 1;
 307                 return;
 308         }
 309
 310         $cur_version = get_sphinx_version($sphinx);
 311         die ("$sphinx returned an error") if (!$cur_version);
 312
 313         die "$sphinx didn't return its version" if (!$cur_version);
 314
 315         if ($cur_version lt $min_version) {
 316                 printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
 317                        $cur_version, $min_version, $default_version;
 318                 $need_sphinx = 1;
 319                 return;
 320         }
 321
 322         if ($cur_version lt $rec_version) {
 323                 $rec_sphinx_upgrade = 1;
 324                 return;
 325         }
 326         if ($cur_version lt $min_pdf_version) {
 327                 $rec_sphinx_upgrade = 1;
 328                 return;
 329         }
 330
 331         # On version check mode, just assume Sphinx has all mandatory deps
 332         exit (0) if ($version_check);
 333 }
 334
 335 #
 336 # Ancillary subroutines
 337 #
 338
 339 sub catcheck($)
 340 {
 341   my $res = "";
 342   $res = qx(cat $_[0]) if (-r $_[0]);
 343   return $res;
 344 }
 345
 346 sub which($)
 347 {
 348         my $file = shift;
 349         my @path = split ":", $ENV{PATH};
 350
 351         foreach my $dir(@path) {
 352                 my $name = $dir.'/'.$file;
 353                 return $name if (-x $name );
 354         }
 355         return undef;
 356 }
 357
 358 #
 359 # Subroutines that check distro-specific hints
 360 #
 361
 362 sub give_debian_hints()
 363 {
 364         my %map = (
 365                 "python-sphinx"         => "python3-sphinx",
 366                 "sphinx_rtd_theme"      => "python3-sphinx-rtd-theme",
 367                 "ensurepip"             => "python3-venv",
 368                 "virtualenv"            => "virtualenv",
 369                 "dot"                   => "graphviz",
 370                 "convert"               => "imagemagick",
 371                 "Pod::Usage"            => "perl-modules",
 372                 "xelatex"               => "texlive-xetex",
 373                 "rsvg-convert"          => "librsvg2-bin",
 374         );
 375
 376         if ($pdf) {
 377                 check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"],
 378                                    "fonts-dejavu", 2);
 379
 380                 check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
 381                                     "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
 382                                     "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"],
 383                                    "fonts-noto-cjk", 2);
 384         }
 385
 386         check_program("dvipng", 2) if ($pdf);
 387         check_missing(\%map);
 388
 389         return if (!$need && !$optional);
 390         printf("You should run:\n\n\tsudo apt-get install $install\n");
 391 }
 392
 393 sub give_redhat_hints()
 394 {
 395         my %map = (
 396                 "python-sphinx"         => "python3-sphinx",
 397                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 398                 "virtualenv"            => "python3-virtualenv",
 399                 "dot"                   => "graphviz",
 400                 "convert"               => "ImageMagick",
 401                 "Pod::Usage"            => "perl-Pod-Usage",
 402                 "xelatex"               => "texlive-xetex-bin",
 403                 "rsvg-convert"          => "librsvg2-tools",
 404         );
 405
 406         my @fedora26_opt_pkgs = (
 407                 "graphviz-gd",          # Fedora 26: needed for PDF support
 408         );
 409
 410         my @fedora_tex_pkgs = (
 411                 "texlive-collection-fontsrecommended",
 412                 "texlive-collection-latex",
 413                 "texlive-xecjk",
 414                 "dejavu-sans-fonts",
 415                 "dejavu-serif-fonts",
 416                 "dejavu-sans-mono-fonts",
 417         );
 418
 419         #
 420         # Checks valid for RHEL/CentOS version 7.x.
 421         #
 422         my $old = 0;
 423         my $rel;
 424         $rel = $1 if ($system_release =~ /release\s+(\d+)/);
 425
 426         if (!($system_release =~ /Fedora/)) {
 427                 $map{"virtualenv"} = "python-virtualenv";
 428
 429                 if ($rel && $rel < 8) {
 430                         $old = 1;
 431                         $pdf = 0;
 432
 433                         printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n");
 434                         printf("If you want to build PDF, please read:\n");
 435                         printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n");
 436                 }
 437         } else {
 438                 if ($rel && $rel < 26) {
 439                         $old = 1;
 440                 }
 441         }
 442         if (!$rel) {
 443                 printf("Couldn't identify release number\n");
 444                 $old = 1;
 445                 $pdf = 0;
 446         }
 447
 448         if ($pdf) {
 449                 check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
 450                                    "google-noto-sans-cjk-ttc-fonts", 2);
 451         }
 452
 453         check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old);
 454         check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf);
 455         check_missing_tex(2) if ($pdf);
 456         check_missing(\%map);
 457
 458         return if (!$need && !$optional);
 459
 460         if (!$old) {
 461                 # dnf, for Fedora 18+
 462                 printf("You should run:\n\n\tsudo dnf install -y $install\n");
 463         } else {
 464                 # yum, for RHEL (and clones) or Fedora version < 18
 465                 printf("You should run:\n\n\tsudo yum install -y $install\n");
 466         }
 467 }
 468
 469 sub give_opensuse_hints()
 470 {
 471         my %map = (
 472                 "python-sphinx"         => "python3-sphinx",
 473                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 474                 "virtualenv"            => "python3-virtualenv",
 475                 "dot"                   => "graphviz",
 476                 "convert"               => "ImageMagick",
 477                 "Pod::Usage"            => "perl-Pod-Usage",
 478                 "xelatex"               => "texlive-xetex-bin",
 479         );
 480
 481         # On Tumbleweed, this package is also named rsvg-convert
 482         $map{"rsvg-convert"} = "rsvg-view" if (!($system_release =~ /Tumbleweed/));
 483
 484         my @suse_tex_pkgs = (
 485                 "texlive-babel-english",
 486                 "texlive-caption",
 487                 "texlive-colortbl",
 488                 "texlive-courier",
 489                 "texlive-dvips",
 490                 "texlive-helvetic",
 491                 "texlive-makeindex",
 492                 "texlive-metafont",
 493                 "texlive-metapost",
 494                 "texlive-palatino",
 495                 "texlive-preview",
 496                 "texlive-times",
 497                 "texlive-zapfchan",
 498                 "texlive-zapfding",
 499         );
 500
 501         $map{"latexmk"} = "texlive-latexmk-bin";
 502
 503         # FIXME: add support for installing CJK fonts
 504         #
 505         # I tried hard, but was unable to find a way to install
 506         # "Noto Sans CJK SC" on openSUSE
 507
 508         check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
 509         check_missing_tex(2) if ($pdf);
 510         check_missing(\%map);
 511
 512         return if (!$need && !$optional);
 513         printf("You should run:\n\n\tsudo zypper install --no-recommends $install\n");
 514 }
 515
 516 sub give_mageia_hints()
 517 {
 518         my %map = (
 519                 "python-sphinx"         => "python3-sphinx",
 520                 "sphinx_rtd_theme"      => "python3-sphinx_rtd_theme",
 521                 "virtualenv"            => "python3-virtualenv",
 522                 "dot"                   => "graphviz",
 523                 "convert"               => "ImageMagick",
 524                 "Pod::Usage"            => "perl-Pod-Usage",
 525                 "xelatex"               => "texlive",
 526                 "rsvg-convert"          => "librsvg2",
 527         );
 528
 529         my @tex_pkgs = (
 530                 "texlive-fontsextra",
 531         );
 532
 533         $map{"latexmk"} = "texlive-collection-basic";
 534
 535         my $packager_cmd;
 536         my $noto_sans;
 537         if ($system_release =~ /OpenMandriva/) {
 538                 $packager_cmd = "dnf install";
 539                 $noto_sans = "noto-sans-cjk-fonts";
 540                 @tex_pkgs = ( "texlive-collection-fontsextra" );
 541         } else {
 542                 $packager_cmd = "urpmi";
 543                 $noto_sans = "google-noto-sans-cjk-ttc-fonts";
 544         }
 545
 546
 547         if ($pdf) {
 548                 check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
 549                                     "/usr/share/fonts/TTF/NotoSans-Regular.ttf"],
 550                                    $noto_sans, 2);
 551         }
 552
 553         check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
 554         check_missing(\%map);
 555
 556         return if (!$need && !$optional);
 557         printf("You should run:\n\n\tsudo $packager_cmd $install\n");
 558 }
 559
 560 sub give_arch_linux_hints()
 561 {
 562         my %map = (
 563                 "sphinx_rtd_theme"      => "python-sphinx_rtd_theme",
 564                 "virtualenv"            => "python-virtualenv",
 565                 "dot"                   => "graphviz",
 566                 "convert"               => "imagemagick",
 567                 "xelatex"               => "texlive-bin",
 568                 "latexmk"               => "texlive-core",
 569                 "rsvg-convert"          => "extra/librsvg",
 570         );
 571
 572         my @archlinux_tex_pkgs = (
 573                 "texlive-core",
 574                 "texlive-latexextra",
 575                 "ttf-dejavu",
 576         );
 577         check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
 578
 579         if ($pdf) {
 580                 check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
 581                                    "noto-fonts-cjk", 2);
 582         }
 583
 584         check_missing(\%map);
 585
 586         return if (!$need && !$optional);
 587         printf("You should run:\n\n\tsudo pacman -S $install\n");
 588 }
 589
 590 sub give_gentoo_hints()
 591 {
 592         my %map = (
 593                 "sphinx_rtd_theme"      => "dev-python/sphinx_rtd_theme",
 594                 "virtualenv"            => "dev-python/virtualenv",
 595                 "dot"                   => "media-gfx/graphviz",
 596                 "convert"               => "media-gfx/imagemagick",
 597                 "xelatex"               => "dev-texlive/texlive-xetex media-fonts/dejavu",
 598                 "rsvg-convert"          => "gnome-base/librsvg",
 599         );
 600
 601         check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"],
 602                            "media-fonts/dejavu", 2) if ($pdf);
 603
 604         if ($pdf) {
 605                 check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
 606                                     "/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc"],
 607                                    "media-fonts/noto-cjk", 2);
 608         }
 609
 610         check_missing(\%map);
 611
 612         return if (!$need && !$optional);
 613
 614         printf("You should run:\n\n");
 615
 616         my $imagemagick = "media-gfx/imagemagick svg png";
 617         my $cairo = "media-gfx/graphviz cairo pdf";
 618         my $portage_imagemagick = "/etc/portage/package.use/imagemagick";
 619         my $portage_cairo = "/etc/portage/package.use/graphviz";
 620
 621         if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") {
 622                 printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n")
 623         }
 624         if (qx(grep graphviz $portage_cairo 2>/dev/null) eq  "") {
 625                 printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n");
 626         }
 627
 628         printf("\tsudo emerge --ask $install\n");
 629
 630 }
 631
 632 sub check_distros()
 633 {
 634         # Distro-specific hints
 635         if ($system_release =~ /Red Hat Enterprise Linux/) {
 636                 give_redhat_hints;
 637                 return;
 638         }
 639         if ($system_release =~ /CentOS/) {
 640                 give_redhat_hints;
 641                 return;
 642         }
 643         if ($system_release =~ /Scientific Linux/) {
 644                 give_redhat_hints;
 645                 return;
 646         }
 647         if ($system_release =~ /Oracle Linux Server/) {
 648                 give_redhat_hints;
 649                 return;
 650         }
 651         if ($system_release =~ /Fedora/) {
 652                 give_redhat_hints;
 653                 return;
 654         }
 655         if ($system_release =~ /Ubuntu/) {
 656                 give_debian_hints;
 657                 return;
 658         }
 659         if ($system_release =~ /Debian/) {
 660                 give_debian_hints;
 661                 return;
 662         }
 663         if ($system_release =~ /openSUSE/) {
 664                 give_opensuse_hints;
 665                 return;
 666         }
 667         if ($system_release =~ /Mageia/) {
 668                 give_mageia_hints;
 669                 return;
 670         }
 671         if ($system_release =~ /OpenMandriva/) {
 672                 give_mageia_hints;
 673                 return;
 674         }
 675         if ($system_release =~ /Arch Linux/) {
 676                 give_arch_linux_hints;
 677                 return;
 678         }
 679         if ($system_release =~ /Gentoo/) {
 680                 give_gentoo_hints;
 681                 return;
 682         }
 683
 684         #
 685         # Fall-back to generic hint code for other distros
 686         # That's far from ideal, specially for LaTeX dependencies.
 687         #
 688         my %map = (
 689                 "sphinx-build" => "sphinx"
 690         );
 691         check_missing_tex(2) if ($pdf);
 692         check_missing(\%map);
 693         print "I don't know distro $system_release.\n";
 694         print "So, I can't provide you a hint with the install procedure.\n";
 695         print "There are likely missing dependencies.\n";
 696 }
 697
 698 #
 699 # Common dependencies
 700 #
 701
 702 sub deactivate_help()
 703 {
 704         printf "\nIf you want to exit the virtualenv, you can use:\n";
 705         printf "\tdeactivate\n";
 706 }
 707
 708 sub check_needs()
 709 {
 710         # Check if Sphinx is already accessible from current environment
 711         check_sphinx();
 712
 713         if ($system_release) {
 714                 print "Detected OS: $system_release.\n";
 715         } else {
 716                 print "Unknown OS\n";
 717         }
 718         printf "Sphinx version: %s\n\n", $cur_version if ($cur_version);
 719
 720         # Check python command line, trying first python3
 721         $python_cmd = findprog("python3");
 722         $python_cmd = check_program("python", 0) if (!$python_cmd);
 723
 724         # Check the type of virtual env, depending on Python version
 725         if ($python_cmd) {
 726                 if ($virtualenv) {
 727                         my $tmp = qx($python_cmd --version 2>&1);
 728                         if ($tmp =~ m/(\d+\.)(\d+\.)/) {
 729                                 if ($1 >= 3 && $2 >= 3) {
 730                                         $need_venv = 1;         # python 3.3 or upper
 731                                 } else {
 732                                         $need_virtualenv = 1;
 733                                 }
 734                                 if ($1 < 3) {
 735                                         # Complain if it finds python2 (or worse)
 736                                         printf "Warning: python$1 support is deprecated. Use it with caution!\n";
 737                                 }
 738                         } else {
 739                                 die "Warning: couldn't identify $python_cmd version!";
 740                         }
 741                 } else {
 742                         add_package("python-sphinx", 0);
 743                 }
 744         }
 745
 746         # Set virtualenv command line, if python < 3.3
 747         my $virtualenv_cmd;
 748         if ($need_virtualenv) {
 749                 $virtualenv_cmd = findprog("virtualenv-3");
 750                 $virtualenv_cmd = findprog("virtualenv-3.5") if (!$virtualenv_cmd);
 751                 if (!$virtualenv_cmd) {
 752                         check_program("virtualenv", 0);
 753                         $virtualenv_cmd = "virtualenv";
 754                 }
 755         }
 756
 757         # Check for needed programs/tools
 758         check_perl_module("Pod::Usage", 0);
 759         check_program("make", 0);
 760         check_program("gcc", 0);
 761         check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv);
 762         check_program("dot", 1);
 763         check_program("convert", 1);
 764
 765         # Extra PDF files - should use 2 for is_optional
 766         check_program("xelatex", 2) if ($pdf);
 767         check_program("rsvg-convert", 2) if ($pdf);
 768         check_program("latexmk", 2) if ($pdf);
 769
 770         if ($need_sphinx || $rec_sphinx_upgrade) {
 771                 check_python_module("ensurepip", 0) if ($need_venv);
 772         }
 773
 774         # Do distro-specific checks and output distro-install commands
 775         check_distros();
 776
 777         if (!$python_cmd) {
 778                 if ($need == 1) {
 779                         die "Can't build as $need mandatory dependency is missing";
 780                 } elsif ($need) {
 781                         die "Can't build as $need mandatory dependencies are missing";
 782                 }
 783         }
 784
 785         # Check if sphinx-build is called sphinx-build-3
 786         if ($need_symlink) {
 787                 printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",
 788                        which("sphinx-build-3");
 789         }
 790
 791         # NOTE: if the system has a too old Sphinx version installed,
 792         # it will recommend installing a newer version using virtualenv
 793
 794         if ($need_sphinx || $rec_sphinx_upgrade) {
 795                 my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate";
 796                 my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate";
 797
 798                 if ($cur_version lt $rec_version) {
 799                         print "Warning: It is recommended at least Sphinx version $rec_version.\n";
 800                         print "         If you want pdf, you need at least $min_pdf_version.\n";
 801                 }
 802                 if ($cur_version lt $min_pdf_version) {
 803                         print "Note: It is recommended at least Sphinx version $min_pdf_version if you need PDF support.\n";
 804                 }
 805                 @activates = sort {$b cmp $a} @activates;
 806                 my ($activate, $ver);
 807                 foreach my $f (@activates) {
 808                         next if ($f lt $min_activate);
 809
 810                         my $sphinx_cmd = $f;
 811                         $sphinx_cmd =~ s/activate/sphinx-build/;
 812                         next if (! -f $sphinx_cmd);
 813
 814                         $ver = get_sphinx_version($sphinx_cmd);
 815                         if ($need_sphinx && ($ver ge $min_version)) {
 816                                 $activate = $f;
 817                                 last;
 818                         } elsif ($ver gt $cur_version) {
 819                                 $activate = $f;
 820                                 last;
 821                         }
 822                 }
 823                 if ($activate ne "") {
 824                         if ($need_sphinx) {
 825                                 printf "\nNeed to activate Sphinx (version $ver) on virtualenv with:\n";
 826                                 printf "\t. $activate\n";
 827                                 deactivate_help();
 828                                 exit (1);
 829                         } else {
 830                                 printf "\nYou may also use a newer Sphinx (version $ver) with:\n";
 831                                 printf "\tdeactivate && . $activate\n";
 832                         }
 833                 } else {
 834                         my $rec_activate = "$virtenv_dir/bin/activate";
 835
 836                         print "To upgrade Sphinx, use:\n\n" if ($rec_sphinx_upgrade);
 837
 838                         $python_cmd = find_python_no_venv();
 839
 840                         if ($need_venv) {
 841                                 printf "\t$python_cmd -m venv $virtenv_dir\n";
 842                         } else {
 843                                 printf "\t$virtualenv_cmd $virtenv_dir\n";
 844                         }
 845                         printf "\t. $rec_activate\n";
 846                         printf "\tpip install -r $requirement_file\n";
 847                         deactivate_help();
 848
 849                         $need++ if (!$rec_sphinx_upgrade);
 850                 }
 851         }
 852         printf "\n";
 853
 854         print "All optional dependencies are met.\n" if (!$optional);
 855
 856         if ($need == 1) {
 857                 die "Can't build as $need mandatory dependency is missing";
 858         } elsif ($need) {
 859                 die "Can't build as $need mandatory dependencies are missing";
 860         }
 861
 862         print "Needed package dependencies are met.\n";
 863 }
 864
 865 #
 866 # Main
 867 #
 868
 869 while (@ARGV) {
 870         my $arg = shift(@ARGV);
 871
 872         if ($arg eq "--no-virtualenv") {
 873                 $virtualenv = 0;
 874         } elsif ($arg eq "--no-pdf"){
 875                 $pdf = 0;
 876         } elsif ($arg eq "--version-check"){
 877                 $version_check = 1;
 878         } else {
 879                 print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
 880                 print "Where:\n";
 881                 print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
 882                 print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
 883                 print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
 884                 exit -1;
 885         }
 886 }
 887
 888 #
 889 # Determine the system type. There's no standard unique way that would
 890 # work with all distros with a minimal package install. So, several
 891 # methods are used here.
 892 #
 893 # By default, it will use lsb_release function. If not available, it will
 894 # fail back to reading the known different places where the distro name
 895 # is stored
 896 #
 897
 898 $system_release = qx(lsb_release -d) if which("lsb_release");
 899 $system_release =~ s/Description:\s*// if ($system_release);
 900 $system_release = catcheck("/etc/system-release") if !$system_release;
 901 $system_release = catcheck("/etc/redhat-release") if !$system_release;
 902 $system_release = catcheck("/etc/lsb-release") if !$system_release;
 903 $system_release = catcheck("/etc/gentoo-release") if !$system_release;
 904
 905 # This seems more common than LSB these days
 906 if (!$system_release) {
 907         my %os_var;
 908         if (open IN, "cat /etc/os-release|") {
 909                 while (<IN>) {
 910                         if (m/^([\w\d\_]+)=\"?([^\"]*)\"?\n/) {
 911                                 $os_var{$1}=$2;
 912                         }
 913                 }
 914                 $system_release = $os_var{"NAME"};
 915                 if (defined($os_var{"VERSION_ID"})) {
 916                         $system_release .= " " . $os_var{"VERSION_ID"} if (defined($os_var{"VERSION_ID"}));
 917                 } else {
 918                         $system_release .= " " . $os_var{"VERSION"};
 919                 }
 920         }
 921 }
 922 $system_release = catcheck("/etc/issue") if !$system_release;
 923 $system_release =~ s/\s+$//;
 924
 925 check_needs;