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