Documentation for GJS

In the last days of January I attended the GNOME Developer Experience hackfest, remotely. This was a first for me since I have not attended a hackfest remotely before. It was also a first for the hackfest, that three remote participants signed up, and we had a discussion on desktop-devel-list as to how that should work.

My main project for the three days was to show people the documentation browser I’ve been working on. This got started a while after last year’s edition of the DX hackfest, which I didn’t attend, but the project was born out of a discussion with some people who were there and talked about it last year.

Some background: You can write applications for the GNOME desktop in many different programming languages, including C, Python, Javascript, and Vala; this is made possible through a piece of software called GObject Introspection, which is a bridge between C libraries and many other programming languages. At (yet another) DX hackfest, the one in 2013, GNOME decided to promote Javascript (and the GJS interpreter, which is basically the Javascript engine from Firefox 24 with GObject Introspection on top) as its preferred platform for application development. Not the exclusive platform, you can still develop apps in Python if you want, but there would be a focus on getting new developers started in Javascript, with tutorials and documentation.

Sadly, since then, we haven’t had good API documentation for developing apps in GJS. The best story we had for a long time was to tell people to refer to the C, Python, or Vala API references and mentally make the transition to Javascript, a process I’ve compared to playing a song on the guitar using chord sheets from the internet, but mentally transposing them to a different key as you go along. At one point, Giovanni Campagna generated some static Javascript documentation and hosted it on his website. This eventually got out of date.

So, this was the problem I was hoping to solve. After a short-lived attempt to write my own web app using Semantic UI (a technology I’d still like to check out someday!) I figured, why bother when there was something that would fit the bill perfectly well: DevDocs, an open-source documentation browser that combines all kinds of documentation from elsewhere (mostly web development technologies) and presents them in a unified fashion with a useful but simple and elegant web app.

In the final quarter of 2015 I worked on this on and off, adding some code to the documentation generator g-ir-doc-tool to make its output suitable for DevDocs to input, and some code to a forked version of DevDocs to import the GNOME documentation and make nice metadata and sidebar entries.

Here it is in action

At the hackfest I gave a demo (at 6:30 AM, because of the timezone difference!) to the other people there who were working on developer documentation. I got some good feedback from the people who were listening, discussed some of the shortcomings, and we discussed Mathieu Duponchelle’s new documentation tool, Hotdoc, as well. One good outcome was that the GNOME Developer Center now links to my instance of DevDocs (noting that it’s “experimental”.)

To talk about one of the limitations that we discussed at the hackfest: The approach I chose generates all the documentation from one file, the “GIR file,” which is the same approach that g-ir-doc-tool has always taken. This is nice because it’s self-contained, but also incomplete: API references often include separate pages not connected to any API in particular, such as this one. I think using Hotdoc will help overcome this limitation, since Hotdoc is made for combining these sorts of things. I’m also happy not to work with g-ir-doc-tool since all the stuff I added to it was basically bolted on the side, not really useful for anything else, and therefore not likely to be accepted upstream.

I’m now hosting an instance of the GNOME Javascript API documentation on my modified version of DevDocs: try it out at http://docs.ptomato.name:9292/.

During the hackfest I also collaborated with Philip Withnall on some autoconf macros for GJS and GObject Introspection, which I’ll talk about in a following post…

Some of the other stuff that people worked on is summarized on Philip W.’s blog.

Geek tip: Malloc debugging on OSX

I’ve been trying to chase down an annoying bug that I suspected to be a case of using uninitialized memory. The problem is, it only shows up about 1 in 30 times (I was lucky to notice it in the first place), and never in a debugger.

Fortunately I found that there’s a library on OSX that tweaks malloc() to help you debug:

DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib MallocPreScribble=1 ./myprogram

Or, to do this in LLDB, since due to System Integrity Protection, your linker-affecting environment variables get wiped when you execute a system program:

lldb -- ./myprogram
env DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib
env MallocPreScribble=1
run

This triggered the bug every time, both inside and outside the debugger.

For more information about what you can do with libgmalloc, see this documentation. It only tells how to use that facility in Xcode, though, so the above instructions should help if you’re on the command line.