r40965 - /website/howto/quilt.pod
jawnsy-guest at users.alioth.debian.org
jawnsy-guest at users.alioth.debian.org
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)
+	dh_testdir
+	...
+clean: unpatch
+	dh_clean build-stamp
+	...</pre>
+
+=end html
Note that using the following:
- build: patch build-stamp
- build-stamp:
- ...
+=begin html
+
+<pre>build: patch build-stamp
+build-stamp:
+	...</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
+
+%:
+	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
+
+%:
+	dh --with quilt $@
+
+override_dh_quilt_patch:
+	dh_quilt_patch
+	[ -f bin/some_utility ] || mv bin/some_utility.pl bin/some_utility
+
+override_dh_quilt_unpatch:
+	[ -f bin/some_utility.pl ] || mv bin/some_utility bin/some_utility.pl
+	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
More information about the Pkg-perl-cvs-commits
mailing list