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