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. <ballo...@debian.org> Imagine a large red swirl here.
