== Working on RPMs with _quilt_: an illustrated guide

I've [[mentioned _quilt_ before ../programming/SoftwarePointersI]];
it's a package for managing a series of patches. One of the things it's
really handy for is modifying source RPMs (which themselves are mostly
a series of patches on top of a base source tree, hence the good fit).
However, there's a bit of arcana involved in the process, so it's useful
to have an example.

(Since my margin is only so big, I'm going to assume that you're
broadly familiar with building RPMs and RPM specfiles. If not, look
around [[rpm.org http://www.rpm.org/]].)

First, you need to be using the sensible RPM build setup I described
[[here RPMBuild]]. I'll also assume that you already have a source RPM
that you want to modify; I'm starting with one for [[Liferea
http://liferea.sf.net/]] 1.0.9.

* _cd sys/RPMS/SOURCES/liferea-1.0.9_
* _quilt setup *.spec_ \\
  This creates a _liferea-1.0.9_ source tree as a subdirectory and sets
  it up for quilt.
* _cd liferea-1.0.9_

* _ln -s .. patches_

You only need to create this symlink if the source RPM has no patches
itself; otherwise quilt does it automatically (a future version of
quilt may fix this oddity). The symlink makes it so that quilt's patch
area is the same as the RPM source's patch area, which is exactly what
we want.

We're now ready to start actually patching things:

* _quilt new liferea-1.0.9-atom-title.patch_ \\
  Some style issues:
  * It's a good idea to start your patch series with the least
    controversial patches, the ones most likely to be accepted as bugfixes
    or whatever by the upstream developers, because the earlier they are the
    easier they're going to be to merge as standalone patches.
  * It's a convention to name RPM patches like this. The descriptive
    bit in the middle shouldn't be too long, but it should give someone
    skimming a list of patches some idea of what your patch is about.
* _quilt add src/atom10.c_
* edit src/atom10.c in your favorite editor
* _quilt refresh_: this actually generates the patch file (and will
  happily tell you about it).
* edit the patch file to add an explanation of what the patch
  is about and why it's necessary at the top; quilt will ignore
  (but preserve) this text. I tend to write the sort of explanation
  that I'd put in email to the upstream developers if I were to mail
  the patch off to them.

* _cd .._ to get back up to the RPM source directory
* edit the specfile to include the new patch. I usually start my own
  patches as _Patch50_ or so, so there's a big numbering gap between
  upstream source RPM patches and mine.
* _rpmbuild -bb *.spec_, and see if the patch actually works.

Now to illustrate the process of using quilt on an RPM with existing
patches, I'll delete the _liferea-1.0.9_ directory and the _series_ file
and start again:

* _quilt setup *.spec; cd liferea-1.0.9_ \\
  (We don't need to set up the _patches_ symlink; now that the RPM
  already has a patch, quilt has done this for us.)
* _quilt push -a_

One of the few gotchas of using quilt with RPMs is that quilt defaults
to starting off a newly set up patch area with no patches applied,
instead of applying all of the patches from the RPM spec file and
starting there. So if we were to just go ahead and start a new patch,
it would wind up being at the *front* of the patch list, quite possibly
causing some of the other patches to fail, instead of at the end. The
_quilt push -a_ applies all of the already existing RPM patches, so
we're where we want to be.

(I've made this mistake, and it can be *very* irritating.)

* _quilt new liferea-1.0.9-atom-times.patch_
* _quilt add src/atom10.c src/metadata.c_
* edit the two files
* _quilt refresh_
* edit the new patch file to explain things, _cd .._,
  edit specfile, build, test, etc.

Interested people can find the actual patches on my [[liferea patches
page /Programs/LifereaPatches]].

PS: yes, this was sort of a cooked demo; I was less writing patches
from scratch and more rolling forward existing patches I'd already
written for an older version of [[liferea http://liferea.sf.net/]].
Real quilt usage may have more flailing around with adding and
removing files from patches and so on.

=== Sidebar: the basics of adding patches to RPM specfiles

Given a patch, like _liferea-1.0.9-atom-title.patch_:

# go the initial section of the specfile and look for the _Source:_
  header (or _SourceN:_ or a few other things), or any existing _PatchNN:_
  lines.
# add a _PatchNN:_ line for your patch, like '_Patch50:
  liferea-1.0.9-atom-title.patch_'. Pick an NN value that is significantly
  larger than any existing ones, and remember it. (Also, to keep your
  sanity, keep the PatchNN headers ordered.)
# skip down to the _%prep_ section, which describes how to unpack the
  source and apply patches *and what order this happens in*. Add a
  _%patchNN_ directive for your patch, *after* the _%setup_ (and any
  existing _%patch_ directives), like '_%patch50 -p1 -b .atomtitle_'. The
  %patch options are more or less the same as for _patch(1)_.
# skip down to the _%changelog_ section; add your own entry.
# skip up to the _Release:_ header and change it; for example, I add
  _.cks._*N* to most of mine. This clearly marks your RPM build as a
  non-standard version. (Usually my *N* is 1, but occasionally I have
  to respin an RPM and bump it up.)
# Comment out any _Packager:_ and _Vendor:_ lines that already exist,
  because you're probably not them. Optionally add your own.

You're done.