diff options
Diffstat (limited to 'doc/rootless-builds.txt')
| -rw-r--r-- | doc/rootless-builds.txt | 44 |
1 files changed, 30 insertions, 14 deletions
diff --git a/doc/rootless-builds.txt b/doc/rootless-builds.txt index 98e387709..3298768ec 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 ---------- @@ -47,10 +48,20 @@ The values are defined as: (See also "Implementation provided keywords".) - When "Rules-Requires-Root" is set to <implementations-keywords>, the - builder will expose an interface that is used to run a command under - (fake)root via the "Gain Root API". If the builder cannot provide such - a command, it MUST behave like "Rules-Requires-Root" was set to - "binary-targets", i.e. run "debian/rules binary" under (fake)root. + builder (i.e. whatever is executing debian/rules) will expose an + interface that is used to run a command under (fake)root via the + "Gain Root API". If the builder cannot provide such 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 chosen 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 @@ -93,21 +104,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 ------------ @@ -124,12 +140,12 @@ Prototyping/preparation dpkg side --------- -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-deb --build provides the --root-owner-group option so that dh_builddeb +or direct calls can control the owner/group file values w/o requiring +(fake)root. -dpkg-buildpackage must export DPKG_GAIN_ROOT_CMD (for starters, doing this -unconditionally would be fine). +dpkg-buildpackage must export DEB_GAIN_ROOT_CMD when necessary (for +prototyping, doing this unconditionally would be fine). debhelper side @@ -143,7 +159,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" |