Sean Whitton: > [...] Hi,
Thanks for the updated version. :)
My second also applies to the re-worded variant quoted below
> Here is the complete new diff for seconding. Below that, I've included
> the interdiff between the patch Niels seconded and the new one.
>
>> 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 <ni...@thykier.net>
>> + Wording: Guillem Jover <guil...@debian.org>
>> + Wording: Sean Whitton <spwhit...@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
>> -------------
>
> [...]
Thanks,
~Niels
signature.asc
Description: OpenPGP digital signature
