Hello Paul,
On Thu, Jun 14 2018, Paul Gevers wrote:
>> + - A space separated list of keywords described below. These must
>> + always contain a forward slash, which sets them apart from the
>> + other values. When this list is provided, the builder must provide
>
> ^^^^^^ plural here, makes sense.
>
>> + 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
>> +want 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
>
> ^^^^^ singular here. I find this ambiguous. I think you mean
> to treat the list of values above as one variable by calling it singular
> here, a suggested by the remark about space below.
The latter use of 'value' refers to the value of a field, but a field
cannot have more than one value, so it has to be singular.
I'm sorry, but I do not see how it could be ambiguous. Maybe you could
state the multiple senses between which you find it to be ambiguous.
>> + 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 (partiularly 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.
>
> Apparently some details in the implementation are unclear to me, as I
> don't get this statement if the example at the end includes a sudo
> example. Isn't that a true root or is that not what you mean? Is only
> $(su root) a real root (and why wouldn't that work)?
Using R-R-R, a package can declare "I need a command that will give me
root", but under this specification, either fakeroot or real root is
considered an acceptable answer to that declaration.
An alternative would be `Rules-Requires-Real-Root: yes` which would
allow a package to declare "I need a command giving me actual root on
the system building the package, not just fakeroot". Then fakeroot
would not be an acceptable answer. But that is not the spec.
In short, the spec does not distinguish between real root and fakeroot,
such that a package could request the former over the latter.
>> +
>> +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
>
> ^^^ a?
> ^^^^^^^^^^^^^^^^^ should this be linked to the
> *section describing it? It drops out of thin air here.
There is already a cross reference just above, near "A space separated
list of keywords described below." Adding another cross reference seems
like it would make things a bit cluttered? I don't mind adding it if
you are sure it's needed.
>> +(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..214d716 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 be invoked as root depending on the
>> + value of the :ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>`
>> + field. [#]_
>
> I have difficulty parsing this sentence. I think I know what is meant.
> The ``binary`` may always be invoked as root, but depending on the value
> of R³, it may also not.
I read it in the same way as you do, but I agree that it is not a good
sentence.
How about:
The ``binary`` targets may need to be invoked as root depending on
the value of the 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
>
> ^^^^^^ lintian will tell you this should be "enables"
As a native speaker I find 'allows' more natural than 'enables'.
'Allows' is certainly not grammatically incorrect. Can you point me to
the Lintian tag?
>> +(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 need
>> +not be used via a shell.
>
> I am not a native speaker, but isn't "doesn't need to" more natural?
> Otherwise it should be "needs" I guess.
s/need/needs/ would not be grammatically correct.
I am a native speaker and I find the "need not" more idiomatic than
"doesn't need to", but I have to admit that I do not know why :)
Here is a possible explanation, but please do not rely on this in the
future unless some other native speakers are able to confirm it:
"The gain root command ... because it need not be used via a shell"
<-- it /can/ be used without a shell and /might/ be used without a shell,
/therefore/ it should not rely on shell features.
"The gain root command ... because it doesn't need to be used via a
shell" <-- it /can/ be used without a shell,
/therefore/ it should not rely on shell features.
i.e. the 'need not' carries the additional connotation that it might
/actually/ be used without a shell, which is the reason for not relying
on shell features.
>> +
>> +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
> `gain root command`s ?
Unfortunately that change breaks Sphinx, causing it to print literal
backticks.
--
Sean Whitton
