[Jim's Web Nook | Window Maker Stuff | Patches | Patching-HOWTO]
Here's what's here:
When you have an article of clothing with a hole in it---for example, a pair of pants---you can repair the hole by sewing or gluing on a patch---another piece of fabric designed to cover the hole. Sometimes, patches don't necessarily cover a hole; sometimes they keep holes from forming to begin with, by reinforcing the pants. Other patches may simply add decoration.
Similarly, in the jargon of computer software, a patch is a separate "piece" of a computer program, designed to be "stitched" into or "glued" onto a program to repair a problem in the original program (a "hole" or bug) or to add functionality (not always merely decoration). Patches can fix a bug or security hole in a program, stop a program from crashing, or add extra features to a program.
In the case of open source software or free software (or any other software for which you have the source code), a patch is usually a specially-formatted piece of source code, sometimes called a diff (because the program used to produce the patch is also called diff, short for "difference"). Not only does a diff show the difference between to sets of source files (the original files and the patched ones), but, because of its special formatting, a diff contains the information necessary to to change another set of original files into patched ones.
When you apply a patch over the hole in your pair of pants, you usually use a special tool: a sewing machine, or a needle and thread, or a clothes iron with a heat-sensitive iron-on patch. In the same way, you usually apply a patch using a special tool designed for "stitching" together pieces of software.
It can be particularly easy to apply a diff to software for which you have the source code. Before building and installing the software, you pass the diff to a tool called, appropriately, patch. Patch can understand several different diff formats and automatically apply them to your source files.
Unfortunately, the procedure isn't always completely automated; you sometimes have to be able to read the patch to determine how to invoke (or start) patch.
Let's use a patch from my supply of patches for Window Maker as an example: the one named WindowMaker-0.65.1-clip-captions.patch.
First, notice that the patch's filename contains the name (WindowMaker) and version number (0.65.1) of the software it's intended to patch, as well as a short description (clip-captions) of what the patch is for. Not all patches are named in this fashion; if they're not, it's not always easy to tell what software package or what version of the software the patch is for, or sometimes even what the patch does. Obviously, it is often a good idea to name patches in this fashion.
To apply WindowMaker-0.65.1-clip-captions.patch, the first thing to do is acquire the source code for Window Maker. The source code comes in a tar archive which has been compressed using the bzip2 program. Such compressed archives are sometimes called tarballs.
Once you have the source code, let's unpack the tarball into a subdirectory (to be safe):
That last one looks like a long command (it is). Briefly, bunzip2 uncompresses the tarball, and tar -x unpacks the files contained in the tar archive. The v makes tar list the files as it unpacks them, so that you can see what you unpacked. The rest "glues" the commands together. You should end up with a subdirectory named WindowMaker-0.65.1. Change to that directory:mkdir patched-WindowMaker cd patched-WindowMaker bunzip2 -c ../WindowMaker-0.65.1.tar.bz2 |tar -xvf -
cd WindowMaker-0.65.1
Finally, let's apply the patch (assuming it's in the same place as the Window Maker source tarball):
Patch should produce output that looks similar to this:patch -p0 <../../WindowMaker-0.65.1-clip-captions.patch
patching file `./src/balloon.h' patching file `./src/balloon.c' patching file `./src/dock.c' Hunk #7 succeeded at 4061 (offset 1 line). Hunk #9 succeeded at 4163 (offset 1 line). Hunk #11 succeeded at 4218 (offset 1 line). patching file `./src/wconfig.h.in'
How did patch know what to do? Let's have a look at the patch:
You can see that the patch file begins with the following lines:head -15 ../../WindowMaker-0.65.1-clip-captions.patch
You can see that the file ./src/balloon.h, which was the first file patch said it patched, is listed at the top of the diff (on the second line, after the +++ symbols). The top line shows the original file, in this case ./src/balloon.h.orig-clipcaptions.--- ./src/balloon.h.orig-clipcaptions Wed Oct 21 09:43:54 1998 +++ ./src/balloon.h Mon Aug 13 11:33:06 2001 @@ -26,6 +26,10 @@ void wBalloonEnteredObject(WScreen *scr, WObjDescriptor *object); +#ifdef PRETTY_CLIP_CAPTIONS +void wBalloonChangeText(WScreen *scr, char *text); +#endif + void wBalloonHide(WScreen *scr); #endif --- ./src/balloon.c.orig-clipcaptions Mon Jul 23 13:31:49 2001 +++ ./src/balloon.c Mon Aug 13 11:35:40 2001
Sometimes, folks make patches from outside the subdirectory containing the source code. If i had done that with WindowMaker-0.65.1-clip-captions.patch, it might look like this instead:
The advantage to making patches like this is that the patch itself tells you the name and version of the software it's inteded to patch. To apply such a patch, you would follow the same procedure as above, but using the following patch command instead:--- WindowMaker-0.65.1.clipcaptions/src/balloon.h Wed Oct 21 09:43:54 1998 +++ WindowMaker-0.65.1/src/balloon.h Mon Aug 13 11:33:06 2001 @@ -26,6 +26,10 @@ void wBalloonEnteredObject(WScreen *scr, WObjDescriptor *object); +#ifdef PRETTY_CLIP_CAPTIONS +void wBalloonChangeText(WScreen *scr, char *text); +#endif + void wBalloonHide(WScreen *scr); #endif --- WindowMaker-0.65.1.clipcaptions/src/balloon Mon Jul 23 13:31:49 2001 +++ WindowMaker-0.65.1/src/balloon.c Mon Aug 13 11:35:40 2001
The -p1 tells patch to skip the first subdirectory name of each file listed in the patch.patch -p1 <../../WindowMaker-0.65.1-clip-captions.patch
Once you've patched the source code, you can build and install the software as you normally would. For example, for Window Maker:
./configure make make install
Happy patching!
[Jim's Web Nook | Window Maker Stuff | Patches | Patching-HOWTO]
Copyright © 1996-2001 Jim Knoble and Liquid Meme. All rights reserved.