help--patching for dummies?

  • Anthony

    Hi folks, I apologize if this is a stupid question, but I see a number of very useful patches available for xournal and can not figure out how to apply the patches. One of the patch pages (  linked to an article describing the application of patches but I can't get it to work. One sticking point is that xournal (which I installed through Ubuntu's software center) does not appear to reside in a single folder.

    I'm kinda stumped here and would appreciate any help. I am fairly new to linux but am ready and willing to do as I'm told.


  • Denis Auroux
    Denis Auroux

    STEP 0: figure out which version of the xournal source code the patch is meant to be applied against. Most of the patches on the tracker are for the standard 0.4.5 release; a few older ones are for older versions; a few others are meant to be applied on top of other patches (then it should say).

    STEP 1: download the appropriate version of the source code.
    Version 0.4.5 is at
    Unpack the tar.gz file by running "tar xvzf xournal-0.4.5.tar.gz" in a terminal; this creates a directory called xournal-0.4.5/ containing the code.
    The last stable version (which is 0.4.5 with several bugs fixed) is on the CVS repository; to get it, run the two commands:
    cvs login
    cvs -z3 co -P xournal
    (Patches usually apply best against the standard 0.4.5, not the CVS, but if you can get the patch to work against the CVS version you'll get some useful bugfixes).

    STEP 2: apply the patch. In a terminal, go into the directory where the xournal source code unpacked (e.g. the directory called xournal-0.4.5/ if you unpacked the tar.gz). Run "patch -p1 < the-patch-file.patch". The "-p1" option tells patch to discard 1 level of directory from the filenames specified in the patch file; this is usually the appropriate amount.

    Some of the larger patches are compressed (.gz), in that case "gunzip the-patch-file.patch.gz" first.
    If patch complains that none of the file names can be found in the right place, you should try again with "-p0" or "-p2" instead, since some patches may have been created from an upper or lower level directory of the source code tree.
    If patch complains that the files do not match (line numbers need to be adjusted, and it has had to give up on some of the changes), then most likely the patch was meant for a different version of the source code.  Depending on how serious the issue was, the resulting code might compile or not.

    If you have a partially applied patch due to a mis-manipulation, it's best to unpack the source code again and start again applying the patch against a clean copy. If you are trying to apply several patches in succession, you are likely to get mismatches in the line numbers, since the second patch is most likely not meant to apply against the result of the first one; still, the patch command is fairly smart, so if the patches affect different portions of the source code it'll figure things out and it should work.  In complicated cases, I'm afraid that combining incompatible patches requires programming knowledge and inspection of the source code - for experts only.

    STEP 3: compile the patched source code. In the main xournal source directory, run:

    If configure complains that you are missing dependencies, use your distribution's package manager to install the development packages for gtk+2, libgnomecanvas, poppler, and pango. (In fedora the relevant packages are called gtk2-devel, libgnomecanvas-devel, poppler-glib-devel, and pango-devel; not sure in your distribution).

    If make complains of compilation errors (i.e. aborts with error, instead of just giving warning messages but proceeding anyway): most likely the patch didn't apply cleanly. Check carefully what happened when you ran the "patch" command; if there was too much mismatch when applying the patch, it might not have been applied properly.

    STEP 4: test.
    Go into the src directory, and run "./xournal". Test and see whether it seems to work.
    If it does, you can install your new version of xournal by running, as root, "make install" in the main source code directory. 
    This will install the executable into /usr/local/bin/xournal (as opposed to the standard version of your distribution, which most likely lives in /usr/bin/xournal). If you're confident that the patched version works well, you can start by uninstalling the distribution's copy of xournal in the package manager to reduce the confusion. If later you'd like to get rid of the patched version instead, just delete the file /usr/local/bin/xournal  and the directory /usr/local/share/xournal/

    Note: some of the patches are rather untested, so they might not all be equally reliable. The popular "image" and "autosave" patches have been revised several times, and are in extensive use, so those are presumably among the safest. Those which add a very specific and narrow feature are also usually reliable.

    Good luck!

  • kelly

    Thank you, Denis, for taking the time to write that detailed reply! It was phenomenally helpful.