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		"sphinx_rtd_theme"	=> "python3-sphinx-rtd-theme",
366		"ensurepip"		=> "python3-venv",
367		"virtualenv"		=> "virtualenv",
368		"dot"			=> "graphviz",
369		"convert"		=> "imagemagick",
370		"Pod::Usage"		=> "perl-modules",
371		"xelatex"		=> "texlive-xetex",
372		"rsvg-convert"		=> "librsvg2-bin",
373	);
374
375	if ($pdf) {
376		check_missing_file(["/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty"],
377				   "texlive-lang-chinese", 2);
378
379		check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"],
380				   "fonts-dejavu", 2);
381
382		check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
383				    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
384				    "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"],
385				   "fonts-noto-cjk", 2);
386	}
387
388	check_program("dvipng", 2) if ($pdf);
389	check_missing(\%map);
390
391	return if (!$need && !$optional);
392	printf("You should run:\n") if ($verbose_warn_install);
393	printf("\n\tsudo apt-get install $install\n");
394}
395
396sub give_redhat_hints()
397{
398	my %map = (
399		"python-sphinx"		=> "python3-sphinx",
400		"sphinx_rtd_theme"	=> "python3-sphinx_rtd_theme",
401		"virtualenv"		=> "python3-virtualenv",
402		"dot"			=> "graphviz",
403		"convert"		=> "ImageMagick",
404		"Pod::Usage"		=> "perl-Pod-Usage",
405		"xelatex"		=> "texlive-xetex-bin",
406		"rsvg-convert"		=> "librsvg2-tools",
407	);
408
409	my @fedora26_opt_pkgs = (
410		"graphviz-gd",		# Fedora 26: needed for PDF support
411	);
412
413	my @fedora_tex_pkgs = (
414		"texlive-collection-fontsrecommended",
415		"texlive-collection-latex",
416		"texlive-xecjk",
417		"dejavu-sans-fonts",
418		"dejavu-serif-fonts",
419		"dejavu-sans-mono-fonts",
420	);
421
422	#
423	# Checks valid for RHEL/CentOS version 7.x.
424	#
425	my $old = 0;
426	my $rel;
427	$rel = $1 if ($system_release =~ /release\s+(\d+)/);
428
429	if (!($system_release =~ /Fedora/)) {
430		$map{"virtualenv"} = "python-virtualenv";
431
432		if ($rel && $rel < 8) {
433			$old = 1;
434			$pdf = 0;
435
436			printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n");
437			printf("If you want to build PDF, please read:\n");
438			printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n");
439		}
440	} else {
441		if ($rel && $rel < 26) {
442			$old = 1;
443		}
444	}
445	if (!$rel) {
446		printf("Couldn't identify release number\n");
447		$old = 1;
448		$pdf = 0;
449	}
450
451	if ($pdf) {
452		check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"],
453				   "google-noto-sans-cjk-ttc-fonts", 2);
454	}
455
456	check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old);
457	check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf);
458	check_missing_tex(2) if ($pdf);
459	check_missing(\%map);
460
461	return if (!$need && !$optional);
462
463	if (!$old) {
464		# dnf, for Fedora 18+
465		printf("You should run:\n") if ($verbose_warn_install);
466		printf("\n\tsudo dnf install -y $install\n");
467	} else {
468		# yum, for RHEL (and clones) or Fedora version < 18
469		printf("You should run:\n") if ($verbose_warn_install);
470		printf("\n\tsudo yum install -y $install\n");
471	}
472}
473
474sub give_opensuse_hints()
475{
476	my %map = (
477		"python-sphinx"		=> "python3-sphinx",
478		"sphinx_rtd_theme"	=> "python3-sphinx_rtd_theme",
479		"virtualenv"		=> "python3-virtualenv",
480		"dot"			=> "graphviz",
481		"convert"		=> "ImageMagick",
482		"Pod::Usage"		=> "perl-Pod-Usage",
483		"xelatex"		=> "texlive-xetex-bin",
484	);
485
486	# On Tumbleweed, this package is also named rsvg-convert
487	$map{"rsvg-convert"} = "rsvg-view" if (!($system_release =~ /Tumbleweed/));
488
489	my @suse_tex_pkgs = (
490		"texlive-babel-english",
491		"texlive-caption",
492		"texlive-colortbl",
493		"texlive-courier",
494		"texlive-dvips",
495		"texlive-helvetic",
496		"texlive-makeindex",
497		"texlive-metafont",
498		"texlive-metapost",
499		"texlive-palatino",
500		"texlive-preview",
501		"texlive-times",
502		"texlive-zapfchan",
503		"texlive-zapfding",
504	);
505
506	$map{"latexmk"} = "texlive-latexmk-bin";
507
508	# FIXME: add support for installing CJK fonts
509	#
510	# I tried hard, but was unable to find a way to install
511	# "Noto Sans CJK SC" on openSUSE
512
513	check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf);
514	check_missing_tex(2) if ($pdf);
515	check_missing(\%map);
516
517	return if (!$need && !$optional);
518	printf("You should run:\n") if ($verbose_warn_install);
519	printf("\n\tsudo zypper install --no-recommends $install\n");
520}
521
522sub give_mageia_hints()
523{
524	my %map = (
525		"python-sphinx"		=> "python3-sphinx",
526		"sphinx_rtd_theme"	=> "python3-sphinx_rtd_theme",
527		"virtualenv"		=> "python3-virtualenv",
528		"dot"			=> "graphviz",
529		"convert"		=> "ImageMagick",
530		"Pod::Usage"		=> "perl-Pod-Usage",
531		"xelatex"		=> "texlive",
532		"rsvg-convert"		=> "librsvg2",
533	);
534
535	my @tex_pkgs = (
536		"texlive-fontsextra",
537	);
538
539	$map{"latexmk"} = "texlive-collection-basic";
540
541	my $packager_cmd;
542	my $noto_sans;
543	if ($system_release =~ /OpenMandriva/) {
544		$packager_cmd = "dnf install";
545		$noto_sans = "noto-sans-cjk-fonts";
546		@tex_pkgs = ( "texlive-collection-fontsextra" );
547	} else {
548		$packager_cmd = "urpmi";
549		$noto_sans = "google-noto-sans-cjk-ttc-fonts";
550	}
551
552
553	if ($pdf) {
554		check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
555				    "/usr/share/fonts/TTF/NotoSans-Regular.ttf"],
556				   $noto_sans, 2);
557	}
558
559	check_rpm_missing(\@tex_pkgs, 2) if ($pdf);
560	check_missing(\%map);
561
562	return if (!$need && !$optional);
563	printf("You should run:\n") if ($verbose_warn_install);
564	printf("\n\tsudo $packager_cmd $install\n");
565}
566
567sub give_arch_linux_hints()
568{
569	my %map = (
570		"sphinx_rtd_theme"	=> "python-sphinx_rtd_theme",
571		"virtualenv"		=> "python-virtualenv",
572		"dot"			=> "graphviz",
573		"convert"		=> "imagemagick",
574		"xelatex"		=> "texlive-bin",
575		"latexmk"		=> "texlive-core",
576		"rsvg-convert"		=> "extra/librsvg",
577	);
578
579	my @archlinux_tex_pkgs = (
580		"texlive-core",
581		"texlive-latexextra",
582		"ttf-dejavu",
583	);
584	check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf);
585
586	if ($pdf) {
587		check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"],
588				   "noto-fonts-cjk", 2);
589	}
590
591	check_missing(\%map);
592
593	return if (!$need && !$optional);
594	printf("You should run:\n") if ($verbose_warn_install);
595	printf("\n\tsudo pacman -S $install\n");
596}
597
598sub give_gentoo_hints()
599{
600	my %map = (
601		"sphinx_rtd_theme"	=> "dev-python/sphinx_rtd_theme",
602		"virtualenv"		=> "dev-python/virtualenv",
603		"dot"			=> "media-gfx/graphviz",
604		"convert"		=> "media-gfx/imagemagick",
605		"xelatex"		=> "dev-texlive/texlive-xetex media-fonts/dejavu",
606		"rsvg-convert"		=> "gnome-base/librsvg",
607	);
608
609	check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"],
610			   "media-fonts/dejavu", 2) if ($pdf);
611
612	if ($pdf) {
613		check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf",
614				    "/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc"],
615				   "media-fonts/noto-cjk", 2);
616	}
617
618	check_missing(\%map);
619
620	return if (!$need && !$optional);
621
622	printf("You should run:\n") if ($verbose_warn_install);
623	printf("\n");
624
625	my $imagemagick = "media-gfx/imagemagick svg png";
626	my $cairo = "media-gfx/graphviz cairo pdf";
627	my $portage_imagemagick = "/etc/portage/package.use/imagemagick";
628	my $portage_cairo = "/etc/portage/package.use/graphviz";
629
630	if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") {
631		printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n")
632	}
633	if (qx(grep graphviz $portage_cairo 2>/dev/null) eq  "") {
634		printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n");
635	}
636
637	printf("\tsudo emerge --ask $install\n");
638
639}
640
641sub check_distros()
642{
643	# Distro-specific hints
644	if ($system_release =~ /Red Hat Enterprise Linux/) {
645		give_redhat_hints;
646		return;
647	}
648	if ($system_release =~ /CentOS/) {
649		give_redhat_hints;
650		return;
651	}
652	if ($system_release =~ /Scientific Linux/) {
653		give_redhat_hints;
654		return;
655	}
656	if ($system_release =~ /Oracle Linux Server/) {
657		give_redhat_hints;
658		return;
659	}
660	if ($system_release =~ /Fedora/) {
661		give_redhat_hints;
662		return;
663	}
664	if ($system_release =~ /Ubuntu/) {
665		give_debian_hints;
666		return;
667	}
668	if ($system_release =~ /Debian/) {
669		give_debian_hints;
670		return;
671	}
672	if ($system_release =~ /openSUSE/) {
673		give_opensuse_hints;
674		return;
675	}
676	if ($system_release =~ /Mageia/) {
677		give_mageia_hints;
678		return;
679	}
680	if ($system_release =~ /OpenMandriva/) {
681		give_mageia_hints;
682		return;
683	}
684	if ($system_release =~ /Arch Linux/) {
685		give_arch_linux_hints;
686		return;
687	}
688	if ($system_release =~ /Gentoo/) {
689		give_gentoo_hints;
690		return;
691	}
692
693	#
694	# Fall-back to generic hint code for other distros
695	# That's far from ideal, specially for LaTeX dependencies.
696	#
697	my %map = (
698		"sphinx-build" => "sphinx"
699	);
700	check_missing_tex(2) if ($pdf);
701	check_missing(\%map);
702	print "I don't know distro $system_release.\n";
703	print "So, I can't provide you a hint with the install procedure.\n";
704	print "There are likely missing dependencies.\n";
705}
706
707#
708# Common dependencies
709#
710
711sub deactivate_help()
712{
713	printf "\n    If you want to exit the virtualenv, you can use:\n";
714	printf "\tdeactivate\n";
715}
716
717sub get_virtenv()
718{
719	my $ver;
720	my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate";
721	my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate";
722
723	@activates = sort {$b cmp $a} @activates;
724
725	foreach my $f (@activates) {
726		next if ($f lt $min_activate);
727
728		my $sphinx_cmd = $f;
729		$sphinx_cmd =~ s/activate/sphinx-build/;
730		next if (! -f $sphinx_cmd);
731
732		my $ver = get_sphinx_version($sphinx_cmd);
733
734		if (!$ver) {
735			$f =~ s#/bin/activate##;
736			print("Warning: virtual environment $f is not working.\nPython version upgrade? Remove it with:\n\n\trm -rf $f\n\n");
737		}
738
739		if ($need_sphinx && ($ver ge $min_version)) {
740			return ($f, $ver);
741		} elsif ($ver gt $cur_version) {
742			return ($f, $ver);
743		}
744	}
745	return ("", "");
746}
747
748sub recommend_sphinx_upgrade()
749{
750	my $venv_ver;
751
752	# Avoid running sphinx-builds from venv if $cur_version is good
753	if ($cur_version && ($cur_version ge $rec_version)) {
754		$latest_avail_ver = $cur_version;
755		return;
756	}
757
758	# Get the highest version from sphinx_*/bin/sphinx-build and the
759	# corresponding command to activate the venv/virtenv
760	($activate_cmd, $venv_ver) = get_virtenv();
761
762	# Store the highest version from Sphinx existing virtualenvs
763	if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) {
764		$latest_avail_ver = $venv_ver;
765	} else {
766		$latest_avail_ver = $cur_version if ($cur_version);
767	}
768
769	# As we don't know package version of Sphinx, and there's no
770	# virtual environments, don't check if upgrades are needed
771	if (!$virtualenv) {
772		return if (!$latest_avail_ver);
773	}
774
775	# Either there are already a virtual env or a new one should be created
776	$need_pip = 1;
777
778	return if (!$latest_avail_ver);
779
780	# Return if the reason is due to an upgrade or not
781	if ($latest_avail_ver lt $rec_version) {
782		$rec_sphinx_upgrade = 1;
783	}
784
785	return $latest_avail_ver;
786}
787
788#
789# The logic here is complex, as it have to deal with different versions:
790#	- minimal supported version;
791#	- minimal PDF version;
792#	- recommended version.
793# It also needs to work fine with both distro's package and venv/virtualenv
794sub recommend_sphinx_version($)
795{
796	my $virtualenv_cmd = shift;
797
798	# Version is OK. Nothing to do.
799	if ($cur_version && ($cur_version ge $rec_version)) {
800		if ($cur_version lt $min_pdf_version) {
801			print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
802		}
803		return;
804	};
805
806	if (!$need_sphinx) {
807		# sphinx-build is present and its version is >= $min_version
808
809		#only recommend enabling a newer virtenv version if makes sense.
810		if ($latest_avail_ver gt $cur_version) {
811			printf "\nYou may also use the newer Sphinx version $latest_avail_ver with:\n";
812			printf "\tdeactivate\n"  if ($ENV{'PWD'} =~ /${virtenv_prefix}/);
813			printf "\t. $activate_cmd\n";
814			deactivate_help();
815
816			return;
817		}
818		return if ($latest_avail_ver ge $rec_version);
819	}
820
821	if (!$virtualenv) {
822		# No sphinx either via package or via virtenv. As we can't
823		# Compare the versions here, just return, recommending the
824		# user to install it from the package distro.
825		return if (!$latest_avail_ver);
826
827		# User doesn't want a virtenv recommendation, but he already
828		# installed one via virtenv with a newer version.
829		# So, print commands to enable it
830		if ($latest_avail_ver gt $cur_version) {
831			printf "\nYou may also use the Sphinx virtualenv version $latest_avail_ver with:\n";
832			printf "\tdeactivate\n"  if ($ENV{'PWD'} =~ /${virtenv_prefix}/);
833			printf "\t. $activate_cmd\n";
834			deactivate_help();
835
836			return;
837		}
838		print "\n";
839	} else {
840		$need++ if ($need_sphinx);
841	}
842
843	# Suggest newer versions if current ones are too old
844	if ($latest_avail_ver && $latest_avail_ver ge $min_version) {
845		# If there's a good enough version, ask the user to enable it
846		if ($latest_avail_ver ge $rec_version) {
847			printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n";
848			printf "\t. $activate_cmd\n";
849			deactivate_help();
850
851			if ($latest_avail_ver lt $min_pdf_version) {
852				print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
853			}
854
855			return;
856		}
857
858		# Version is above the minimal required one, but may be
859		# below the recommended one. So, print warnings/notes
860
861		if ($latest_avail_ver lt $rec_version) {
862			print "Warning: It is recommended at least Sphinx version $rec_version.\n";
863		}
864	}
865
866	# At this point, either it needs Sphinx or upgrade is recommended,
867	# both via pip
868
869	if ($rec_sphinx_upgrade) {
870		if (!$virtualenv) {
871			print "Instead of install/upgrade Python Sphinx pkg, you could use pip/pypi with:\n\n";
872		} else {
873			print "To upgrade Sphinx, use:\n\n";
874		}
875	} else {
876		print "\nSphinx needs to be installed either:\n1) via pip/pypi with:\n\n";
877	}
878
879	$python_cmd = find_python_no_venv();
880
881	printf "\t$virtualenv_cmd $virtenv_dir\n";
882
883	printf "\t. $virtenv_dir/bin/activate\n";
884	printf "\tpip install -r $requirement_file\n";
885	deactivate_help();
886
887	printf "\n2) As a package with:\n";
888
889	my $old_need = $need;
890	my $old_optional = $optional;
891	%missing = ();
892	$pdf = 0;
893	$optional = 0;
894	$install = "";
895	$verbose_warn_install = 0;
896
897	add_package("python-sphinx", 0);
898	check_python_module("sphinx_rtd_theme", 1);
899
900	check_distros();
901
902	$need = $old_need;
903	$optional = $old_optional;
904
905	printf "\n    Please note that Sphinx >= 3.0 will currently produce false-positive\n";
906	printf "   warning when the same name is used for more than one type (functions,\n";
907	printf "   structs, enums,...). This is known Sphinx bug. For more details, see:\n";
908	printf "\thttps://github.com/sphinx-doc/sphinx/pull/8313\n";
909}
910
911sub check_needs()
912{
913	# Check if Sphinx is already accessible from current environment
914	check_sphinx();
915
916	if ($system_release) {
917		print "Detected OS: $system_release.\n";
918	} else {
919		print "Unknown OS\n";
920	}
921	printf "Sphinx version: %s\n\n", $cur_version if ($cur_version);
922
923	# Check python command line, trying first python3
924	$python_cmd = findprog("python3");
925	$python_cmd = check_program("python", 0) if (!$python_cmd);
926
927	# Check the type of virtual env, depending on Python version
928	if ($python_cmd) {
929		if ($virtualenv) {
930			my $tmp = qx($python_cmd --version 2>&1);
931			if ($tmp =~ m/(\d+\.)(\d+\.)/) {
932				if ($1 < 3) {
933					# Fail if it finds python2 (or worse)
934					die "Python 3 is required to build the kernel docs\n";
935				}
936				if ($1 == 3 && $2 < 3) {
937					# Need Python 3.3 or upper for venv
938					$need_virtualenv = 1;
939				}
940			} else {
941				die "Warning: couldn't identify $python_cmd version!";
942			}
943		} else {
944			add_package("python-sphinx", 0);
945		}
946	}
947
948	my $venv_ver = recommend_sphinx_upgrade();
949
950	my $virtualenv_cmd;
951
952	if ($need_pip) {
953		# Set virtualenv command line, if python < 3.3
954		if ($need_virtualenv) {
955			$virtualenv_cmd = findprog("virtualenv-3");
956			$virtualenv_cmd = findprog("virtualenv-3.5") if (!$virtualenv_cmd);
957			if (!$virtualenv_cmd) {
958				check_program("virtualenv", 0);
959				$virtualenv_cmd = "virtualenv";
960			}
961		} else {
962			$virtualenv_cmd = "$python_cmd -m venv";
963			check_python_module("ensurepip", 0);
964		}
965	}
966
967	# Check for needed programs/tools
968	check_perl_module("Pod::Usage", 0);
969	check_program("make", 0);
970	check_program("gcc", 0);
971	check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv);
972	check_program("dot", 1);
973	check_program("convert", 1);
974
975	# Extra PDF files - should use 2 for is_optional
976	check_program("xelatex", 2) if ($pdf);
977	check_program("rsvg-convert", 2) if ($pdf);
978	check_program("latexmk", 2) if ($pdf);
979
980	# Do distro-specific checks and output distro-install commands
981	check_distros();
982
983	if (!$python_cmd) {
984		if ($need == 1) {
985			die "Can't build as $need mandatory dependency is missing";
986		} elsif ($need) {
987			die "Can't build as $need mandatory dependencies are missing";
988		}
989	}
990
991	# Check if sphinx-build is called sphinx-build-3
992	if ($need_symlink) {
993		printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n",
994		       which("sphinx-build-3");
995	}
996
997	recommend_sphinx_version($virtualenv_cmd);
998	printf "\n";
999
1000	print "All optional dependencies are met.\n" if (!$optional);
1001
1002	if ($need == 1) {
1003		die "Can't build as $need mandatory dependency is missing";
1004	} elsif ($need) {
1005		die "Can't build as $need mandatory dependencies are missing";
1006	}
1007
1008	print "Needed package dependencies are met.\n";
1009}
1010
1011#
1012# Main
1013#
1014
1015while (@ARGV) {
1016	my $arg = shift(@ARGV);
1017
1018	if ($arg eq "--no-virtualenv") {
1019		$virtualenv = 0;
1020	} elsif ($arg eq "--no-pdf"){
1021		$pdf = 0;
1022	} elsif ($arg eq "--version-check"){
1023		$version_check = 1;
1024	} else {
1025		print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
1026		print "Where:\n";
1027		print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
1028		print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
1029		print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
1030		exit -1;
1031	}
1032}
1033
1034#
1035# Determine the system type. There's no standard unique way that would
1036# work with all distros with a minimal package install. So, several
1037# methods are used here.
1038#
1039# By default, it will use lsb_release function. If not available, it will
1040# fail back to reading the known different places where the distro name
1041# is stored
1042#
1043
1044$system_release = qx(lsb_release -d) if which("lsb_release");
1045$system_release =~ s/Description:\s*// if ($system_release);
1046$system_release = catcheck("/etc/system-release") if !$system_release;
1047$system_release = catcheck("/etc/redhat-release") if !$system_release;
1048$system_release = catcheck("/etc/lsb-release") if !$system_release;
1049$system_release = catcheck("/etc/gentoo-release") if !$system_release;
1050
1051# This seems more common than LSB these days
1052if (!$system_release) {
1053	my %os_var;
1054	if (open IN, "cat /etc/os-release|") {
1055		while (<IN>) {
1056			if (m/^([\w\d\_]+)=\"?([^\"]*)\"?\n/) {
1057				$os_var{$1}=$2;
1058			}
1059		}
1060		$system_release = $os_var{"NAME"};
1061		if (defined($os_var{"VERSION_ID"})) {
1062			$system_release .= " " . $os_var{"VERSION_ID"} if (defined($os_var{"VERSION_ID"}));
1063		} else {
1064			$system_release .= " " . $os_var{"VERSION"};
1065		}
1066	}
1067}
1068$system_release = catcheck("/etc/issue") if !$system_release;
1069$system_release =~ s/\s+$//;
1070
1071check_needs;
1072