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