spec/R³: Add new DEB_RULES_REQUIRES_ROOT variable

This variable is set by the builder to notify debian/rules that it
supports this specification.

Wordsmithing-by: Niels Thykier <niels@thykier.net>

4 files changed, 20 insertions, 0 deletions

diff --git a/debian/changelog b/debian/changelog
index 4b630810a..0a1789908 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -30,6 +30,7 @@ dpkg (1.19.1) UNRELEASED; urgency=medium
     <implementations-keywords>, following the specification.
   * Specify that DEB_GAIN_ROOT_CMD in R³ should preserve the environment.
     Proposed by Josh Triplett <josh@joshtriplett.org>.
+  * Specify new DEB_RULES_REQUIRES_ROOT variable for R³ support.
   * Architecture support:
     - Add support for riscv64 CPU. Closes: #822914
       Thanks to Manuel A. Fernandez Montecelo <mafm@debian.org>
diff --git a/doc/rootless-builds.txt b/doc/rootless-builds.txt
index 68617d5b4..a17a5ad17 100644
--- a/doc/rootless-builds.txt
+++ b/doc/rootless-builds.txt
@@ -52,6 +52,15 @@ The values are defined as:
      a command, it MUST behave like "Rules-Requires-Root" was set to
      "binary-targets", i.e. run "debian/rules binary" under (fake)root.
 
+When the builder supports this specification, it MUST notify this fact to
+the rules file via the "DEB_RULES_REQUIRES_ROOT" environment variable, with
+the value it has obtained from the Rules-Requires-Root field or some builder
+specific override mechanism, which will denote the level of support the
+builder has choosen to commit to take effect during the build. When set,
+it MUST be a valid value for the Rules-Requires-Root field. If unset,
+the build system SHOULD assume that the builder does not recognize the
+Rules-Requires-Root field at all.
+
 It is always permissible for a builder to ignore this field and fall back to
 running the binary targets under (fake)root. This is to ensure backwards
 compatibility when builds are performed by legacy builders or older versions
diff --git a/man/dpkg-buildpackage.man b/man/dpkg-buildpackage.man
index 165e63ff2..76545ebb8 100644
--- a/man/dpkg-buildpackage.man
+++ b/man/dpkg-buildpackage.man
@@ -519,6 +519,13 @@ standalone should be supported.
 parameters forwarded. Any variable that is output by its \fB\-s\fP
 option is integrated in the build environment.
 .TP
+.B DEB_RULES_REQUIRES_ROOT
+This variable is set to the value obtained from the \fBRules\-Requires\-Root\fP
+field or from the command-line.
+When set, it will be a valid value for the \fBRules\-Requires\-Root\fP field.
+It is used to notify \fBdebian/rules\fP whether the \fBrootless\-builds.txt\fP
+specification is supported.
+.TP
 .B DEB_GAIN_ROOT_CMD
 This variable is set to \fIgain-root-command\fP when the field
 \fBRules\-Requires\-Root\fP is set to a value different to \fBno\fP and
diff --git a/scripts/dpkg-buildpackage.pl b/scripts/dpkg-buildpackage.pl
index d790b3177..bd0a6f6a6 100755
--- a/scripts/dpkg-buildpackage.pl
+++ b/scripts/dpkg-buildpackage.pl
@@ -715,6 +715,9 @@ sub parse_rules_requires_root {
         setup_rootcommand();
     }
 
+    # Notify the childs we do support R³.
+    $ENV{DEB_RULES_REQUIRES_ROOT} = join ' ', sort keys %rrr;
+
     if ($keywords_base > 1 or $keywords_base and $keywords_impl) {
         error(g_('%s field contains both global and implementation specific keywords'),
               'Rules-Requires-Root');