Bug#88111: policy should not dictate implementation details
Previously Julian Gilbey wrote:
> Right. Give a policy diff which specifies *exactly* what interfaces
> are required of debian/rules.
I'll make some other changes as well. I notice the current policy
documented is poluted with things like scripting advise, which
should be in a seperate document.
Patch is attached.
Wichert.
--
_________________________________________________________________
/ Nothing is fool-proof to a sufficiently talented fool \
| wichert@cistron.nl http://www.liacs.nl/~wichert/ |
| 1024D/2FA3BC2D 576E 100B 518D 2F16 36B0 2805 3CB8 9250 2FA3 BC2D |
--- policy.sgml.org Thu Mar 1 17:30:54 2001
+++ policy.sgml Thu Mar 1 17:43:03 2001
@@ -1230,50 +1230,6 @@
GNU GPL, just as the rest of <prgn>dpkg</prgn>
is.)</p></sect1>
-
- <sect1>
- <heading>Error trapping in makefiles</heading>
-
- <p>
- When <prgn>make</prgn> invokes a command in a makefile
- (including your package's upstream makefiles and the
- <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
- means that <tt>sh</tt>'s usual bad error handling
- properties apply: if you include a miniature script as one
- of the commands in your makefile you'll find that if you
- don't do anything about it then errors are not detected
- and <prgn>make</prgn> will blithely continue after
- problems.</p>
-
- <p>
- Every time you put more than one shell command (this
- includes using a loop) in a makefile command you
- must make sure that errors are trapped. For
- simple compound commands, such as changing directory and
- then running a program, using <tt>&&</tt> rather
- than semicolon as a command separator is sufficient. For
- more complex commands including most loops and
- conditionals you should include a separate <tt>set -e</tt>
- command at the start of every makefile command that's
- actually one of these miniature shell scripts.</p></sect1>
-
-
- <sect1>
- <heading>Obsolete constructs and libraries</heading>
-
- <p>
- The include file <prgn><varargs.h></prgn> is
- provided to support end-users compiling very old software;
- the library <tt>libtermcap</tt> is provided to support the
- execution of software which has been linked against it
- (either old programs or those such as Netscape which are
- only available in binary form).</p>
-
- <p>
- Debian packages should be ported to include
- <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
- they are built.</p>
- </sect1>
</sect>
</chapt>
@@ -1734,15 +1690,16 @@
main building script </heading>
<p>
- This file must be an executable makefile, and contains the
+ This file must be an executable, and contains the
package-specific recipes for compiling the package and
building binary package(s) out of the source.
</p>
<p>
- It must start with the line <tt>#!/usr/bin/make -f</tt>,
- so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
+ The <tt>debian/rules</tt> takes a single argument, which is
+ the target we want to build. Success should be indicated
+ using the exitcode: an exitcode of 0 indicates success,
+ any other code indicates a failure.
</p>
<p>
@@ -1773,39 +1730,10 @@
</p>
<p>
- For some packages, notably ones where the same
- source tree is compiled in different ways to produce
- two binary packages, the <prgn>build</prgn> target
- does not make much sense. For these packages it is
- good enough to provide two (or more) targets
- (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
- for each of the ways of building the package, and a
- <prgn>build</prgn> target that does nothing. The
- <prgn>binary</prgn> target will have to build the
- package in each of the possible ways and make the
- binary package out of each.
- </p>
-
- <p>
The <prgn>build</prgn> target must not do anything
that might require root privilege.
</p>
- <p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
- </p>
-
- <p>
- When a package has a configuration routine that
- takes a long time, or when the makefiles are poorly
- designed, or when <prgn>build</prgn> needs to run
- <prgn>clean</prgn> first, it is a good idea to
- <tt>touch build</tt> when the build process is
- complete. This will ensure that if <tt>debian/rules
- build</tt> is run again it will not rebuild the
- whole program.
- </p>
</item>
<tag><tt>binary</tt>, <tt>binary-arch</tt>,
@@ -1887,10 +1815,14 @@
example).
</p>
</item>
+ </taglist>
+ </p>
- <tag><tt>get-orig-source</tt> (optional)</tag>
+ <p>
+ The optional target are:
+ <taglist>
+ <tag><tt>get-orig-source</tt></tag>
<item>
-
<p>
This target fetches the most recent version of the
original source package from a canonical archive site
@@ -1905,21 +1837,15 @@
should take care to clean up any temporary files it
may have left.
</p>
-
- <p>
- This target is optional, but providing it if
- possible is a good idea.
- </p>
</item>
</taglist>
+ </p>
<p>
- The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with a current
+ <tt>debian/rules</tt> must be invoked with a current
directory of the package's top-level directory.
</p>
-
<p>
Additional targets may exist in <tt>debian/rules</tt>,
either as published or undocumented interfaces or for the
@@ -2053,8 +1979,8 @@
The <var>date</var> should be in RFC822 format
<footnote>
<p>
- This is generated by the <prgn>822-date</prgn>
- program.
+ This can generated by the <prgn>822-date</prgn>
+ program, or by using the -R option for date.
</p>
</footnote>; it should include the time zone specified
numerically, with the time zone name or abbreviation
Reply to: