klik tips+tricks: how to hack (or fix) a klik bundle

Time to reveal a few more of the little tricks around klik...

This time it is "How do I fix a klik AppDir bundle if it does not work the way I want it to work?"

Easy. Follow these steps to troubleshoot a problematic klik .cmg file. (We assume, that your Kernel is in fact cramfs and loop-mount enabled; this is surely the case, if you succeeded before to run one of the simpler klik applications, like klik://xvier, and only suffer from a problem with certain .cmg files).

We'll use as an example "Kalzium", the cool chemistry application (screenshots) by Carsten Niehaus, from the KDE Education module. (I do not say the bundle needs a fix -- it works fine for me; but maybe someone wants to update it manually to KDE-3.5, so that it contains the latest and greates improvements Carsten made?).

Step 1

The IP of klik.atekon.de is 134.169.172.48 in case the DNS problem is still prevalent. It is advisible to re-install the klik client from time to time. The reason is: klik is a development in full swing. We add bugfixes and improvements (like handling of new distros), and this will only make it to you if you let the client be re-installed onto your system. The way to install the klik client is this: hit "[alt]+[f2]"; type "wget klik.atekon.de/client/install -O - | sh"; hit "Enter". This install script is not saved onto your harddisk (only its output is), but executed on the fly by piping its content into a shell (the "| sh" part). If you want to have a look at the install script itself (it is only 15 kByte), modify the above sequence like this: "[alt]+[f2]"; type "wget klik.atekon.de/client/install"; hit "Enter". This will save (and not execute) the file "install". As was already outlined in my initial Dot article, the install procedure creates two files in your home directory: .zAppRun and .klik, plus a few .desktop, .protocol and .hidden files.

STEP 2

You know by now how to klik-copy and -run the existing kalzium bundle, yes? Just do "[alt]+[f2]"; "klik://kalzium". The "klik://kalzium" fake URL in the meanwhile does not just work for KDE and Konqueror -- Firefox and elinks are now supported too. What the "klik://kalzium" action then will do is this: it contacts the klik server to ask for "kalzium"; the klik server sends back the Kalzium "recipe" containing a list of Debian packages (Kalzium plus dependencies) to download, plus the commands to unpack the Debian packages, to stuff them into a directory structure, to spice the soup with additional symlinks and environment variables ($PATH and $LD_LIBRARY_PATH) come to mind), to arrange them in a way so that the correct directory structure is the result, and finally to compress them into a cramfs filesystem image.

STEP 3

Once the Kalzium is started, you can find the file "kalzium.cmg" in your ${HOME}/Desktop/ directory. This .cmg is a compressed image containing a compressed file system (much like the ISO image that fills the complete Knoppix or Kanotix CD) which holds all binaries, libraries, icons and helper files that the Kalzium application needs to run. If you do not like the default locations where klik stores your new klik-able applications, you can freely move the kalzium.cmg file to other locations; it will still run from there.

STEP 4

Unpack the bundle: "cd ${HOME}/Desktop/; /sbin/fsck.cramfs -x kalzium/ kalzium.cmg". This creates the "kalzium/" sub directory, where you can now browse the contents of the bundle. You could browse the bundle by mounting it, or by running it (which mounts it too) -- but then it would be read-only, and you could not make changes to it.

STEP 5

Now go into this "kalzium" directory and explore it. Find the "wrapper" script, and have a look at it. Find the "usr/" and "opt/" subdirs, and take note of their contents (symlinks as well as real files).

STEP 6

Did I tell you yet, that you can run the application from the subdirectory? Try this: "cd kalzium; sh wrapper". For more output (possibly good for debugging): "sh -x wrapper".

STEP 7

You may be one the Kalzium developers: this means you do not like the old version of your app so much that is represented by the downloaded kalzium.cmg. OK, go ahead, exchange all binaries and libs and icons and documents in that subdirectory for newer ones!

STEP 8

When you are done with the modifications: test the changes inside the "kalzium" subdirectory first, by running again the app via the wrapper script: "cd kalzium; sh -x wrapper".

STEP 9

Fix any problems you encounter; repeat STEPS 5-8 as often as needed

STEP 10

Last, pack the new bundle into a compressed image file: "cd ${HOME}/Desktop/; /sbin/fsck.cramfs kalzium/ kalzium-new.cmg"

STEP 11

Run the new bundle. Either just click on it from Konqui, or use the commandline start: "${HOME}/.zAppRun ${HOME}/Desktop/kalzium-new.cmg"

STEP 12

enjoy!

As you can see, modifying klik bundles is pretty easy. If you want help bring the current 4.000+ klik packages and recipes into really good shape, join us at channel #klik on Freenode, or subscribe to the klik@kde.org mailing list.