March 2011

How to write a patch for Octave

Jordi

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/ → src → src/DLD-FUNCTIONS → scripts/, 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!

Making posting easier

Jordi

Dear lazyweb,

How can I make blogging as painless as possible? I’m an Emacs + WordPress user. I wish I could just easily post from Emacs. Right now, I still use the WordPress admin website for posting, and although of course it’s not hard to do it this way, it’s awkward to have to log in and do a few administrative tasks before I can post. I tried org2blog, but I don’t like it too much because it was almost as much as work, plus I had a hard time getting org-mode to not try to be more clever than me and no write its own HTML. Right now, the way I feel most comfortable writing in Emacs is in html-mode. I like writing my own HTML. It’s easy enough that I don’t need any pretty interface to it; plain HTML is simple enough.

I really need to lower the activation energy to blogging to almost zero. Of course, that alone might not make me blog more often, but any amount of nontrivial activation energy will slow me down. I may end up writing my own Emacs solution if I don’t find one, but perhaps there’s an easy method out there I’ve missed.

Earning my wings

Jordi

I forgot when it happened, but it was sometime in late January or February that I was finally given push access to the Octave repositories, plus being a manager for Octave items at the Savannah website where it’s hosted. This means I have the privilege to commit my changes to Octave code on my own without needing to ask someone to push them for me, plus I can also handle bug reports to Octave on my own. In addition to that (bring it on, spammers!) I also now have an @octave.org mailing address.

This is a pretty big deal for me. I had been dreaming of being a formal member of the Octave dev team, and I’m really glad it’s finally happened.

At the same time, I wanted to get this distinction because I had obviously earned it… but what actually happened is that I obliquely requested it and head honcho jwe responded to it.

I’m a junior Octave dev, and I expect to be one for a while until I get to feel more comfortable with the code base. This means that I still need to be very careful with what I push, and I should consult publicly on the mailing list if my patches are acceptable before I push them.

So what have I done so far with my shiny new Octave badge? So far as I write this, not much only 8 changesets, of which 6 are documentation fixes, one was a minor m-script fix for imshow, and the last fix as I write this that looks like a minor thing, but took I would say around 30 hours of debugging to find. The Nikolai Tesla fable comes to mind.

I have done other things that don’t show up in the hg log. I try to help as much as I can in the mailing lists and in the #octave channel in Freenode. I’ve been trying to help triaging bug reports in Savannah. I’ve revived work on Agora a little. A friend has lent me hosting for it! Snippets are now fully functional as far as I’m concerned. I even created a better Octave syntax highlighter for Pygments, although I’m still waiting for the official Pygments maintainer to pull my patches. It really does work, although I gotta fiddle around with the setup in my shiny new webhost to make it work.

I’m going to keep working in the immediate future on the sparse matrix bugs I’ve been looking at. Squashing #32747 was a lot of fun, and it forced me to finally use a good gdb setup, plus learn more about gdb itself. Wow. What an awesome debugger.

And as I keep working on Octave, perhaps I’ll feel more justified for the Octave badge that has been handed to me, feel like I actually earned it, not that I just asked for it and jwe is just a generous guy.