Patch development

If you have not yet read the overview documentation, please do so now.

Hello world example patch

tklpatch-example helloworld

This executes tklpatch-example to create an example patch in the helloworld/ directory. If more fine-grained control is needed in your patch then an advanced example can be created using the --advanced switch.

When this patch is applied to an ISO it will create a new ISO in which the hello package is installed and the message of the day has been changed. Let's try it on turnkey-core.iso (which we downloaded earlier) and see tklpatch in action:

tklpatch turnkey-core.iso helloworld

Behind the scenes, when tklpatch applied our helloworld patch it followed the instructions in the patch's 'conf' file:

$ cat helloworld/conf
#!/bin/bash -ex
install()
{
    apt-get update
    DEBIAN_FRONTEND=noninteractive apt-get -y \
        -o DPkg::Options::=--force-confdef \
        -o DPkg::Options::=--force-confold \
        install $@
}

# installs hello - a highly useful package
install hello

# tell the world what we've done!
echo 'Hello world - I just patched TurnKey!' >> /etc/issue

Drupal5 example patch

For educational purposes, tklpatch includes a more complex example patch which will turn TurnKey LAMP into a Drupal5 appliance. The patch is located in /usr/share/tklpatch/examples when tklpatch is installed via apt-get, or /usr/local/share/tklpatch/examples when installed from source. The example patch is also available on github for reference.

Create the skeleton of a new patch from scratch

mkdir mypatch
mkdir mypatch/debs
mkdir mypatch/overlay
touch mypatch/conf; chmod +x mypatch/conf

Now you need to figure out how your patch should change the patched appliance to get the result you want. It's often easiest to figure this out interactively in a "live" system by trial and error. You can setup such a test environment by installing the appliance you want to patch in a VM and then experimenting to find what changes you need to make. You can also experiment in a chroot environment.

Development tips and tricks

TKLPatch has a modular design which allows you to develop your patch incrementally inside an installed virtual appliance instance or in the extracted root filesystem of an ISO image. A development cycle in which you tweak and test in fast succession is often more productive than one that has a long feedback loop.

How to setup and experiment in a chroot environment:

tklpatch-extract-iso path/to/image.iso

This will extract the appliance's filesystem and cdroot from the ISO. You can then chroot into the appliance's filesystem. Inside the chroot it's easy to experiment to find out what your patch should do. For example you might manually install packages, make tweaks to the configuration, etc. When you know what needs to be done, update mypatch to reflect it (e.g., by adding instructions to conf, files to the overlay, etc.)

tklpatch-chroot path/to/image.rootfs

Once complete, you may remove the temporary rootfs and cdroot directories you experimented in, and test your patch (preferably in a virtual machine) by applying it to your ISO of choice:

tklpatch path/to/image.iso path/to/mypatch

Next, publish it.