Hi!
On Mon, 2017-11-13 at 01:28:08 +0100, Guillem Jover wrote:
> On Sat, 2017-10-28 at 15:59:00 +0000, Niels Thykier wrote:
> > * Deadline for feedback: 2 weeks from today (but we are happy to extend
> > it if people find this too short).
> > - if there are no major concerns with this proposal at that time
> > we will consider the specification as stable, and mark it as so.
>
> I've queued now a commit for dpkg marking the spec as stable. So, for
> all practical effects, feel free to consider it as such from now on.
> But if there were still serious concerns, please bring them up before
> dpkg 1.19.1 hits unstable in a couple of weeks at most, when we'll
> consider it really really stable. ;)
Ok, there were some comments provided, and some important omissions
were spotted. I'm attaching the diff for those changes, which mark
now the spec as a stable recommendation with 1.19.0.5.
Thanks,
Guillem
diff --git a/doc/rootless-builds.txt b/doc/rootless-builds.txt
index 98e387709..0157879a4 100644
--- a/doc/rootless-builds.txt
+++ b/doc/rootless-builds.txt
@@ -1,7 +1,8 @@
Supporting rootless builds
==========================
-Status: draft, experimental
+Status: recommendation, stable
+Version: 1.0
Background
----------
@@ -52,6 +53,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
@@ -93,21 +103,26 @@ 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 command SHOULD preserve all the
+environment variables, unmodified.
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 +143,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 +158,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"
