[dpkg] 23/28: spec/R³: Rename DPKG_GAIN_ROOT_CMD to DEB_GAIN_ROOT_CMD

[Mattia Rizzolo]

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

mattia pushed a commit to branch master
in repository dpkg.

commit 28fee8b445cd94bf7efd76f6c3fd0c62bdf94b6d
Author: Guillem Jover <guillem at debian.org>
Date:   Wed Jan 3 01:54:51 2018 +0100

    spec/R³: Rename DPKG_GAIN_ROOT_CMD to DEB_GAIN_ROOT_CMD
    
    This variable should not be dpkg specific, as it is supposed to be set
    by any builder driving the package build, and not just dpkg itself.
    
    Introduce ephemereal backwards compatibility by mapping the old name to
    the new one, even thught there are no known users.
---
 debian/changelog             |  4 ++++
 doc/rootless-builds.txt      | 14 +++++++++-----
 man/dpkg-buildpackage.man    |  2 +-
 scripts/dpkg-buildpackage.pl |  4 +++-
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 7883dac..bd41680 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -22,6 +22,10 @@ dpkg (1.19.1) UNRELEASED; urgency=medium
     dpkg-gencontrol and dpkg-genchanges. Regression introduced in dpkg 1.18.5.
   * Fix dpkg-gensymbols to print "error" instead of "warning" when these
     are fatal. Closes: #881488
+  * Rename DPKG_GAIN_ROOT_CMD to DEB_GAIN_ROOT_CMD in the R³ support, as
+    the variable is expected to be set by any builder, not just dpkg. And
+    introduce ephemereal backwards compatibility even though there are no
+    known users.
   * Architecture support:
     - Add support for riscv64 CPU. Closes: #822914
       Thanks to Manuel A. Fernandez Montecelo <mafm at debian.org>
diff --git a/doc/rootless-builds.txt b/doc/rootless-builds.txt
index 98e3877..29b034a 100644
--- a/doc/rootless-builds.txt
+++ b/doc/rootless-builds.txt
@@ -93,21 +93,25 @@ Gain Root API
 -------------
 
 The builder will provide a command to promote a given command to (fake)root
-by exposing it in the environment variable "DPKG_GAIN_ROOT_CMD". Tools that
+by exposing it in the environment variable "DEB_GAIN_ROOT_CMD". Tools that
 need this promotion will then use it like the following:
 
-    $DPKG_GAIN_ROOT_CMD cmd-that-needs-root ...
+    $DEB_GAIN_ROOT_CMD cmd-that-needs-root ...
 
 This command is subject to the same requirements as the "gain-root-command"
 that dpkg-buildpackage accepts via its "-r/--root-command" option, which
 means that it can contain space-separated parameters. If dpkg-buildpackage is
 called with "-r/--root-command", then dpkg-buildpackage shall use that value
-as the value for DPKG_GAIN_ROOT_CMD.
+as the value for "DEB_GAIN_ROOT_CMD".
 
 The variable SHOULD only be provided when there is a need for it. Notably
 when "Rules-Requires-Root" is either "no" or "binary-targets" the variable
 SHOULD NOT be defined.
 
+(The "DEB_GAIN_ROOT_CMD" variable used to be named "DPKG_GAIN_ROOT_CMD"
+starting with dpkg 1.19.0 and before dpkg 1.19.1 when this specification
+got released as stable. The old name MUST not be used.)
+
 Common cases
 ------------
 
@@ -128,7 +132,7 @@ dpkg-deb --build must either default to resetting all owner/group values to
 0:0 when not run under (fake)root OR provide an interface so dh_builddeb can
 provide the owner/group value to dpkg-deb --build.
 
-dpkg-buildpackage must export DPKG_GAIN_ROOT_CMD (for starters, doing this
+dpkg-buildpackage must export DEB_GAIN_ROOT_CMD (for starters, doing this
 unconditionally would be fine).
 
 
@@ -143,7 +147,7 @@ When the field is present:
  * dh_testroot will be a no-op when Rules-Requires-Root is set to "no".
 
  * Otherwise, dh_testroot will either verify that it is run under (fake)root
-   (as usual) OR assert that DPKG_GAIN_ROOT_CMD is defined.
+   (as usual) OR assert that DEB_GAIN_ROOT_CMD is defined.
 
  * debhelper build systems will be patched to check for the
    "debhelper/upstream-make-install" keyword and use the "Gain Root API"
diff --git a/man/dpkg-buildpackage.man b/man/dpkg-buildpackage.man
index 12c121c..165e63f 100644
--- a/man/dpkg-buildpackage.man
+++ b/man/dpkg-buildpackage.man
@@ -519,7 +519,7 @@ 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 DPKG_GAIN_ROOT_CMD
+.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
 \fBbinary-targets\fP.
diff --git a/scripts/dpkg-buildpackage.pl b/scripts/dpkg-buildpackage.pl
index 3a9ba5b..4b3e2b9 100755
--- a/scripts/dpkg-buildpackage.pl
+++ b/scripts/dpkg-buildpackage.pl
@@ -720,7 +720,9 @@ sub parse_rules_requires_root {
               'Rules-Requires-Root');
     } elsif ($keywords_impl) {
         # Set only on <implementations-keywords>.
-        $ENV{DPKG_GAIN_ROOT_CMD} = join ' ', @rootcommand;
+        $ENV{DEB_GAIN_ROOT_CMD} = join ' ', @rootcommand;
+        # XXX: For ephemeral backwards compatibility.
+        $ENV{DPKG_GAIN_ROOT_CMD} = $ENV{DEB_GAIN_ROOT_CMD};
     }
 
     return %rrr;

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