3.7 Applying a Patch

After you've been running Squid for a while, you may find that you need to patch the source code to fix a bug or add an experimental feature. Patches are posted for important bug fixes on the squid-cache.org web site. If you don't want to wait for the next official release, you can download and apply the patch to your source code. You will then need to recompile Squid.

To apply a patch ”also sometimes called a diff ”you need a program called patch . Chances are that your operating system already has the patch program. If not, you can download it from the GNU collection (http://www.gnu.org/directory/patch.html). Note that if you're using anonymous CVS (see Section 2.4), you don't need to worry about patching files. The CVS system does it for you automatically when you update your tree.

To apply a patch, you need to save the patch file somewhere on your system. Then cd to the Squid source directory and run the command like this:

 % cd squid-2.5.STABLE4 % patch < /tmp/patch_file 

By default, the patch program tells you what it's doing as it runs. Usually this output scrolls by very quickly, unless there is a problem. You can safely ignore the warnings that say offset NNN lines . If you don't want to see all this output, use the -s option to make patch silent.

When patch updates the source files, it creates a backup copy of the original file. For example, if you're applying a patch to src/http.c , patch names the backup file src/http.c.orig . Thus, if you want to undo the patch after applying it, you can simply rename all the .orig files back to their former names. To use this technique successfully, it's a good idea to remove all .orig files before applying a patch.

If patch encounters a problem, it stops and prompts you for advice. Common problems are as follows :

• Running patch from the wrong directory. To fix this problem, you may need to cd to a different directory or use patch 's -p option.

• Patch is already applied. patch can usually tell if the patch file has already been applied. In this case, it asks if you want to unpatch the file.

• The patch program doesn't understand the file you are giving it. Patch files come in three flavors: normal, context, and unified. Old versions of patch may not understand context or unified diff output. Getting the latest version from the GNU FTP site will solve this problem.

• Corrupted patch file. If you aren't careful when downloading and saving the patch file, it may become corrupted. Sometimes people send patch files in email messages, and it is tempting to simply cut-and-paste them into a new window. On some systems, cut-and-paste can change Tab characters into spaces, or incorrectly wrap long lines. Both changes confuse patch . The -l option may be helpful, but it's best to make sure you copy and save the patch file correctly.

Sometimes patch can't apply part or all of the diff. In these cases, you'll see such messages as Hunk 3 of 4 failed . The failed sections are saved to files named .rej . For example, if a failure occurs while processing src/http.c , patch saves that piece of the diff to src/http.c.rej . In some cases, you may be able to fix these by hand, but it's usually not worth the trouble. If you have a lot of "failed hunks" or .rej files, it's a good idea to download a whole new copy of the latest source code.

After you apply a patch, you need to recompile Squid. One of the great things about make is that it only recompiles the files that have changed. But sometimes make doesn't comprehend all the intricate dependencies, and it doesn't rebuild enough of the files. To be safe, it's usually a good idea to recompile everything. The best way to do this is to clean the source tree before recompiling:

 % make clean % make