5.6.31. Rules-Requires-Root

Simple field that defines if the source package requires access to root (or fakeroot) during selected targets in the Main building script: debian/rules.

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 debian/rules and Rules-Requires-Root) 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.

5.6.31.1. 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.

5.6.31.2. 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.

5.6.31.3. 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 Main building script: debian/rules) 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.