[debhelper-devel] [RFC 1/4] add DH_QUIET environment variable

[Bernhard R. Link]

Add a DH_QUIET environment variable to make debhelper more silent
if set (unless DH_VERBOSE is set).
Add new helper functions print_and_doit, print_and_doint_noerror,
and nonquiet_print.
If DH_QUIET is set, disable printing of dh subcommands to be run.
Describe effects DH_QUIET should have in doc/PROGRAMMING.

Signed-off-by: Bernhard R. Link <brlink at debian.org>
---
 Debian/Debhelper/Dh_Lib.pm | 29 ++++++++++++++++++++++++++++-
 debhelper.pod              |  9 +++++++++
 dh                         |  4 +++-
 doc/PROGRAMMING            | 11 +++++++++++
 4 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/Debian/Debhelper/Dh_Lib.pm b/Debian/Debhelper/Dh_Lib.pm
index 0519d20..25a9de2 100644
--- a/Debian/Debhelper/Dh_Lib.pm
+++ b/Debian/Debhelper/Dh_Lib.pm
@@ -11,6 +11,7 @@ use Exporter;
 use vars qw(@ISA @EXPORT %dh);
 @ISA=qw(Exporter);
 @EXPORT=qw(&init &doit &doit_noerror &complex_doit &verbose_print &error
+            &nonquiet_print &print_and_doit &print_and_doit_noerror
             &warning &tmpdir &pkgfile &pkgext &pkgfilename &isnative
 	    &autoscript &filearray &filedoublearray
 	    &getpackages &basename &dirname &xargs %dh
@@ -59,9 +60,11 @@ sub init {
 	}
 	
 	# Check to see if DH_VERBOSE environment variable was set, if so,
-	# make sure verbose is on.
+	# make sure verbose is on. Otherwise, check DH_QUIET.
 	if (defined $ENV{DH_VERBOSE} && $ENV{DH_VERBOSE} ne "") {
 		$dh{VERBOSE}=1;
+	} elsif (defined $ENV{DH_QUIET} && $ENV{DH_QUIET} ne "") {
+		$dh{QUIET}=1;
 	}
 
 	# Check to see if DH_NO_ACT environment variable was set, if so, 
@@ -229,6 +232,21 @@ sub doit_noerror {
 	}
 }
 
+sub print_and_doit {
+	print_and_doit_noerror(@_) || _error_exitcode(join(" ", @_));
+}
+
+sub print_and_doit_noerror {
+	nonquiet_print(escape_shell(@_));
+
+	if (! $dh{NO_ACT}) {
+		return (system(@_) == 0)
+	}
+	else {
+		return 1;
+	}
+}
+
 # Run a command and display the command to stdout if verbose mode is on.
 # Use doit() if you can, instead of this function, because this function
 # forks a shell. However, this function can handle more complicated stuff
@@ -301,6 +319,15 @@ sub verbose_print {
 	}
 }
 
+# Print something unless the quiet flag is on
+sub nonquiet_print {
+	my $message=shift;
+
+	if (!$dh{QUIET}) {
+		print "\t$message\n";
+	}
+}
+
 # Output an error message and die (can be caught).
 sub error {
 	my $message=shift;
diff --git a/debhelper.pod b/debhelper.pod
index cc9989a..9c39af8 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -660,6 +660,15 @@ F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc.
 Set to B<1> to enable verbose mode. Debhelper will output every command it
 runs. Also enables verbose build logs for some build systems like autoconf.
 
+=item B<DH_QUIET>
+
+Set to B<1> to enable quiet mode. Debhelper will not output commands calling
+the upstream build system nor will dh print which subcommands are called
+and depending on the upstream build system might make that more quiet, too.
+This makes it easier to spot important messages but makes the output quite
+useless as buildd log.
+Ignored if DH_VERBOSE is also set.
+
 =item B<DH_COMPAT>
 
 Temporarily specifies what compatibility level debhelper should run at,
diff --git a/dh b/dh
index f3bd321..a5d8900 100755
--- a/dh
+++ b/dh
@@ -713,7 +713,9 @@ sub run {
 
 	# 3 space indent lines the command being run up under the
 	# sequence name after "dh ".
-	print "   ".escape_shell($command, @options)."\n";
+	if (!$dh{QUIET}) {
+		print "   ".escape_shell($command, @options)."\n";
+	}
 
 	return if $dh{NO_ACT};
 			
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index e7b6e35..cba4704 100644
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -18,6 +18,11 @@ output the commands, you should indent them with 1 tab). This is so we don't
 have a lot of noise output when all the debhelper commands in a debian/rules
 are run, so the important stuff is clearly visible.
 
+An exception to above rule are dh_auto_* commands and dh itself. They will
+also print the commands interacting with the upstream build system and which
+of the simple debhelper programms are called. (i.e. print what a traditional
+non-dh(1) using debian/rules would print but nothing else).
+
 Debhelper programs should accept all options listed in the "SHARED
 DEBHELPER OPTIONS" section of debhelper(7), including any long forms of
 these options, like --verbose . If necessary, the options may be ignored.
@@ -152,6 +157,9 @@ doit(@command)
 	if $dh{VERBOSE} is set, it will also output the command to stdout. You
 	should use this function for almost all commands your program performs
 	that manipulate files in the package build directories.
+print_and_doit(@command)
+        Like doit but will print unless $dh{QUIET} is set. See "Standardization"
+        above for when this is allowed to be called.
 complex_doit($command)
 	Pass this function a string that is a shell command, it will run it
 	similarly to how doit() does. You can pass more complicated commands 
@@ -159,6 +167,9 @@ complex_doit($command)
 	have to worry about things like escaping shell metacharacters.
 verbose_print($message)
 	Pass this command a string, and it will echo it if $dh{VERBOSE} is set.
+nonquiet_print($message)
+	Pass this command a string, and it will echo it unless $dh{QUIET} is set.
+	See "Standardization" above for when this is allowed to be called.
 error($errormsg)
 	Pass this command a string, it will output it to standard error and
 	exit.
-- 
2.1.4

	Bernhard R. Link
-- 
F8AC 04D5 0B9B 064B 3383  C3DA AFFC 96D1 151D FFDC