Customizing FreeBSD Port Installations With Patch Files

-
This article presumes the reader has a good working knowledge of the FreeBSD ports system. For more information see the ports manpage, the FreeBSD handbooks section on ports and the FreeBSD porters handbook.
-

The FreeBSD ports tree is great, but when it comes to making changes to the files that are installed by a port you have to be careful so as not to lose any changes when you upgrade. Say you install a port like the Serendipity weblog software, then go to modify a template. Everything works great but unfortunately when you next use portupgrade you find the changes you made were all clobbered by the upgrade! Not good.

There are a few solutions to this problem, but probably the most natural method - in terms of keeping with the ports system and your own changes in harmony - is to create your own custom patch files and place them inside the port's 'files' directory. This way when you install or upgrade a port, the files you want patching to include your modifications will automatically be patched.

Here's a simple example using this weblog, Serendipity. I want to modify the template I'm using so it includes a Google Analytics tracker in each and every page to help track web usage. The easiest way to do this is to modify the index.tpl file so it includes the analytics tracker code just before the closing </body> tag of the index.tpl file.

To make the changes permanent after an upgrade, instead of just going ahead and modifying the 'live' index.tpl that's already installed I'm going to make the changes to the index.tpl file located in the serendipity ports working directory 'work' and then create a patch file that will transform the original index.tpl to the modified index.tpl.

To do this step by step:

1. Ensure the working directory for serendipity is available - to do this run 'make extract' to extract the distfile's contents into the 'work' directory:
   
   CODE:
   root@users /home/munk/ports/www/serendipity# cd /usr/ports/www/serendipity/
   root@users /home/munk/ports/www/serendipity# make extract
   ===>  Found saved configuration for serendipity-1.0.1
   ===>  Extracting for serendipity-1.0.1
   => MD5 Checksum OK for serendipity-1.0.1.tar.gz.
   => SHA256 Checksum OK for serendipity-1.0.1.tar.gz.
   
   
2. Move into the template directory and create a copy of the file you want to modify, naming it <file>.orig, where <file> is the name of the file to be modified:
   
   CODE:
   root@users /home/munk/ports/www/serendipity# cd work/serendipity/templates/contest/
   root@users /home/munk/ports/www/serendipity/work/serendipity/templates/contest# cp index.tpl 
   index.tpl.orig
   
   
3. Make the changes to the file you're modifying - note NOT the .orig file! - in this case I need to make changes to index.tpl to add the following before the ending tag:
   
   CODE:
   <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
   </script>
   <script type="text/javascript">
   _uacct = "UA-XXXXXX-1";
   urchinTracker();
   </script>
   
   
4. Create a patch file in the 'files' directory of the port containing the unified diffs between the original file and the modified file.
   Notes:
   
   1. The name of the patch file MUST begin with 'patch-' to be treated as a patch file. The rest of the filename should reasonably indicate what the patch file contains. In my case I'll call the patch file 'patch-templates_contest_index.tpl'.
      
   2. The patch must be made relative to the directory into which the port's distfile was extracted - if in doubt check over other port's patch files to see how they do it!
      
   3. Make sure the .orig file is first in the diff command
   
   
   CODE:
   root@users /home/munk/ports/www/serendipity/work/serendipity/templates/contest# cd ../..
   root@users /home/munk/ports/www/serendipity/work/serendipity# diff -u templates/contest/index.tpl.orig templates/contest/index.tpl > usr/ports/www/serendipity/files/patch-templates_contest_index.tpl
   root@users /home/munk/ports/www/serendipity/work/serendipity# cat /usr/ports/www/serendipity/files/patch-templates_contest_index.tpl
   --- templates/contest/index.tpl.orig    Thu Sep  7 03:13:56 2006
   +++ templates/contest/index.tpl Thu Sep  7 03:14:08 2006
   @@ -52,6 +52,13 @@
    <div id="copyright">Design <a href="http://garv.in/">Garvin Hicking</a>, Icons 
   <a href="http://tango-project.org/">Tango Project</a></div>
   
    {if $is_embedded != true}
   +<script src="http://www.google-analytics.com/urchin.js"
   +type="text/javascript">
   +</script>
   +<script type="text/javascript">
   +_uacct = "UA-669467-1";
   +urchinTracker();
   +</script>
    </body>
    </html>
    {/if}

Now if all went well we should be able to run portupgrade on the installed port - or just run 'make install' in the port directory if it's not installed yet - and the modifications to the index.tpl file should be made automatically.

Admittedly this is a slightly complicated process and there are other easier ways of keeping a file after an upgrade - for example modify pkgtools.conf to make portupgrade execute commands after the port is installed to copy over the files you want updating. However this method isn't as reliable as the patch file method. If any changes are made to the files you're overwriting, portupgrade will never let you know about it - whereas with the patch file method, if one of the files you're wanting to modify has changed in the distribution tarball, then in all likelyhood the upgrade will fail becaue the patch process fails. This allows you to look at the files that have changed in the distribution and change your patch file appropriately.