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



Attachment: signature.asc
Description: OpenPGP digital signature

Reply via email to