Bug#930666: Please document consensus on use of dh sequencer
On Sat, Jul 06, 2019 at 08:58:26PM -0700, Russ Allbery wrote:
> Here is an updated patch incorporating Sean's wording changes as well as
> other changes discussed elsewhere on the thread. This reverts most of my
> unrelated informative changes for clarity (they can be discussed or made
> separately) and drops the sample dh makefile in favor of just referencing
> the debhelper documentation. It does keep some minor wording and
> formatting fixes in the first two paragraphs.
>
> This also removes the word "new" from the discussion of using another
> packaging helper as an example, to make it a bit more obvious that the
> cdbs maintainer using cdbs is one of the expected exceptions.
>
> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index ee9270d..93beb4a 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -259,13 +259,33 @@ 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 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.
> +
> +The recommended way to implement the build process of a Debian package, in
> +the absence of a good reason to use a different approach, is the ``dh``
> +tool. This includes the contents of the ``debian/rules`` building script.
> +``dh`` is the most common packaging helper tool in Debian. Using it will
> +usually save effort in complying with the rules in this document, because
> +``dh`` will automatically implement many of them without requiring
> +explicit instructions.
> +
> +There are sometimes good reasons to use a different approach. 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; and a packager working on a different packaging
> +helper might want to use their tool. The recommendation to use ``dh``
> +does not always apply, and use of ``dh`` is not required.
> +
> +For more information about how to use ``dh``, see the documentation in the
> +debhelper package, most notably the dh(1) manual page.
>
> The following targets are required and must be implemented by
> ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
>
Thanks Russ, this is much nicer this way.
Cheers,
--
Bill. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: