r10762 - /website/quilt.pod

[dmn at users.alioth.debian.org]

Author: dmn
Date: Mon Dec  3 17:45:34 2007
New Revision: 10762

URL: http://svn.debian.org/wsvn/?sc=1&rev=10762
Log:
Tidy-up. Remove redundant QUILT_PATCHES explaination. Better debian/rules example that does not fail parallel builds

Modified:
    website/quilt.pod

Modified: website/quilt.pod
URL: http://svn.debian.org/wsvn/website/quilt.pod?rev=10762&op=diff
==============================================================================
--- website/quilt.pod (original)
+++ website/quilt.pod Mon Dec  3 17:45:34 2007
@@ -23,7 +23,7 @@
 Unfortunatelly, that directory is C<./patches/> by default. For Debian packages
 C<./debian/patches/> is far more comfortable. To flawlessly fix this, add
 C<export QUILT_PATCHES=debian/patches> in your shell resource file and reload
-it. This way you won't have to worry about this quilt oddity (as me; ever
+it. This way you won't have to worry about this quilt oddity (like me; ever
 forgot to mention it in the first revision of this document).
 
 =head2 1.1. Patches order -- the series
@@ -35,15 +35,7 @@
 list of all patches to be applied. C<quilt> applies patches in the order they
 are listed in that file.
 
-=head2 1.2. debian/patches
-
-In Debian packages, it is usual to have the patches in C<debian/patches>.
-C<quilt>'s default patches directory, however, is C<./patches>. To make it
-follow Debian, one needs to do C<export QUILT_PATCHES=debian/patches>. Note
-that the C<quilt.make> snippet makes this so you don't need to set this
-explicitly in C<debian/rules>.
-
-=head2 1.3. quilt philosophy
+=head2 1.2. quilt philosophy
 
 C<quilt> works in the source tree. There's no copying large trees around.
 There's also no need to always keep the source tree clean of unapplied changes
@@ -113,20 +105,35 @@
 
 =head1 3. Integrating within package build process
 
-C<include /usr/share/quilt/quilt.make> gives debian/rules two useful targets:
-I<patch> and I<unpatch>.
+C<include /usr/share/quilt/quilt.make> has some candy for C<debian/rules>.
+First, it defines C<QUILT_PATCHES> to be C<debian/patches> so that one doesn't
+have to worry about that setting in the pbuilder chroot.o
 
-Integrate them within debian/rules as you see fit. Example:
+Second, it defines C<QUILT_STAMPFN>, which can be used as a C<build-stamp> or
+C<configure-stamp> dependency.
+
+Lastly, C<unpatch> target is useful as a C<clean> dependency.
+
+Here's sample fragment from C<debian/rules>:
 
     include /usr/share/quilt/quilt.make
 
-    build: patch build-stamp
-    build-stamp
+    build: build-stamp
+    build-stamp: $(QUILT_STAMPFN)
         dh_testdir
         ...
     clean: unpatch
         dh_clean build-stamp
         ...
+
+Note that using the following:
+
+    build: patch build-stamp
+    build-stamp:
+        ...
+
+can fail if parallel build is allowed via C<-jN>. C<patch> and C<build-stamp>
+would be run in parallel, possibly failing due to partly applied patches.
 
 =head1 4. Why quilt is better?