summaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/get_feat.pl2
-rwxr-xr-xscripts/kernel-doc82
-rwxr-xr-xscripts/sphinx-pre-install90
3 files changed, 105 insertions, 69 deletions
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 76cfb96b59b6..5c5397eeb237 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -1,4 +1,4 @@
-#!/usr/bin/perl
+#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
use strict;
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 7516949bb049..aea04365bc69 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -427,6 +427,13 @@ sub print_lineno {
print ".. LINENO " . $lineno . "\n";
}
}
+
+sub emit_warning {
+ my $location = shift;
+ my $msg = shift;
+ print STDERR "$location: warning: $msg";
+ ++$warnings;
+}
##
# dumps section contents to arrays/hashes intended for that purpose.
#
@@ -451,8 +458,7 @@ sub dump_section {
if (defined($sections{$name}) && ($sections{$name} ne "")) {
# Only warn on user specified duplicate section names.
if ($name ne $section_default) {
- print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
- ++$warnings;
+ emit_warning("${file}:$.", "duplicate section name '$name'\n");
}
$sections{$name} .= $contents;
} else {
@@ -1094,7 +1100,7 @@ sub dump_struct($$) {
if ($members) {
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
return;
}
@@ -1298,9 +1304,9 @@ sub dump_enum($$) {
if ($members) {
if ($identifier ne $declaration_name) {
if ($identifier eq "") {
- print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
} else {
- print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
}
return;
}
@@ -1316,7 +1322,7 @@ sub dump_enum($$) {
if (!$parameterdescs{$arg}) {
$parameterdescs{$arg} = $undescribed;
if (show_warnings("enum", $declaration_name)) {
- print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
+ emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
}
}
$_members{$arg} = 1;
@@ -1325,7 +1331,7 @@ sub dump_enum($$) {
while (my ($k, $v) = each %parameterdescs) {
if (!exists($_members{$k})) {
if (show_warnings("enum", $declaration_name)) {
- print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
+ emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
}
}
}
@@ -1367,7 +1373,7 @@ sub dump_typedef($$) {
$return_type =~ s/^\s+//;
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
return;
}
@@ -1398,7 +1404,7 @@ sub dump_typedef($$) {
$declaration_name = $1;
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
return;
}
@@ -1554,9 +1560,7 @@ sub push_parameter($$$$$) {
$parameterdescs{$param} = $undescribed;
if (show_warnings($type, $declaration_name) && $param !~ /\./) {
- print STDERR
- "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
}
}
@@ -1604,11 +1608,10 @@ sub check_sections($$$$$) {
}
if ($err) {
if ($decl_type eq "function") {
- print STDERR "${file}:$.: warning: " .
+ emit_warning("${file}:$.",
"Excess function parameter " .
"'$sects[$sx]' " .
- "description in '$decl_name'\n";
- ++$warnings;
+ "description in '$decl_name'\n");
}
}
}
@@ -1629,10 +1632,9 @@ sub check_return_section {
if (!defined($sections{$section_return}) ||
$sections{$section_return} eq "") {
- print STDERR "${file}:$.: warning: " .
+ emit_warning("${file}:$.",
"No description found for return value of " .
- "'$declaration_name'\n";
- ++$warnings;
+ "'$declaration_name'\n");
}
}
@@ -1714,12 +1716,12 @@ sub dump_function($$) {
create_parameterlist($args, ',', $file, $declaration_name);
} else {
- print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
+ emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
return;
}
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+ emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
return;
}
@@ -1801,8 +1803,8 @@ sub tracepoint_munge($) {
$tracepointargs = $1;
}
if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
- print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
- "$prototype\n";
+ emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
+ "$prototype\n");
} else {
$prototype = "static inline void trace_$tracepointname($tracepointargs)";
$identifier = "trace_$identifier";
@@ -2027,22 +2029,16 @@ sub process_name($$) {
}
if (!$is_kernel_comment) {
- print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
$state = STATE_NORMAL;
}
if (($declaration_purpose eq "") && $verbose) {
- print STDERR "${file}:$.: warning: missing initial short description on line:\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "missing initial short description on line:\n$_");
}
if ($identifier eq "" && $decl_type ne "enum") {
- print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
$state = STATE_NORMAL;
}
@@ -2050,9 +2046,7 @@ sub process_name($$) {
print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
}
} else {
- print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
- " - I thought it was a doc line\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
$state = STATE_NORMAL;
}
}
@@ -2071,8 +2065,7 @@ sub process_body($$) {
$section =~ s/\.\.\.$//;
if ($verbose) {
- print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
}
}
@@ -2101,8 +2094,7 @@ sub process_body($$) {
if (($contents ne "") && ($contents ne "\n")) {
if (!$in_doc_sect && $verbose) {
- print STDERR "${file}:$.: warning: contents before sections\n";
- ++$warnings;
+ emit_warning("${file}:$.", "contents before sections\n");
}
dump_section($file, $section, $contents);
$section = $section_default;
@@ -2128,8 +2120,7 @@ sub process_body($$) {
}
# look for doc_com + <text> + doc_end:
if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
- print STDERR "${file}:$.: warning: suspicious ending line: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "suspicious ending line: $_");
}
$prototype = "";
@@ -2173,8 +2164,7 @@ sub process_body($$) {
}
} else {
# i dont know - bad line? ignore.
- print STDERR "${file}:$.: warning: bad line: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "bad line: $_");
}
}
@@ -2268,9 +2258,7 @@ sub process_inline($$) {
}
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
$inline_doc_state = STATE_INLINE_ERROR;
- print STDERR "${file}:$.: warning: ";
- print STDERR "Incorrect use of kernel-doc format: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
}
}
}
@@ -2319,11 +2307,11 @@ sub process_file($) {
if ($initial_section_counter == $section_counter && $
output_mode ne "none") {
if ($output_selection == OUTPUT_INCLUDE) {
- print STDERR "${file}:1: warning: '$_' not found\n"
+ emit_warning("${file}:1", "'$_' not found\n")
for keys %function_table;
}
else {
- print STDERR "${file}:1: warning: no structured comments found\n";
+ emit_warning("${file}:1", "no structured comments found\n");
}
}
close IN_FILE;
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f126ecbb0494..ec84fc62774e 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -25,6 +25,7 @@ my $need_sphinx = 0;
my $need_pip = 0;
my $need_virtualenv = 0;
my $rec_sphinx_upgrade = 0;
+my $verbose_warn_install = 1;
my $install = "";
my $virtenv_dir = "";
my $python_cmd = "";
@@ -103,10 +104,12 @@ sub check_missing(%)
next;
}
- if ($is_optional) {
- print "Warning: better to also install \"$prog\".\n";
- } else {
- print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
+ if ($verbose_warn_install) {
+ if ($is_optional) {
+ print "Warning: better to also install \"$prog\".\n";
+ } else {
+ print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
+ }
}
if (defined($map{$prog})) {
$install .= " " . $map{$prog};
@@ -386,7 +389,8 @@ sub give_debian_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo apt-get install $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo apt-get install $install\n");
}
sub give_redhat_hints()
@@ -458,10 +462,12 @@ sub give_redhat_hints()
if (!$old) {
# dnf, for Fedora 18+
- printf("You should run:\n\n\tsudo dnf install -y $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo dnf install -y $install\n");
} else {
# yum, for RHEL (and clones) or Fedora version < 18
- printf("You should run:\n\n\tsudo yum install -y $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo yum install -y $install\n");
}
}
@@ -509,7 +515,8 @@ sub give_opensuse_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo zypper install --no-recommends $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo zypper install --no-recommends $install\n");
}
sub give_mageia_hints()
@@ -553,7 +560,8 @@ sub give_mageia_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo $packager_cmd $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo $packager_cmd $install\n");
}
sub give_arch_linux_hints()
@@ -583,7 +591,8 @@ sub give_arch_linux_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo pacman -S $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo pacman -S $install\n");
}
sub give_gentoo_hints()
@@ -610,7 +619,8 @@ sub give_gentoo_hints()
return if (!$need && !$optional);
- printf("You should run:\n\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n");
my $imagemagick = "media-gfx/imagemagick svg png";
my $cairo = "media-gfx/graphviz cairo pdf";
@@ -700,7 +710,7 @@ sub check_distros()
sub deactivate_help()
{
- printf "\nIf you want to exit the virtualenv, you can use:\n";
+ printf "\n If you want to exit the virtualenv, you can use:\n";
printf "\tdeactivate\n";
}
@@ -720,6 +730,12 @@ sub get_virtenv()
next if (! -f $sphinx_cmd);
my $ver = get_sphinx_version($sphinx_cmd);
+
+ if (!$ver) {
+ $f =~ s#/bin/activate##;
+ print("Warning: virtual environment $f is not working.\nPython version upgrade? Remove it with:\n\n\trm -rf $f\n\n");
+ }
+
if ($need_sphinx && ($ver ge $min_version)) {
return ($f, $ver);
} elsif ($ver gt $cur_version) {
@@ -741,7 +757,7 @@ sub recommend_sphinx_upgrade()
# Get the highest version from sphinx_*/bin/sphinx-build and the
# corresponding command to activate the venv/virtenv
- $activate_cmd = get_virtenv();
+ ($activate_cmd, $venv_ver) = get_virtenv();
# Store the highest version from Sphinx existing virtualenvs
if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) {
@@ -759,10 +775,14 @@ sub recommend_sphinx_upgrade()
# Either there are already a virtual env or a new one should be created
$need_pip = 1;
+ return if (!$latest_avail_ver);
+
# Return if the reason is due to an upgrade or not
if ($latest_avail_ver lt $rec_version) {
$rec_sphinx_upgrade = 1;
}
+
+ return $latest_avail_ver;
}
#
@@ -775,12 +795,13 @@ sub recommend_sphinx_version($)
{
my $virtualenv_cmd = shift;
- if ($latest_avail_ver lt $min_pdf_version) {
- print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
- }
-
# Version is OK. Nothing to do.
- return if ($cur_version && ($cur_version ge $rec_version));
+ if ($cur_version && ($cur_version ge $rec_version)) {
+ if ($cur_version lt $min_pdf_version) {
+ print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
+ }
+ return;
+ };
if (!$need_sphinx) {
# sphinx-build is present and its version is >= $min_version
@@ -820,13 +841,17 @@ sub recommend_sphinx_version($)
}
# Suggest newer versions if current ones are too old
- if ($latest_avail_ver && $cur_version ge $min_version) {
+ if ($latest_avail_ver && $latest_avail_ver ge $min_version) {
# If there's a good enough version, ask the user to enable it
if ($latest_avail_ver ge $rec_version) {
printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n";
printf "\t. $activate_cmd\n";
deactivate_help();
+ if ($latest_avail_ver lt $min_pdf_version) {
+ print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
+ }
+
return;
}
@@ -848,7 +873,7 @@ sub recommend_sphinx_version($)
print "To upgrade Sphinx, use:\n\n";
}
} else {
- print "Sphinx needs to be installed either as a package or via pip/pypi with:\n";
+ print "\nSphinx needs to be installed either:\n1) via pip/pypi with:\n\n";
}
$python_cmd = find_python_no_venv();
@@ -858,6 +883,29 @@ sub recommend_sphinx_version($)
printf "\t. $virtenv_dir/bin/activate\n";
printf "\tpip install -r $requirement_file\n";
deactivate_help();
+
+ printf "\n2) As a package with:\n";
+
+ my $old_need = $need;
+ my $old_optional = $optional;
+ %missing = ();
+ $pdf = 0;
+ $optional = 0;
+ $install = "";
+ $verbose_warn_install = 0;
+
+ add_package("python-sphinx", 0);
+ check_python_module("sphinx_rtd_theme", 1);
+
+ check_distros();
+
+ $need = $old_need;
+ $optional = $old_optional;
+
+ printf "\n Please note that Sphinx >= 3.0 will currently produce false-positive\n";
+ printf " warning when the same name is used for more than one type (functions,\n";
+ printf " structs, enums,...). This is known Sphinx bug. For more details, see:\n";
+ printf "\thttps://github.com/sphinx-doc/sphinx/pull/8313\n";
}
sub check_needs()
@@ -897,7 +945,7 @@ sub check_needs()
}
}
- recommend_sphinx_upgrade();
+ my $venv_ver = recommend_sphinx_upgrade();
my $virtualenv_cmd;
generated by cgit v1.2.3 (git 2.39.0) at 2024-12-01 15:28:50 +0300