libgcal 0.9.4 released

June 11, 2010 at 2:16 am 19 comments

Sweet! But what the heck is this ‘libgcal’ thingie? For starts, the name can and is misleading, since it should read as ‘library for google calendar’ but in reality, it implements both Contacts and Calendar google data protocol.

When I got it started, back in February of 2008, it was supposed to implement just calendar, but later on I realized that adding contact support only required +25% of code on it (thanks for well modular software design). Back then,  there was no other good alternative for any C/C++ programmer that would fit the following requirements:
  • easy to use;
  • well documented;
  • few dependencies;

So, I got my library started! After studying the google data protocol 1.0 (at the time) for while, I realized that using XPath would make my life way easier than say, browsing through the DOM tree searching for the attributes and tags that I wanted.

At that time, Qt didn’t have support for XPath (it only started with 4.5), so I went with libxml. For networking I used libcurl, which is fast/reliable and has great documentation (and a very welcoming community, from time to time I asked for help and always got answers for my questions).

From the very early beginning, I set a high quality standard in the development (after all, parsing XML in C is already prone to errors by itself) and followed a TDD (Test Driven Development) approach where *first* I write the test and *later* write the implementation of functions. Having an average of test coverage of 80% helped a lot when google released version 2.0 of the protocol (back in december 2008) and now more recently, version 3.0 of Contact’s protocol. I did the porting from version 1.0 to version 2.0 of the protocol in few hours, mostly because I could detect any regression by simply running the test suites.

IIRC in about 4 months I got the basic (authenticate, retrieve, add/edit/delete, query for updates) done and the library even got featured in the google official blog (that was surprising to say the least)!

So, the library was ‘done’, let’s put it to good use. I decided to integrate it with Opensync (it was rather cool, I got google contacts and calendar sync for my Nokia N95 over bluetooth working 6 months before google decided to release a syncml server for S60 devices). You can see a pre-jurassic video of this here. I think up until now libsyncml is a pretty good syncml implementation, it is just a shame that there is not a good UI bounded to it.

But I needed a good UI and the alternative seemed to write an akonadi resource. In just 3 weeks I got contacts working, while also implementing missing features in libgcal to make possible to do fast-sync (i.e. when you download only what has changed in server side). Contacts resource was done in just 3 days (I think this is clearly a good signal that akonadi API is well designed).

Developing the akonadi resources gave the opportunity to better understand how KDE community works and also to start running KDE trunk as my default desktop (after all, pre-packaged software are for sissies and developers should eat their own dog food).

So, why I wrote all this story? Well, to help to understand some numbers:
  • 10 months ……. since last release (0.9.3)
  • 6 distros ………. pre-packages libgcal (Debian, Ubuntu, OpenSuse, Gentoo, Mandriva, FreeBSD) and counting
  • 2326 downloads .. directly from libgcal project website (hey, this is a source code tarball of a library and not some porn!)
  • 20681 views …… reported by google analytics in a 1 year period
  • 3000 ms……… the lag to ping google servers in a bad day in Manaus/Amazonas (yeah, truly it is unbeliavable how I managed to write a *networking* library in this enviroment but what doesn’t kill you makes you stronger)
  • 6762 LOC ……. lines of C code (34% are unit tests)
  • 76.5 % ……… current *real* code coverage (here I slipped a bit, it used to be 80%)
  • 10th ……….. of most wanted KDE features

So, what this new release brings? For start, support for multiple email addresses, patch by Stefano Avallone (Andre Loureiro helped to fix the unit test) and migration to Google Contacts API 3.0. Next, support for structured names and several other fields (nickname, blog, etc) by Holger Kral. I think currently only IM field is missing from the library (but is quite easy to implement that).

You can have access to both the library and the akonadi resource in libgcal website. The only issue is that is required to purge your akonadi resource and do a slow-sync again because the ETags and urls of contacts have changed thanks to migration to version 3.0 of protocol.

So, what is missing in the library for a 1.0 release? The following features:
  • support multiple calendars (easy to do, is a matter of using another URL as base to do the network operations)
  • support recurrent events in calendar (thanks to the fact that google uses an invalid iCal to represent it, it gets tricky to implement it since a iCal parser would fail to read this data). An idea to implement this would be to ‘convert’ the invalid iCal from google to a valid one and do the opposite when sending data back to the google server.
  • batch commit (nice to have, but not a hard requirement)
  • port/rewrite it all to Qt (seriously, this was actually started already: Here I’m somewhat unsure, if Qt has support for the XPath/XQuery in Symbian (it seems that RTTI is not supported in this OS).

Oh well… so, why not give it a try? If you got the skills, go on and download the sources (please check the README and INSTALL files) and feel free to report to me how things worked (or not…).

If you are a normal user, I think in a couple of weeks it should get packaged for your loved distro.


Entry filed under: akonadi, gdata, linux.

6 months of plasma in 10 minutes libgcal 0.9.5 plus a video

19 Comments Add your own

  • 1. jensp  |  June 11, 2010 at 3:49 am

    Thanks a ton for your hard work on libgcal, it’s really appreciated!

  • 2. Thilo Bangert  |  June 11, 2010 at 9:07 am


    thanks for the release.
    The testsuite fails with many errors when I run it over here.

    do you have any idea how to fix this?

    kind regards

    • 3. jensp  |  June 11, 2010 at 10:25 am

      I already filed a bug for that btw:

      Are you going to add it to gentoo? I was going to try to get it to sunrise, but as you are a gentoo dev I guess I can save myself the hassle?

      • 4. Thilo Bangert  |  June 11, 2010 at 10:58 am

        The ebuild will be in portage soon… no need to add it to sunrise.

  • 5. savago  |  June 11, 2010 at 10:24 am


    It is a good programming practice to actually build and run the code in another directory than the sources.

    I designed the utests of libgcal to fail if you run it in another place than a directory inside of the place where you extracted the tarball.

    From the README:
    ps4: Currently I have being using cmake as the official development buildsystem
    (just run: mkdir build; cd build; cmake ..; make)

    What happens when following this instructions?

    Best regards


    • 6. jensp  |  June 11, 2010 at 10:30 am

      Looking at the past the tests are run in libgcal-0.9.4_build, the source is in libgcal-0.9.4.

      • 7. savago  |  June 11, 2010 at 10:36 am

        Is the directory structure:

        ….. build




        It will only work correctly in the first case.

        Just run: mkdir build; cd build; cmake ..; make
        Have a look here:

        The most important tests are the userapi (which stresses the functions used by the akonadi resource):
        Running suite(s): userapi
        100%: Checks: 11, Failures: 0, Errors: 0

        In the core module, there are tests that will only work if they are the first to be executed in a specific day (and considering the timezones).

        In the XML module (XML api, where there is not a need for using gcal_calendar_t and gcal_contact_t) there is indeed a regression, but it will not affect at all the akonadi resources.

        While I’m at it, it is important to note that libgcal depends indirectly on ca-certificates, or authentication with google will fail.


  • 8. Thilo Bangert  |  June 11, 2010 at 11:05 am

    okay – so the build dir structure is to blame for the build failures. any chance of making the tests work for arbitrary build dir structures?

    ie. make it work for
    libgcal-0.9.4 <- sources
    libgcal-0.9.4_build <- build dir


    • 9. savago  |  June 11, 2010 at 11:33 am

      This is not a priority at all, because the unit tests are a development tool (and don’t affect at all the life of users).

      In reality, the only dependency related to the path is being able to load some test XML and image files from ‘data’ directory. Anyone willing to send a clean patch is welcomed, please just remember to read this articles before getting started:

      I must assume that in next release I can count in Geento as another distro packaging libgcal?

      Best regards


  • 10. mutlu  |  June 11, 2010 at 11:18 am

    Awesome work! Thank you so much.

  • 11. milton  |  June 11, 2010 at 2:45 pm

    Great work!

    I’m wondering if there would be any plan (or need at all) to support Yahoo! API’s now that it has closed an agreement with Nokia.

    • 12. savago  |  June 11, 2010 at 3:32 pm


      I think about 1 year ago I checked the contacts data protocol for Yahoo and it seemed pretty straight forward.

      And opposed to the Ovi, it has some public available documentation.

      Who knowns? Maybe this could be a nice new feature in libgcal.

      Best regards


  • 13. mck182  |  June 12, 2010 at 2:26 pm


    first of all thanks for this awesome work!

    I just installed KDE 4.5.85 (beta2) and the akonadi part of your project doesn’t seem to work =/ Everything compiled OK, but when I try to add a new ressource in Akonadi, nothing happens. If I close & reopen the configuration window of Akonadi, I can see, that the Google ressources (either cal or contacts) are added to the list, but no way to configure them for login info etc. If I click the “Edit..” button in Akonadi config window, nothing happens, also no output on console.

    Any idea what may be wrong? I’m on Fedora 13 x86_64.

    Thanks, Marty

    • 14. savago  |  June 12, 2010 at 6:42 pm

      Do you have KWallet configured?



      • 15. mck182  |  June 12, 2010 at 11:22 pm

        Yeah I have and I’m using it quite often with no problems there. I understand, that right after adding the Google resource to the Akonadi config tool, it should ask for password, right? This doesn’t happen for me at all. Also the resource is not added, it seems like nothing had happened.

        I’d like to help pinpoint this problem, so if there’s anything I can do, just let me know 😉


      • 16. savago  |  June 16, 2010 at 1:52 pm


        Try to:
        a) remove the resource (using akonadiconsole or in system settings)
        b) use kwallet manager and remove the user/password (it will be associated with gdata resource)
        c) restart akonadi server (akonadictl restart)
        d) add again the gdata resources



      • 17. mck182  |  June 18, 2010 at 10:55 pm

        It seems that the problem was somehow related to MySQL database. I found out, that akonadi starts with fatal error everytime. I searched little bit and found a thread over at where someone suggests to use system mysql instance. So that’s what I did and it is working as it’s supposed.

        Thanks a lot for this piece 🙂

  • 18. Bastien  |  June 12, 2010 at 4:01 pm

    libgdata, which depends on libxml2 and libsoup, already implements most of the gdata protocol. That means Contacts and Calendar as you’ve implemented, but also YouTube, Picasa and Google Docs support.

    • 19. savago  |  June 12, 2010 at 6:39 pm

      Dear Bastien

      libgdata was started by a student in early beginning of 2009, almost 1 year later than libgcal (at the time, someone even commented at the author’s blog about the duplication of work, since libgcal was already available at time).

      I came to known about it only in 05-2009 (when both akonadi resources were already written using libgcal) and even contacted libgdata author (Philiph Withnall) to propose joint work.

      It was not possible to do it, for the following reasons:

      a) libgdata depends heavilly in latest features of GObject and glibs (which is a unnecessary weight for KDE). This could be workarounded, but Gnome developers where not willing to switch from libsoup to libcurl for networking or to make the gobject dependency a compile time flag.

      b) I used a XPath approach for XML parsing, while libgdata depends on DOM tree browsing. This means more C code to do the same job.

      c) I believe that having heavy coverage in unit tests for a library was a hard requirement, instead of writing new features.

      d) Licensing issues: libgcal (BSD), libgdata (LGPL or GPL, IIRC).




Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Trackback this post  |  Subscribe to the comments via RSS Feed


June 2010
« May   Jul »

Most Recent Posts

%d bloggers like this: