Bug#880920: Document Rules-Requires-Root field
On Fri, 15 Jun 2018 at 18:02:39 +0100, Sean Whitton wrote:
> Here is the complete new diff for seconding
Seconded (as below).
smcv
> > diff --git a/debian/changelog b/debian/changelog
> > index 2dea331..b89816e 100644
> > --- a/debian/changelog
> > +++ b/debian/changelog
> > @@ -1,5 +1,11 @@
> > -debian-policy (4.1.4.2) UNRELEASED; urgency=medium
> > +debian-policy (4.1.5.0) UNRELEASED; urgency=medium
> >
> > + * Policy: Document Rules-Requires-Root
> > + Wording: Niels Thykier <niels@thykier.net>
> > + Wording: Guillem Jover <guillem@debian.org>
> > + Wording: Sean Whitton <spwhitton@spwhitton.name>
> > + Seconded: ...
> > + Closes: #880920
> > * Fix URL to the alioth lists service in footnote (Closes: #896749).
> > Thanks Martin Zobel-Helas for the report.
> >
> > diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> > index 0771346..3afba4c 100644
> > --- a/policy/ch-controlfields.rst
> > +++ b/policy/ch-controlfields.rst
> > @@ -129,6 +129,8 @@ package) are:
> >
> > - :ref:`Testsuite <s-f-Testsuite>`
> >
> > +- :ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>`
> > +
> > The fields in the binary package paragraphs are:
> >
> > - :ref:`Package <s-f-Package>` (mandatory)
> > @@ -1020,6 +1022,118 @@ This field is automatically added to Debian source control files
> > field may also be used in source package control files
> > (``debian/control``) if needed in other situations.
> >
> > +.. _s-f-Rules-Requires-Root:
> > +
> > +``Rules-Requires-Root``
> > +~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Simple field that defines if the source package requires access to
> > +root (or fakeroot) during selected targets in the :ref:`Main building
> > +script: debian/rules <s-debianrules>`.
> > +
> > +The field can consist of exactly one of the following three items:
> > +
> > + - ``no``: Declares that neither root nor fakeroot is required.
> > + Package builders (e.g. dpkg-buildpackage) may choose to invoke any
> > + target in ``debian/rules`` with an unprivileged user.
> > +
> > + - ``binary-targets`` (default): Declares that the package will need
> > + the root (or fakeroot) when either of the ``binary``,
> > + ``binary-arch`` or ``binary-indep`` targets are called. This is
> > + how every tool behaved before this field was defined.
> > +
> > + - A space separated list of keywords described below. These keywords
> > + must always contain a forward slash, which sets them apart from the
> > + other possible values of ``Rules-Requires-Root``. When this list
> > + is provided, the builder must provide a `gain root command` (as
> > + defined in :ref:`debian/rules and Rules-Requires-Root
> > + <s-debianrules-gainrootapi>`) *or* pretend that the value was set
> > + to ``binary-targets``, and both the builder and the package's
> > + ``debian/rules`` script must downgrade accordingly (see below).
> > +
> > +If the package builder supports the ``Rules-Requires-Root`` field and
> > +wants to enable the feature, then it must set the environment variable
> > +``DEB_RULES_REQUIRES_ROOT`` when invoking the package building script
> > +``debian/rules``. The value of ``DEB_RULES_REQUIRES_ROOT`` should be
> > +one of:
> > +
> > + * The value of ``Rules-Requires-Root`` if the builder can support
> > + that value. The builder may trim unnecessary whitespace used to
> > + format the field for readability.
> > +
> > + * The value ``binary-targets`` if it cannot support the value of
> > + ``Rules-Requires-Root``.
> > +
> > +A compliant builder may also leave ``DEB_RULES_REQUIRES_ROOT`` unset
> > +or set it to ``binary-targets`` if it has been requested to test
> > +whether the package it builds correctly implements the fall-back for
> > +legacy builders.
> > +
> > +Remarks
> > +^^^^^^^
> > +
> > +All packages and builders must support ``binary-targets`` as this was
> > +the historical behaviour prior to the introduction of this field.
> > +
> > +Any tool (particularly older versions of them) may be unaware of this
> > +field and behave like the field was set to ``binary-targets``. The
> > +package build must gracefully cope with this and produce a
> > +semantically equivalent result.
> > +
> > +This field intentionally does not enable a package to request a true
> > +root over fakeroot.
> > +
> > +Definition of the keywords
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +The keywords have the format ``<namespace>/<case>``, where:
> > +
> > + * ``<namespace>`` must consist entirely of printable ASCII characters
> > + except for any whitespace and the forward slash (``/``). It must
> > + consist of at least 2 characters.
> > +
> > + * ``/`` (between ``<namespace>`` and ``<case>``) is a single ASCII
> > + forward slash.
> > +
> > + * ``<case>`` must consist entirely of printable ASCII characters
> > + except for any whitespace. It must consist of at least 2
> > + characters.
> > +
> > +These keywords define where the package build script ``debian/rules``,
> > +or the tools called by that script, will need access to root or
> > +fakeroot.
> > +
> > +In addition to the keywords defined in the next section, each tool or
> > +package may define keywords within a namespace named after that tool
> > +or package. The package or tool is considered to own that namespace.
> > +
> > +A tool may use the `gain root command` to do something under
> > +(fake)root if and only if the tool defines an appropriate keyword in
> > +its namespace, and the package lists that keyword in
> > +``Rules-Requires-Root``.
> > +
> > +All tools must ignore keywords under namespaces they do not know or
> > +own. A tool may emit a warning, or abort with an error, if it finds
> > +unknown keywords in namespaces it owns, but it is not required to do
> > +this for all keywords in the namespace.
> > +
> > +Provided keywords
> > +^^^^^^^^^^^^^^^^^
> > +
> > +The following keywords are defined:
> > +
> > + * ``dpkg/target-subcommand``: declares that there exists a command
> > + that the ``debian/rules`` file must run under (fake)root
> > +
> > + * ``dpkg/target/foo``: declares that the additional, package-specific
> > + target ``foo`` (that is, not one of the targets specified in
> > + :ref:`Main building script: debian/rules <s-debianrules>`) must be
> > + run under (fake)root
> > +
> > +This list is intentionally incomplete. You should consult the
> > +documentation of the tool or package in question for which keywords it
> > +defines and when they are needed.
> > +
> > .. _s5.7:
> >
> > User-defined fields
> > diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> > index e3b1981..418dc84 100644
> > --- a/policy/ch-source.rst
> > +++ b/policy/ch-source.rst
> > @@ -346,7 +346,9 @@ The targets are as follows:
> > architecture-dependent or not), it must still exist and must always
> > succeed.
> >
> > - The ``binary`` targets must be invoked as root. [#]_
> > + The ``binary`` targets may need to be invoked as root depending on
> > + the value of the :ref:`Rules-Requires-Root
> > + <s-f-Rules-Requires-Root>` field. [#]_
> >
> > ``clean`` (required)
> > This must undo any effects that the ``build`` and ``binary``
> > @@ -435,6 +437,12 @@ should not be used to get the CPU or system information; the
> > that. GNU style variables should generally only be used with upstream
> > build systems.
> >
> > +The builder may set ``DEB_RULES_REQUIRES_ROOT`` environment variable
> > +when calling any of the mandatory targets as defined in
> > +:ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>`. If the variable
> > +is not set, the package must behave as if it was set to
> > +``binary-targets``.
> > +
> > .. _s-debianrules-options:
> >
> > ``debian/rules`` and ``DEB_BUILD_OPTIONS``
> > @@ -525,6 +533,53 @@ order to make it work for your package.
> > # Code to run the package test suite.
> > endif
> >
> > +
> > +.. _s-debianrules-gainrootapi:
> > +
> > +``debian/rules`` and ``Rules-Requires-Root``
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Depending on the value of the :ref:`Rules-Requires-Root
> > +<s-f-Rules-Requires-Root>` field, the package builder
> > +(e.g. dpkg-buildpackage) may run the ``debian/rules`` target as an
> > +unprivileged user and provide a `gain root command`. This command
> > +allows the ``debian/rules`` target to run particular subcommands under
> > +(fake)root.
> > +
> > +The `gain root command` is passed to the build script via the
> > +``DEB_GAIN_ROOT_CMD`` environment variable. The contents of this
> > +variable is a space separated list, the first entry of which is the
> > +command, and the proceeding entries of which are arguments to the
> > +command. The `gain root command` must be available via PATH. The
> > +`gain root command` must not rely on shell features because it will
> > +not necessarily be invoked via a shell.
> > +
> > +The `gain root command` must not run interactively, including
> > +prompting for any user input. It must be possible to prepend the
> > +`gain root command` to an existing command and its arguments, without
> > +needing to alter or quote the existing command and its arguments.
> > +Furthermore, the `gain root command` must preserve all environment
> > +variables without the caller having to explicitly request any
> > +preservation.
> > +
> > +The following are examples of valid gain root commands (in syntax of
> > +sh), assuming the tools used are available and properly configured::
> > +
> > + # Command "sudo", with arguments "-nE" and "--"
> > + export DEB_GAIN_ROOT_CMD='sudo -nE --'
> > + # Command "fakeroot" with the single argument "--"
> > + export DEB_GAIN_ROOT_CMD='fakeroot --'
> > +
> > +Examples of valid use of the `gain root command`::
> > +
> > + # sh-syntax (assumes set -e semantics for error handling)
> > + $DEB_GAIN_ROOT_CMD some-cmd --which-requires-root
> > +
> > + # perl
> > + my @cmd = ('some-cmd', '--which-requires-root');
> > + unshift(@cmd, split(' ', $ENV{DEB_GAIN_ROOT_CMD})) if $ENV{DEB_GAIN_ROOT_CMD};
> > + system(@cmd) == or die("@cmd failed");
> > +
> > .. _s-substvars:
> >
> > Variable substitutions: ``debian/substvars``
> > diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
> > index ec61f95..ad24eeb 100644
> > --- a/policy/upgrading-checklist.rst
> > +++ b/policy/upgrading-checklist.rst
> > @@ -39,6 +39,18 @@ The sections in this checklist match the values for the
> > except in the two anomalous historical cases where normative
> > requirements were changed in a minor patch release.
> >
> > +Version 4.1.5
> > +-------------
> > +
> > +Unreleased.
> > +
> > +4.9.2
> > + Document how ``debian/rules`` and the ``Rules-Requires-Root``
> > + field interact.
> > +
> > +5.6.31
> > + Document the ``Rules-Requires-Root`` field.
> > +
> > Version 4.1.4
> > -------------
Reply to: