=head1 Quilt for Debian Maintainers This guide briefly introduces usage of C for managing patches to debian packages. It will describe how to create, modify, apply and unapply patches with C. This is a work in progress. Please send any comments or ideas to . =head2 Copyable Version This is a version of the original document, which has been forked to provide copy/paste-compatible information. The original B and this version diverged in revision 40966. Please consider B to be the authoritative version of this document, maintained by Damyan Ivanov. =head1 The Big Picture C 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 and C's simple-patchsys in that the patches are kept as a series of files in F. =head2 Preparation C uses a special directory for keeping patches (not very surprising). Unfortunatelly, that directory is F<./patches/> by default. For Debian packages F<./debian/patches/> is far more comfortable. To flawlessly fix this, add C in your shell resource file and reload it. This way you won't have to worry about this quilt oddity (like me; even forgot to mention it in the first revision of this document). You can also create F<.quiltrc> in your home directory and set C there if you prefer. =head2 Patch Order: the 'series' C manages the series of patches as a stack. You push to it (apply a patch) and pop from it (unapply a patch). There's one special file, F, which contains the list of all patches to be applied. C applies patches in the order they are listed in that file. =head2 Philosophy C 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 just to be able to extract a diff with SVN. To achieve this, however, C needs to know which files are contained in each patch. The workflow is as follows: =over =item 1. you tell C that you start working on a given patch =item 2. you work on that patch =item 3. you tell C that you're done =back 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. =head2 Working With quilt Here are a few examples of working with C. Note that most of the commands below have plenty of options so reading quilt man page is a good idea. =head2 Creating a Patch To create a patch, run C. If you want C<.patch> extension, you need to give it. This will create a new patch entry in F. This patch also becomes the I or current patch. This is the patch that is at the top of the stack. Now choose what file you want to change in that patch and run C. C will note the current state of the file and launch your C<$EDITOR> so you can edit the file. Repeat the C command for all files you want to be changed by that patch. When you're finished, run C. This will compare the noted state of the edited files with their present state and produce a patch in F. Note that that patch is currently applied. Check it with C. If the package is already being maintained in the pkg-perl svn repository, it is necessary to tell svn that you have added new files. You can do this with C. =head2 Applying and Unapplying Patches Now that we have the patch applied, let's play with it. C will unapply the topmost patch. C applies the next patch in the series. You may see the list of unapplied patches with C. =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 C; if it is not, run C. Now that the patch is on the top of the stack, run C as before. You 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 by running C. =head2 Other Commands C deletes, C renames a patch. There are a lot more. See the manual page. =head1 Integrating With the Package Build Process Obviously, C needs to be added to C. Note that C (for arch:all packages) is not appropriate as C is needed by the C 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 has some candy for F. First, it defines C to be F so that one doesn't have to worry about that setting during the build process. Second, it defines C, which can be used as a C or C dependency. Lastly, C target is useful as a C dependency. Here's a sample fragment from F: =begin html
include /usr/share/quilt/quilt.make

build: build-stamp
build-stamp: $(QUILT_STAMPFN)
	dh_testdir
	...
clean: unpatch
	dh_clean build-stamp
	...
=end html Note that using the following: =begin html
build: patch build-stamp
build-stamp:
	...
=end html can fail if parallel build is allowed via C<-jN>. C and C would be run in parallel, possibly failing due to partly applied patches. N.B. F is available since C version 0.40. This version is available since Etch so the build-dependency can usually be without version. =head2 The "Modern" Way Since 0.46-7 C offers a simpler integration with debhelper. A simple F can now be written as (needs C >= 7.0.8): =begin html
%:
	dh $@ --with quilt
=end html Alternatively C and C can be added to F. For the details take a look at F and/or C, C. =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 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 -- 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 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 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
%:
	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
=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 file explaining how to generate the patched source, add a new modification, and remove an existing modification. A standard F file is used for all packages maintained by the Debian Perl Group. The F file looks like this: =begin html
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.
=end html You can also use C to generate the F file. =head1 Why quilt (versus other patch systems) =over =item * patch creating/editing is faster This is due to the fact that quilt works within the source tree. C needs to create a copy, then diff recursively. Using C to create patches is impossible if you have a file that is modified by several patches. C does this naturally. =item * fixing a rejected file is easier quilt push -f # force rejections quilt edit files-with-rejections quilt refresh =item * refreshing a fuzzy patch is a breeze quilt push quilt refresh =back =head1 Tips and Tricks =head2 Cleaner Patches By default, C saves patches that look like the output from C. This means they include timestamps for each changed file. C also preserves C lines, such as those generated by C. However, C doesn't need any of that data to apply the patch and it has the unfortunate side effect of causing every file header line of the patch to change each time someone runs C. To use the simplest headers in the patch, add: QUILT_DIFF_ARGS="--no-timestamps --no-index -pab" QUILT_REFRESH_ARGS="--no-timestamps --no-index -pab" to F<~/.quiltrc> or set those variables in the environment if you prefer. The next time you C a patch, C will remove the extraneous information. =head2 Unified Reject Files If upstream has made a change that conflicts with a patch, one normally force-applies the patch (with C>) and then looks at the resulting F<*.rej> file to see what part of the patch failed. By default, the F<*.rej> file is a traditional context diff similar to the output of C. If you're used to the output of C, you can tell C to create unified context diffs for the F<*.rej> files by putting: QUILT_PATCH_OPTS="--unified-reject-files" in your F<~/.quiltrc> or by setting that variable in the environment. B: I<--unified-reject-files> was removed in C. Having this option in F<~/.quiltrc> breaks quilt. =head1 Version $Id: quilt.pod 40966 2009-07-29 02:40:27Z jawnsy-guest $ =head1 Authors =over =item * Damyan Ivanov =back =head1 Contributors =over =item * gregor herrmann =item * Russ Allbery =item * Jonathan Yu =back =head1 License and Copyright Copyright (c) 2007-2011 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL' and the Artistic License in `/usr/share/common-licenses/Artistic'. =for comment vim:tw=79