HOWTO use quilt
(for balloon development)
Intro
As of 2007-05-31 the official balloon kernel sources are in balloonboard.org svn in the form of patches.
These are normal patches which can be used manually in the usual way if you so wish, but if you are going to make any changes to check in then using and understanding quilt will make this hundreds of times easier.
Quilt is a patch management system. The docs are good: there is a man page (http://www.die.net/doc/linux/man/man1/quilt.1.html) and PDF file (http://www.suse.de/~agruen/quilt.pdf), but they both fail to get over the underlying concept well so you still wonder how to actually use it if you have never done so before. Hence this HOWTO.
aptitude install quilt or rpm -i quilt to get it installed.
Setup
We will use balloon kernel source as an example: svn checkout svn://balloonboard.org/balloon/trunk balloonsvn
You should just be able to to do
cd balloonsvn make
to set up a ../build directory with kernel source downloaded, and patched with quilt (and a balloon kernel built). BUt lets do this manually so you understand what's going on.
mkdir -p build/kernel cd build/kernel wget -N http://balloonboard.org/files/balloon3/distro/test-v0.2/sources/kernel/linux-2.6.21.1.tar.bz2 tar -xvjf linux-2.6.21.1.tar.bz2
so that's unpacked the sources so we have build and balloonsvn at same level (You can put the sources anywhere you like - this just matches up with the structure used by the makefiles. You do all the work within the source tree.)
Now we create a patches directory in the source tree we are working in. This can be a copy, but it best to use a link in this case so the changed patches are automatically in the svn tree ready for checkin.
cd linux-2.6.21.1 ln -s ../../../balloonsvn/kernel/2.6.21.1 patches
OK. that's it for setup. Now to show how to use it.
Basic use
Just a few commands to show what it can do first. Do them in order:
quilt series will list all the patches and their order
quilt push -a will apply all the balloon patches to the kernel
quilt pop -a will remove them all
quilt push will apply the first patch
quilt top will show you the name of the current patch.
This is an important concept. Most quilt actions take place on the current patch by default. This is the one that has been applied, and any edits you make will be added to it.
quilt files will show you which files are touched by this patch
quilt next will show you which patch is next in the series
quilt applied shows which patches have been applied
quilt unapplied shows which patches have still to be applied
All commands can be reduced to shortest distinguishable length quilt un, quilt t, quilt po}}, {{{quilt pu
You can do them anywhere in the source tree - they will still do the same thing. No need to be at the top.
The order of patches is determined by the series files in the patches dir. You can just edit this file manually if you like.
Making changes
OK, so now we get to the meat of the issue - how do you change make edits and modify the patch series?
Make the current patch 2.6.21.balloon3.patch if it isn't already (push, pop), and quilt files to show that it affects files:
Makefile arch/arm/Kconfig arch/arm/mach-pxa/Kconfig arch/arm/mach-pxa/Makefile arch/arm/mach-pxa/balloon3.c include/asm-arm/arch-pxa/balloon3.h include/asm-arm/arch-pxa/debug-macro.S include/asm-arm/arch-pxa/irqs.h include/asm-arm/arch-pxa/uncompress.h
So, now go and edit one, say arch/arm/mach-pxa/balloon3.c. Add a comment or something.
Now you can do
quilt refresh
and the current patch is updated to include the changes you made. You can go and look in build/kernel/linux-2.6.21.1/patches/2.6.21.balloon3.patch to check if you like.
So that's the first clever bit. Any changes you make to already-patched files are magically updated if you just do a refresh.
Now, lets say you want to modify a file which is in the sources, but not patch of this patch - say . The thing to remember is to tell quilt before you edit it. Otherwise it can't know what to diff against. This is the main thing you have to remember when using quilt to avoid annoyance.
quit add driver/base/core.c
- This means that changes to this file will now be added to the current patch.
So now edit driver/base/core.c (random file - only do innocuous things!), then
quilt refresh
- to update the current patch (2.6.21.balloon3.patch) to include the changes to this file.
To remove this file from the patch you do quilt remove driver/base/core.c. Note that you are giving a path here, so if you are already in driver/base dir then the command is
quilt remove core.c
OK. So now I hope you get the general idea how it works.
making new patches
Now lets try that last example again but making a new patch instead of adding the file to the current patch. This often makes more sense - trying to keep each patch having one logical set of changes is the idea here, as now lots of small patches is easy to manage.
So this time we start by doing
quilt new test.patch
to create a new empty patch, which becomes the current patch, inserted into the series at the current point. If you want to add the new patch at the end of the series then quilt push -a to get there before doing the quilt new.
Then do
quilt add driver/base/core.c
- as before, then edit, save and
quilt refresh
- to update the new patch.Then carry on adding and editing or removing files until the new patch contains all the stuff you want it to. Simple.
To remove a patch from the series use
quilt remove test.patch
importing existing patches
quilt import somepath/name-of-new.patch
will do the trick. The catch is often the -pn patch level. You can specifiy this in the import command, but if you forget or get it wrong, just add the appropriate -p0 or -p1 or whatever to the series files, after the patch name i.e.:name-of-new.patch -p1
further stuff
OK. I hope that's enough to understand essentially how quilt works. Now you should find the supplied documentation mentioned at the top to be helpful. There is lots of advanced stuff like quilt fold to merge patches and quilt fork to split patches, and quilt graph to show the interdependencies between patches. When I understand those a bit better maybe I'll add some more to this tutorial.