[debhelper-devel] [debhelper] 01/01: dh_testroot: Document behaviour under R³

[Niels Thykier]

This is an automated email from the git hooks/post-receive script.

nthykier pushed a commit to branch master
in repository debhelper.

commit 72b0763c3b13b6498f5d4287ee4fd6c13d513a55
Author: Niels Thykier <niels at thykier.net>
Date:   Sun Oct 22 08:20:13 2017 +0000

    dh_testroot: Document behaviour under R³
    
    Signed-off-by: Niels Thykier <niels at thykier.net>
---
 debian/changelog |  1 +
 dh_testroot      | 32 ++++++++++++++++++++++++++++----
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 9bfd71b..27893a7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,7 @@ debhelper (10.11) UNRELEASED; urgency=medium
   * dh: Clarify that --list can be run anywhere.
   * dh_testroot: Temporarily cope with being run outside a source
     root.  (Closes: #879478)
+  * dh_testroot: Update manpage to mention its new scope.
 
  -- Niels Thykier <niels at thykier.net>  Sun, 22 Oct 2017 08:04:11 +0000
 
diff --git a/dh_testroot b/dh_testroot
index 02b72dd..e486a54 100755
--- a/dh_testroot
+++ b/dh_testroot
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-dh_testroot - ensure that a package is built as root
+dh_testroot - ensure that a package is built with necessary level of root permissions
 
 =head1 SYNOPSIS
 
@@ -10,9 +10,33 @@ B<dh_testroot> [S<I<debhelper options>>]
 
 =head1 DESCRIPTION
 
-B<dh_testroot> simply checks to see if you are root. If not, it exits with an
-error. Debian packages must be built as root, though you can use 
-L<fakeroot(1)>
+B<dh_testroot> is used to determine if the package has access to at
+least the level of root access that it declared it needed via the
+Rules-Requires-Root (R³) field.
+
+The following is how B<dh_testroot> behaves based on the effective
+value of the R³ field:
+
+=over 4
+
+=item "binary-targets"
+
+B<dh_testroot> asserts that it is run as root or under L<fakeroot(1)>.
+
+=item "no"
+
+B<dh_testroot> returns successfully.
+
+=item Any other value than the above
+
+B<dh_testroot> asserts that it is either run as root (or under
+L<fakeroot(1)>) or the builder has provided the B<DPKG_GAIN_ROOT_CMD>
+environment variable (e.g. via dpkg-buildpackage -r).
+
+=back
+
+For backwards compatibility, B<dh_testroot> will consider the absence
+of the R³ field as if the R³ field was set to "binary-targets".
 
 =cut
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git