wingolog

guile-gnome

Released a new version of guile-gnome; release notes sent to the mailing list.

I used some techniques I wrote about previously to generate schemey texinfo from upstream's docbook for C, with a twist: when generating function docs, we load up the wrapset metadata, and use that to determine which functions are actually in the wrapset, what their arguments are, and if they have a generic function associated with them.

Similarly, when documenting GObject classes, we can actually introspect the GObject class from Scheme, loading it up at runtime to query its properties and signals.

The results are pretty good, although sometimes the C conventions show through unnecessarily; we need to go through and provide custom documentation for those procedures using a method similar to that used in guile-cairo.

The generation of docs only occurs manually, because it depends on the location of files on your filesystem, and some libraries not required for the normal build. The upshot is that the tarballs just have texinfo, which has a well-deployed toolchain.

Folks actually visiting the documentation for the first time might wonder why we wrap such an old version of the GNOME platform, 2.16. The reason is that to stabilize the bindings, we needed to focus on a particular GNOME revision. Once the bindings become stable, updating the versions of the wrapped libraries and wrapping the new functions is relatively easy.

One thing that I really wanted to do, and finally have done for this release, is to integrate API regression unit tests into the build. This was done in two parts: apicheck, a tool to describe Schem APIs and API differences, and then integrating apicheck into the various wrapset modules, a process started in the last release. For example, part of the API description for (gnome gtk), as produced by apicheck-generate, looks like this:

(module-api
  (version 1 0)
  ((gnome gtk)
   (uses-interfaces (gnome gw gdk) (gnome gw gtk))
   (typed-exports
     (<guile-gtk-tree-model> class)
     (create-tag
       generic
       (<gtk-text-buffer> <top> . <top>))
     (gtk-stock-id procedure (arity 1 0 #f))
     (gtk-text-buffer-create-tag
       procedure
       (arity 2 0 #t))
     ...))
  ((gnome gw gdk)
   (uses-interfaces (gnome gw generics))
   (typed-exports
     (gdk-atom-name procedure (arity 0 0 #t))
     (gdk-beep procedure (arity 0 0 #t))
     (gdk-cairo-create procedure (arity 1 0 #f))
     (gdk-cairo-rectangle procedure (arity 2 0 #f))
     ...))
  ...)

Pretty simple in the end -- set differences, with specialized calculation on whether two arities or sets of methods on generics are compatible. Anyway I thought this was neat and the wine told me to write about it.

The message that the wine would like me to bring you is this: the next time you start a project, think about how you've been wanting to learn Scheme, and remember that there's a reasonably well-documented, reasonably stable binding for Guile Scheme, and that maybe you should give it a try. Let me know how it goes!