Cluttermm

Cluttermm wraps the Clutter Toolkit, “a software library for creating fast, compelling, portable, and dynamic graphical user interfaces”. Clutter has become an integral part of the GNOME project through its use in the GNOME Shell featured in GNOME 3. As such, I think it’d be a shame to not have high-quality C++ bindings.

Cluttermm had not really had much activity since early last year. With the rate of Clutter development, Cluttermm feel behind quickly. I’m trying to catch up now and as Murray mentioned, I’ve been able to wrap more API and fix a few bugs. So far I’ve got the 1.2 API almost fully wrapped. There are certainly bugs, some of which I’m finding now that I’m actually writing some examples. As I’m very much new to this wrapping business, I want to write a number of examples using the newly wrapped API. Once I’m comfortable that things are in good order, I’ll move onto the 1.4 and then 1.6 APIs.

GNOME System Monitor

GNOME System Monitor (g-s-m) is the default process viewer and system monitor in GNOME. I got involved by responding to the call to port g-s-m to Gtk3. Thanks goes to Openismus for allowing me to spend work time doing the porting (which I’ll blog about in the next couple days). During this process one always finds areas for improvement which spurred my interest in becoming the maintainer.

From what I can tell g-s-m hasn’t been actively developed in well over a year. You can imagine that bugzilla has a lot of suggestions for future tasks. My first order of business will be dealing with neglected patches and responding to bug reports.

So it appears as if I’ve filled all my free time for the foreseeable future. We’ll see how much I can get done between changing diapers and playing with the kids.

Oh, and lastly… patches welcome.

Note: This was my first attempt at packaging anything and the application I’m packaging (ConferenceGoer) is a personal project which is in an unusably-early state. So let’s ignore all that and focus on OBS itself.

What is OBS

The OBS allows a packager to create packages for multiple distributions and architectures using one spec file for RPM packages or one set of debian packaging files for debian packages. For example, in my OpenSUSE OBS repository I’ve built packages for multiple releases of Fedora, Ubuntu, OpenSUSE, Mandriva and Debian for the i586 and x86_64 architectures from one set of package files.

Despite the “OpenSUSE” in the name, the OBS is useful for other distros as well. For example, the MeeGo project has adopted it as its build-service of choice. I’ve used both and will refer to them as the OpenSUSE OBS and MeeGo OBS.

This is not an OBS how-to. See the OBS tutorial for getting started with OBS.

Some notes (in no particular order)

Generated moc_ files in tarball

One of the problems I ran into while packaging ConferenceGoer was that the tarball that is generated from the Makefile (which is generated from qmake), includes moc_* files. As anyone familiar with Qt knows, these are genereted files. The problem that this causes is that moc_* files generated with a newer version of Qt (4.7 in my case) will not always be compatible with older versions of Qt. As older distros do not package the newer version that you may be developing against, this will cause build problems. The easy fix for this is to remove the moc_* files from the tarball. qmake will regenerate these files for you anyway during the build process making them unnecessary.

Interacting with the OBS

There are 2 ways to interact with the OBS. The first way is using the web interface and the other is using the command-line tool (osc). I found that a mix of these worked best. The web interface can be annoying and slow for certian tasks. Triggering a build and uploading new versions of your files takes far too long. You can use the command line tool much like you would any svn client. You make you local changes, commit them with a message, and repeat. The commit will trigger an automatic rebuild. This seems to happen much faster using osc than with the web-interface. In short, use osc when you can and use the web-interface for watching the packages build status.

OpenSUSE OBS downtime

Annoyingly, the OpenSUSE OBS site seems to be unreachable rather often. It’s also rather slow. The MeeGo OBS is fast and seems reliable though. I’m guessing this has to do with the high load on the OpenSUSE OBS. Still it’s annoying.

Moving from the OpenSUSE OBS to the MeeGo OBS

If you ‘ve managed to get everything working in the OpenSUSE OBS, moving to the MeeGo OBS should be simple. For ConferenceGoer I just needed to remove the ifdef’s for all OS’s other than the redhat-based distros. We then need to remove all Qt version info from the package names. For example, qt4 becomes qt and qmake-qt4 becomes just qmake. MeeGo only has Qt4 packages so this distinction is not needed.

Also to note is that getting access to the MeeGo OBS is a manual process. You’ve got to have a meego acount set up and request access on irc.

Font problem with Qt apps in MeeGo.

Once the package was installed on MeeGo (on the nice netbook we were given at the Dublin conference), I found that the fonts looked terrible. This turned out to be a known bug. Seems you can tweak a config file to get it looking OK but hopefully this is now fixed.

Conclusion

Overall I think the OBS is a very nice tool. It’s rather gratifying to be able to build for so many different distro/version combinations with such little effort. The command-line tool is intuitive and works well. I’d like to be able to access the OpenSUSE OBS instants on a more regular basis however.

I plan on building some new cluttermm packages soon to encourage more people to start testing and using it as well as to practice packaging libraries. So keep an eye on my repository.

A Tutorial for Tutorials?
So here we are, we’ve got some nice, simple code examples, some even with tutorial-style documentation. But if you look through the examples you’ll find that the documentation style varies dramatically. Before we go and write too many of these tutorials maybe we need to standardize how we write these. Some issues that arise when writing the tutorials are:

• how do we structure the tutorial? Daniel’s Magic Mirror example incrementally builds up the program while others, including mine, explain the finished program.
• how does one reference the code? Do we use line numbers, show full functions/classes? Do we include unexplained code in the code snippets?
• how do you show a full listing? Do we append a full code listing at the bottom of the tutorial or provide links to files?
• how much should we comment the code? If the code is going to be explained, do we need to repeat the same thing in the code comments?
• and so on…

Some of these have answers. For example, we decided that we should build up the programs incrementally and that referencing line numbers is probably going to be more trouble than it’s worth.

When I was writing my photo-wall tutorial I knew that I was writing it not in isolation but as a larger collection. Thus, I wanted my tutorial to fit in with the other tutorials in the collection. As there was no guide to go by, I poked around the repository to see how others were doing it. I found one I liked and went with it.

The point is that because there is no canonical tutorial or document to go by, we are adding a possible barrier to those wishing to create such tutorials. During the hackfest it was mentioned that we can not motivate people to contribute, we can only demotivate them. Let’s not do that.

For completeness these are my opinions about the above-listed issues.

• structuring the tutorial: Incremental build up is nice for GNOME beginners and that seems to be the target group so let’s go with that.
• referencing the code: No line number referencing. Break the code up into small logical blocks and describe. Blocks need to be small so that one can read the description and see the code without having to scroll up and down repeatedly.
• showing a full listing: Do like the Qt examples do; list all files at the beginning of the tutorial. This gives quick access to folks who don’t need the description.
• commenting the code: Heavily comment the code so that is descriptive outside the context of the tutorial and probably remove the comments when placing segments in the tutorial in order to save space.

Dealing with undocumented code examples

Right now I don’t know that we have a plan for dealing with this so here are my thoughts.

In a perfect world we are going to have a tutorial written for each example in each of the core programming languages. As perfection is rather boring, lets think about the alternatives.

I think in this case we should simply look at the Qt examples. They either have a tutorial-like description or they don’t. The one’s that do have an asterisks, those without don’t.

Regardless of whether the coder is willing or able to write an accompanying tutorial, we should promote getting as many code examples in as many core languages. In fact some example may be too large to expect a tutorial. Take a look at the Qt Network torrent example for one instance of this being the case. Looking at that example you’ll see that even though there is no tutorial, a file listing and description is available. If we were to standardize on having a file listing and functional description of the example at the top of each tutorial we could just copy the description and list the files for each newly added example port. Of course, hopefully someone would eventually get around to writing a tutorial as well.

Relating reference documentation with examples

One of the nice things about the Qt reference documentation is that it often references examples in the See also section. With one click your sent to an example that’s probably more complete than the small snippets you usually find in the API reference. Looking at the QTcpSocket class you’ll find 6 referenced examples. Some have documentation while some are just commented code. Maybe Shaun has something up his sleeve for something like this using Mallard.

Closing words
Basically, I would like to see a consistent, wide-ranging, integrated and ever growing set of examples and tutorials to help developers get started with developing with GNOME technologies. I think the Hackfest was a great start to getting us there. The documentation team has done a great job laying the foundations and providing infrastructure for getting us where we want to be with GNOME 3 regarding developer docs. We just need to finish ironing out a few things before we are quite there.

Merkmal 0.1.0 screenshot

Currently the functionality is on par with that of GMemory. It requires at least cluttermm 1.1.2, clutter-gtkmm 0.9.6.

Here is a video of Merkmal in action. As you should see, basic game play is working but there are tons of things to be added to make the game more interesting. I listed some of those in the GMemory post.

Merkmal 0.1.0 screencast from Chris Kuehl on Vimeo.

Cluttermm

Now that I’ve ported the game to C++, adding these features should be much easier. However, there are some issues that I’ve been running into. I seem to be among the first (if not the only) consumer of cluttermm at the moment. This has of course meant that I’ve been running into bugs here and there. I’ve fixed the ones I’ve run into. I’ve also started filing bugs for missing api. For example, the new layout classes and animation framework have yet to be wrapped. I’ve filed some bugs for the ones that I’d most like to use.

GNOME Bindings

Having written the same application in both gtk+ and gtkmm, I don’t see why one would not use one of the bindings to write user apps. One of the beauties of GNOME is that there are so many high-quality bindings available. Bindings are a top priority for the project and it shows. With the introspection work that is going on, the situation will only get better.

For the last couple days I’ve been tracking down some reference counting problems in cluttermm. In the course of this I’ve been working on figuring out how GDB can help me do this. Here is what I’ve come up with. If you have improvements please let me know.

Watching the reference count variable

The first small obstacle is that pretty much all objects are wrapped in a RefPtr, glibmm‘s reference-counting shared smartpointers. This is a good thing and gdb makes accessing the underlying C++ object pretty painless. The following command demonstrates this.

p alpha.pCppObject_


For this example I’m using the alpha variable of type Glib::RefPtr<Clutter::Alpha>. In this command we used the fact that gdb gives you access to any member of a class, whether public or private. You should have gotten output similar to the following.

$1 = (Clutter::Alpha *) 0x9cfe40

Now the interesting part. We want to detect any changes in the ref_count variable. To do this we need to watch the ref_count field. The following command does this.

watch alpha.pCppObject_->gobject_->ref_count

To make this a bit more convenient, I’ve used the gdb define command to create a shortcut. Here is an example session.

(gdb) define watchRefCnt
Type commands for definition of "watchRefCnt".
End with a line saying just "end".
>watch ($arg0).pCppObject_->gobject_->ref_count
>end

Now you just need to use the shortcut like this.

watchRefCnt alpha

Which should give you a confirmation similar to the following.

Hardware watchpoint 2: (alpha).pCppObject_->gobject_->ref_count

The obvious thing to do next is to place this command in a .gdbinit file so that it can be pulled in automatically.

Breaking on last unreference

One of things I was most interested in catching was when the g_object_unref function was called with the condition that the _object pointer was equal to a certian pointer and the ref_count variable == 1. This would indicate that the object is ready to be disposed. To do this we first need to get the address of the underlying GObject like this.

(gdb) p alpha.pCppObject_->gobject_
$3 = (GObject *) 0x9c91e0

You now have a convenience variable, $3, which you can use in the conditions. You then need to set a breakpoint on g_object_unref and set the conditions like this.

b g_object_unref
cond 4 _object==$3&&((GObject*)$3)->ref_count==1

This, of course, would also be nice as a custom command. I’ll leave that as an exercise for the reader.

Future explorations

I forsee future blog entries along these lines so stay tuned. There are quite a few things that interest me in gdb right now.

The Archer project is quickly improving C++ support in gdb. I’ve been using gdb 7.2 for my debugging as I wanted to have a stable debugging platform with all the new C++ enhancements. They have a git repository for those who want the bleeding edge.

Python scripting has been available in gdb since 7.0. I plan on looking into this as a way of streamlining debugging tasks and honing my Python skills which are pretty rusty.

Please let me know if you see any areas for improvement.

Update: See below.

For those not familiar with the game Concentration, or Memory as I grew up knowing it, the basic idea is that one has a number of matching card pairs turned face down. The player(s) then attempt(s) to match these pairs by turning over two cards. If the cards match those two cards remain face up. Otherwise, the cards are returned to the face down position. This is repeated until all cards are face up. Here’s a screencast of GMemory being played.

As you can hopefully see, GMemory is currently in a playable state and it actual quite enjoyable if you’re into these types of games. However, there is a lot more to do to reach what I’d consider a 1.0 release. Besides some code reworking and some known bugs, I’d like to see a score tracker, multi-player mode, card animation and selectable themes.

The game is written in C using GTK+, GObject, Clutter and Cairo. In the course of writing GMemory I ran into a few bugs in clutter-gtk. The first bug was that no events were being received when using the embedded clutter gtk widget. You can find the bug report here. The second major bug I ran into was that once I got a version combination that gave me events, I always received double the events that I expected. This is a known bug and I’ve got a work around in the code for that.

There are also a number of known bugs. As you may have noticed from the screencast, the last card of the last successful match does not get shown before the statistics dialog box pops up. It seems the dialog blocks the drawing even thought the function to draw the card is called before the call to show the dialog box. Another bug is that once the game is over the playing area does not resize when the window is resized. I’ll tackle this once I’ve reworked the code some.

You can find GMemory’s git repository at Gitorious and the tarball can be had here.

Unfortunately, right now I’m building against the master branches of clutter and clutter-gtk. Expect breakage.

Btw, right now.

Update: After trying this on Ubuntu Lucid, I experienced none of the event-related problems with clutter-gtk. This seems to be Fedora 13 specific. Thus, I’ve removed the workaround for the double event issue and changed the configure.ac file to rely on the clutter and clutter-gtk versions shipped with Ubuntu Lucid. The new tarball is here.

Partially populated prototype board

I’m in charge of building the GUI and integrating the software side of the system. For the GUI I’m using Qt. I’ve used this before and found it pleasant enough although I still run into issues that cause me to waste more time than I’d like. The most important thing for me was that Qt is cross-platform and has great documentation. Having some high-profile applications such as Google Earth and Skype using it makes it easier to “sell” to the other team members as well.

For the WSN we chose Atmel Zigbit modules. These have a ZigBee wireless chip and an ATMEGA128 microcontroller embedded within. This module was chosen because much of the difficult circuitry was taken care of, previous good experiences with AVRs, and the low-cost of the hardware and development tools. Thus far we’ve created custom PCB’s to hold the Zigbit modules, a pair of ultrasonic transducers, and the accompanying circuitry. We are currently testing those so that we can get about 20 boards professionally made.

We’ve got less than a month to finish up and are working feverishly to get everything brought together and integrated. With luck we’ll have a working system in a couple of weeks.

For those who don’t know, Django is a Python web development framework that makes development super fast.

The list in no particular order…

1. Are you generic?
2. Sending E-Mails via Templates
3. Django admin for your PHP app?
4. Hacking FreeComment
5. the difference between ‘blank’ and ‘null’
6. Using Django’s TemplateTags
7. A Django website that took (a lot) more than 20 minutes
8. Forms With Multiple Inline Objects
9. Extending Generic Views
10. Template context processors
11. Custom SQL In Django
12. How Django processes a request
13. Write better template tags
14. Extending the User model
15. Django’s Undocumented contenttype app
16. Django, gzip and WSGI
17. Django for non-programmers
18. Django Templates: The Power of Inheritance
19. Django Templates: An Introduction
20. Setting up Django on Dreamhost
21. Django on Windows HOWTO
22. Django Admin Hack – Fields varying with user permissions
23. Some django gotchas
24. Django Templates are not limited
25. Develop for the Web with Django and Python
26. An AJAX ComboBox Widget for Django
27. Using Django’s Free Comments
28. MochiKit and Django
29. RSS made stupidly simple
30. Installing Django on OSX

Note: keep an eye out at Django’s community page for new tutorials and articles.

Related Links

• Official Documentation
• Web Development for Perfectionists with Deadlines (VIDEO)
• Django-friendly web hosts
• Sites using Django

If you have an additional tutorial, put it in the comments.

digg story

Currently it looks like this…


" set appearance
syn on
colorscheme torte
set vb " visual beep instead of audible beep
set nu

" search behavior
set incsearch


I’ve been googling and adding, googling and adding. I’ve tried to avoid the complicated stuff so far. The vim documentation is great but a little overwhelming at first. Jonathan McPherson has a nice series of articles that gives a really friendly intro to Vim.

I’m mostly doing python programming so if you have any tips please leave a comment.