How to write a patch for Octave

Often people will find ways to improve Octave’s source and provide a patch, but in a way that is slightly inconvenient to analyse and apply. I will now present instructions for creating a patch for Octave in a manner that is easiest for core Octave developers to apply. In what follows, I assume that you have already managed to install Mercurial, that you’re using some sort of shell (probably even Windows), and that hg is already in your shell’s PATH.

First, you should work with an hg clone of the repository:

hg clone http://www.octave.org/hg/octave
cd octave

Once you’re in there, you probably would want to build Octave so you can test your patch. On a Unix-like system, assuming you’ve installed all the dependencies (and that’s a big assumption, because Octave dependencies can be difficult to track down), you should run autogen.sh in the hg clone before you follow the general build instructions.

Then you can proceed to modify Octave sources however you see fit. You can run the hg st command to see which files you’ve modified and hg diff to get a detailed diff of your changes which will eventually become your patch. I personally find the hg colour extension to be a very nice visual aid for these two commands. You should also try to build Octave again with your changes as a minimum sanity check that your patch is good.

A word on building when patching Octave: the deeper in the build dependencies you patch, the longer you’ll spend rebuilding Octave. So, for example, liboctave depends on libcruft, and liboctinterp (most of the stuff under src/) depends on liboctave, so if you touch a file in libcruft, it’s very likely that you’ll have to rebuild liboctave and liboctinterp. The rough depth of things that can be patched by their directory locations is this: libcruft/liboctave/srcsrc/DLD-FUNCTIONSscripts/, in fact, for scripts, you almost never need to rebuild Octave when patching stuff there (unless you want to rebuild the documentation); but sometimes you do need to restart Octave when testing.

Once you think your patch is in good shape, and you’ve written some tests for it (look for assert commands near the bottom of source files to see how tests are written) you should commit it so that it becomes a (semi-)permanent part of your local hg clone. If it’s your first time using Mercurial, you should create an .hgrc on a Unix-like system or Mercurial.ini in Windows and put in there lines to identify you, like so:

[ui]
username = Your Real Name <some@email.com>

Now do

hg ci
hg export . -o my_fix.patch

to record your change. When you type the first command, hg should open an editor where you will now have to write a commit message. Now your change has become part of your local repository, and the second command has exported your patch to a file named my_fix.patch in a format that is easy for others to apply. Now just send that patch to the Octave patch tracker or attach it to an open bug report, and we’ll take care of it!

Leave a Reply

Your email address will not be published. Required fields are marked *