r40965 - /website/howto/quilt.pod

Wed Jul 29 02:35:38 UTC 2009

Author: jawnsy-guest
Date: Wed Jul 29 02:35:16 2009
New Revision: 40965

URL: http://svn.debian.org/wsvn/?sc=1&rev=40965
Log:
Rewrite headers, add a section about how this all fits in to the new quilt 3.0 format :D

Modified:
    website/howto/quilt.pod

Modified: website/howto/quilt.pod
URL: http://svn.debian.org/wsvn/website/howto/quilt.pod?rev=40965&op=diff
==============================================================================

--- website/howto/quilt.pod (original)
+++ website/howto/quilt.pod Wed Jul 29 02:35:16 2009
@@ -1,8 +1,8 @@
 
-=head1 Quilt for Debian maintainers
-
-This guide briefly introduces usage of C<quilt> for managing patches to debian
-packages.
+=head1 Quilt for Debian Maintainers
+
+This guide briefly introduces usage of C<quilt> for managing patches to
+debian packages.
 
 It will describe how to create, modify, apply and unapply patches with
 C<quilt>.
@@ -10,14 +10,14 @@
 This is a work in progress.  Please send any comments or ideas to
 <dmn at debian.org>.
 
-=head1 1. The big picture
+=head1 The Big Picture
 
 C<quilt> helps managing a series of patches that a debian package maintainer
 needs applied to upstream source when building the package. It is similar to
 C<dpatch> and C<cdbs>'s simple-patchsys in that the patches are kept as a
 series of files in F<debian/patches>.
 
-=head2 1.0. Preparation
+=head2 Preparation
 
 C<quilt> uses a special directory for keeping patches (not very surprising).
 Unfortunatelly, that directory is F<./patches/> by default. For Debian packages
@@ -29,7 +29,7 @@
 You can also create F<.quiltrc> in your home directory and set
 C<QUILT_PATCHES> there if you prefer.
 
-=head2 1.1. Patches order -- the series
+=head2 Patch Order: the 'series'
 
 C<quilt> manages the series of patches as a stack. You push to it (apply a
 patch) and pop from it (unapply a patch).
@@ -38,7 +38,7 @@
 list of all patches to be applied. C<quilt> applies patches in the order they
 are listed in that file.
 
-=head2 1.2. quilt philosophy
+=head2 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
@@ -60,12 +60,12 @@
 At first this sounds complicated but it actually it is not. You just speak to
 your patch system so it knows what you're doing and handles the details.
 
-=head1 2. Working with C<quilt>
+=head2 Working With quilt
 
 Here are a few examples of working with C<quilt>. Note that most of the
 commands below have plenty of options so reading quilt man page is a good idea.
 
-=head2 2.1. Creating a patch
+=head2 Creating a Patch
 
 To create a patch, run C<quilt new $patch_name>. If you want C<.patch>
 extension, you need to give it.
@@ -91,13 +91,13 @@
 necessary to tell svn that you have added new files. You can do this with
 C<svn add debian/patches>.
 
-=head2 2.2. Applying and unapplying patches
+=head2 Applying and Unapplying Patches
 
 Now that we have the patch applied, let's play with it. C<quilt pop> will
 unapply the topmost patch. C<quilt push> applies the next patch in the series.
 You may see the list of unapplied patches with C<quilt unapplied>.
 
-=head2 2.3. Editing patches
+=head2 Editing Patches
 
 To edit a patch, you have to first make it current (be on the top of the stack
 of applied patches). If the patch is already applied (but not the top), run
@@ -106,20 +106,21 @@
 can edit files that were already in the patch and you can edit new files. When
 you're done, remember to tell this to C<quilt> by running C<quilt refresh>.
 
-=head2 2.4. Other commands
+=head2 Other Commands
 
 C<quilt delete> deletes, C<quilt rename> renames a patch. There are a lot
 more. See the manual page.
 
-=head1 3. Integrating within package build process
+=head1 Integrating With the Package Build Process
 
 Obviously, C<quilt> needs to be added to C<Build-Depends>. Note that
-C<Build-Depends-Indep> (for arch:all packages) is not appropriate as C<quilt> is
-needed by the C<clean> target.
-
-Note: Patches should be unapplied before committing to SVN!
-
-=head2 3.1 The "classical" way
+C<Build-Depends-Indep> (for arch:all packages) is not appropriate as
+C<quilt> is needed by the C<clean> target.
+
+Note: Patches should be unapplied before committing to SVN! If you forget,
+don't worry, lintian will issue a warning to remind you.
+
+=head2 The "Classic" Way
 
 C<include /usr/share/quilt/quilt.make> has some candy for F<debian/rules>.
 First, it defines C<QUILT_PATCHES> to be F<debian/patches> so that one doesn't
@@ -132,21 +133,29 @@
 
 Here's a sample fragment from F<debian/rules>:
 
-    include /usr/share/quilt/quilt.make
-
-    build: build-stamp
-    build-stamp: $(QUILT_STAMPFN)
-        dh_testdir
-        ...
-    clean: unpatch
-        dh_clean build-stamp
-        ...
+=begin html
+
+<pre>include /usr/share/quilt/quilt.make
+
+build: build-stamp
+build-stamp: $(QUILT_STAMPFN)
+&#09;dh_testdir
+&#09;...
+clean: unpatch
+&#09;dh_clean build-stamp
+&#09;...</pre>
+
+=end html
 
 Note that using the following:
 
-    build: patch build-stamp
-    build-stamp:
-        ...
+=begin html
+
+<pre>build: patch build-stamp
+build-stamp:
+&#09;...</pre>
+
+=end html
 
 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.
@@ -155,15 +164,19 @@
 This version is available since Etch so the build-dependency can usually be
 without version.
 
-=head2 3.2 The "modern" way
+=head2 The "Modern" Way
 
 Since 0.46-7 C<quilt> offers a simpler integration with debhelper. A simple
 F<debian/rules> can now be written as (needs C<debhelper> >= 7.0.8):
 
-    #!/usr/bin/make -f
-
-    %:
-        dh --with quilt $@
+=begin html
+
+<pre>#!/usr/bin/make -f
+
+%:
+&#09;dh --with quilt $@</pre>
+
+=end html
 
 Alternatively C<dh_quilt_patch> and C<dh_quilt_unpatch> can be added to
 F<debian/rules>.
@@ -171,7 +184,62 @@
 For the details take a look at F</usr/share/doc/quilt/README.Debian> and/or
 C<dh_quilt_patch(1)>, C<dh_quilt_unpatch(1)>.
 
-=head2 3.3 Creating a README.source file
+=head2 The "Post-Modern" Way
+
+Since patches are used so often, the "3.0 (quilt)" source package format
+supports them by default. A running build system will use quilt if it's
+available and C<dpkg-source> can apply patches otherwise. To test your
+package, you can do this:
+
+    $ apt-get source libacme-foo-perl
+    $ mkdir -p libacme-foo-perl-0.1/debian/source
+    $ echo "3.0 (quilt)" >libacme-foo-perl-0.1/debian/source/format
+    $ dpkg-source -b libacme-foo-perl-0.1
+    $ dpkg-source -x libacme-foo-perl-0.1-1.dsc
+    $ cd libacme-foo-perl-0.1 && debuild -us -uc
+
+These instructions come from: L<http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=538676>
+-- you can find more details there.
+
+=head3 Renaming Files
+
+Sometimes you'll need to rename a file, for example if there are some nice
+scripts you'd like to have installed, but they have a B<.pl> extension. For
+Debian packages, scripts are usually installed with the extension dropped,
+so that you can call it on the command line as:
+
+    $ some_utility blahblah
+    # rather than
+    $ some_utility.pl blahblah
+
+In this case, you will need to patch the script file itself so that it only
+refers to itself as the new name. Afterward, you rename the file using an
+override (see the the C<debhelper> article for more). You need to make sure
+the patch is applied first, then the file can be renamed -- this way, if
+one uses C<dpkg-source> to do the patching, it will work properly -- if
+you rename the file first, then dpkg-source won't be able to find the file
+(since the build isn't being run, and the file hasn't been renamed yet)
+and it will fail.
+
+=begin html
+
+<pre>#!/usr/bin/make -f
+
+%:
+&#09;dh --with quilt $@
+
+override_dh_quilt_patch:
+&#09;dh_quilt_patch
+&#09;[ -f bin/some_utility ] || mv bin/some_utility.pl bin/some_utility
+
+override_dh_quilt_unpatch:
+&#09;[ -f bin/some_utility.pl ] || mv bin/some_utility bin/some_utility.pl
+&#09;dh_quilt_unpatch
+</pre>
+
+=end html
+
+=head2 README.source
 
 As of Debian Policy version 3.8.0, packages that use a patch system, such as
 quilt, are required to have a F<debian/README.source> file explaining how to
@@ -180,16 +248,20 @@
 maintained by the Debian Perl Group. The F<debian/README.source> file looks
 like this:
 
-    This package uses quilt to manage all modifications to the upstream
-    source.  Changes are stored in the source package as diffs in
-    debian/patches and applied during the build.
-
-    See /usr/share/doc/quilt/README.source for a detailed explanation.
+=begin html
+
+<pre>This package uses quilt to manage all modifications to the upstream
+source.  Changes are stored in the source package as diffs in
+debian/patches and applied during the build.
+
+See /usr/share/doc/quilt/README.source for a detailed explanation.</pre>
+
+=end html
 
 You can also use C<packagecheck -Q -c> to generate the F<debian/README.source>
 file.
 
-=head1 4. Why quilt is better?
+=head1 Why quilt (versus other patch systems)
 
 =over
 
@@ -214,9 +286,9 @@
 
 =back
 
-=head1 5. Tips and tricks
-
-=head2 5.1. Cleaner patches
+=head1 Tips and Tricks
+
+=head2 Cleaner Patches
 
 By default, C<quilt> saves patches that look like the output from C<diff>.
 This means they include timestamps for each changed file.  C<quilt> also
@@ -234,7 +306,7 @@
 next time you C<quilt refresh> a patch, C<quilt> will remove the extraneous
 information.
 
-=head2 5.2. Unified reject files
+=head2 Unified Reject Files
 
 If upstream has made a change that conflicts with a patch, one normally
 force-applies the patch (with C<quilt push -f I<patch>>) and then looks at the
@@ -267,9 +339,11 @@
 
 =item * Russ Allbery <rra at debian.org>
 
+=item * Jonathan Yu <frequency at cpan.org>
+
 =back
 
-=head1 License
+=head1 License and Copyright
 
 Copyright (c) 2007-2009 Debian Perl Group.  All rights reserved. This document
 is free software; you may redistribute it and/or modify it under the same terms


