Bug#930666: Please document consensus on use of dh sequencer
Sam Hartman <hartmans@debian.org> writes:
> I just published a consensus call on a discussion we had to canvas the
> project on the use of Debhelper's dh sequencer.
> https://lists.debian.org/msgid-search/tslmuif7pwy.fsf@suchdamage.org
> I'd like to ask the policy editors to facilitate using the normal
> process to document this consensus in policy.
> My understanding is that the editors already have some ideas about how
> that might work.
To kick off this discussion with some concrete wording that we can
discuss, here's a possible approach to documenting this consensus. This
attempts to reflect the nuance of the consensus, including the
understanding that dh is not mandatory and there are various cases where
it is not the best choice.
For those reading this, note that "recommended" is a documented keyword in
Policy, equivalent to "should." However, it is intentionally weakened
here with the "in the absence of a reason to use a different approach"
language. The goal here (and please judge whether I achieved it) is to
concentrate on providing default advice to people with no preference,
particularly people new to packaging, not to argue with maintainers who
are familiar with the tradeoffs and are intentionally making a different
choice.
diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index ee9270d..9ea2f5c 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -259,18 +259,49 @@ files, sockets or setuid or setgid files.. [#]_
Main building script: ``debian/rules``
--------------------------------------
-This file must be an executable makefile, and contains the
-package-specific recipes for compiling the package and building binary
-package(s) from the source.
-
-It must start with the line ``#!/usr/bin/make -f``, so that it can be
-invoked by saying its name rather than invoking ``make`` explicitly.
-That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior.
+This file must be an executable makefile. It contains the
+package-specific recipes for compiling the source (if required) and
+constructing one or more binary packages.
+
+``debian/rules`` must start with the line ``#!/usr/bin/make -f`` so that
+it can be executed by running ``./debian/rules`` from the top of the
+source package. Invoking either of ``make -f debian/rules <arg> ...`` or
+``./debian/rules <arg> ...`` must result in identical behavior.
+
+In the absence of a reason to use a different approach, the recommended
+way to implement the build process of a Debian package, including the
+contents of the ``debian/rules`` building script, is the ``dh`` tool,
+which is provided by the debhelper package. This is the most common
+packaging helper tool in Debian. Using it will save effort in complying
+with the rules in this document, since it will automatically implement
+many of them without requiring explicit instructions.
+
+There are various situations in which ``dh`` is not the best choice. For
+example, the standard tools for packaging software written in some
+languages may use another tool, some rarer packaging patterns (such as
+multiple builds of the same software with different options) are easier to
+express with other tools, or the packager may be working on a new
+packaging helper and may therefore want to use that tool. Using ``dh`` is
+therefore not required. But it is a wise default choice in most
+situations.
+
+If the package uses ``dh``, the default content of ``debian/rules`` will
+be::
+
+ #!/usr/bin/make -f
+ %:
+ dh $@
+
+(the start of the ``dh`` line must be a literal tab), and any special
+rules for this package will be expressed as overrides. ``dh`` will then
+take care most of the requirements below (and many others). See the
+documentation in the debhelper package for more information.
The following targets are required and must be implemented by
``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
-``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. These
-are the targets called by ``dpkg-buildpackage``.
+``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. (When
+using ``dh``, these are implemented using the wildcard pattern shown
+above.) These are the targets called by ``dpkg-buildpackage``.
Since an interactive ``debian/rules`` script makes it impossible to
auto-compile that package and also makes it hard for other people to
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: