As part of my Openismus training, I was recently tasked with packaging a Qt application using the OpenSUSE Build Service (OBS). Here I’ll try to note my first impressions as well as offer some solutions to problems I encountered.

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.

I’m a bit late in the game regarding blogging about the GNOME Developer Documentation and Tools Hackfest that we hosted at the Openismus Berlin office a couple weeks ago. There have been a number of good posts made summarizing what we talked about and worked on. In this post, rather than providing another summary, I’d like to share my thoughts about how we can get the most out of the demos (examples, tutorials… whatever) we started during the hackfest. Some of what I’m going to talk about was discussed at the hackfest, but much was not. Also, be warned that this will have quite a few references to Qt documentation practices.

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.

In order to graduate from the Engineering program at San Diego State University, each student needs to complete a senior design project with a team of between 6 to 10 students. The group that I’m apart of is working on building a system to localize nodes in a wireless sensor network (WSN). We do this by using signal strength and, when nodes are in line of sight of each other, ultrasonic transducers to measure the time difference of the received ultrasonic signal and the radio signal. This is a problem that has been tackled many times and I’m pretty sure we won’t be able to come up with anything novel in the short time we have, but the task of building the working system is what is important.

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.