Daniel Espinosa

When you have developed a library using Vala programing language, or any other language, you should generate documentation about its API. You can use Valadoc to generate Documentation for Vala based libraries.

GXml, is a Vala project using valadoc command line tool and Autotools, to automatically generate its documentation. As you can see in this link, Vala documentation provides a very convenient graph about object’s hierarchy; properties and methods provided by current class; and all inherited properties and methods from base classes and interfaces it implements.

But how can I add this feature to my own Vala project? Well, you can use Autotools to call valadoc, generate your documentation and then install in the system, to be available for GNOME DevHelp to show up locally and, at the same time, in GNOME Builder integrated help facility.

While I haven’t, yet, found the way to generate C API documentation using valadoc, from my Vala API one, I’ll show you, in a second part, how you can do it, but not before I have figured out how to create a mk file you can use in your project for an out-of-the-box procedure.

I’ve recently finished a makefile to make easy to create GTK+ applications as well as GTK+ libraries using Vala programing language.

While Vala allows you to use UI files generated by Glade as templates to create custom widgets, is recommended you add these ui files as resources to your application or library’s binaries, in order to build your User Interface. While Vala custom widgets are out of scope of this post, we will talk about how I’ve created a makefile to be imported into your Makefile.am for GTK+ resources embedding.

vala_gtk.mk, is a file to be included in your Makefile.am, after you include vala.mk or valalib.mk, depending on your project. Use the first for  GKT+ applications; the last when creating UI libraries.

Once this pre-requisites are met, you are ready to set up a GTK+ application, because vala_gtk.mk, adds to your VALAFLAGS the gtk+-3.0 package, but the most important, it adds a reference to the XML file with all your resources to be embedded into your application or library binaries. This is required in order to Vala’s compiler to find all your UI files for widgets templates or simple build using GtkBuilder; also images, and any other kind of file can be added as resource, like licenses, texts, and others.

glib-compile-resources is used to generate a C source code file and its header, for all resources, to compiled with your project’s target. Once it is compiled this way, all your resources will be available using GResource or any other function using GLib resources.

For GNOME Builder, I’ll send a patch for it to add an Autotools template to create both applications and libraries for GTK+ written in Vala with resource compilation support.

May be in the near feature, this file could be splitted to include just resource generation as resources.mk, in order to use it when GTK+ is not used at all, but this is another history and a good reason to write some thing about.

Recently blogged  about make distcheck and Vala libraries and how you can use GNOME Builder for Vala development, both are important for Vala developers expecting to increase its productivity.

As all you know Autotools is hard to learn, or at least takes some time to produce custome build rules. While Vala in Autotools have been there for a while it is buggy, making hard to get a out-of-the-box, clean and easy build system.

Now as part of my work to fix Bug #766621, I was able to produce a clean Makefile.am, with all passing make distcheck. I’ve added some utility makefiles to build libraries with GObject Introspection support out-of-the-box.

Just checkout my test bed project at GitHub, in order to see how simple could be.

GNOME Builder has a template system, really easy to update, and now it will have, as soon as may work on Bug #766621 is accepted to commit, out-of-the-box Vala libraries templates for your pleasure.

GNOME Builder have support to create Vala libraries skeleton using templates, but can’t produce any useful library yet. You can see bugs 766621, 768541, 768740, 768540 and 766621, for missing features.

While my patches to improve Builder’s template system work, they can be used when you try to run make distcheck, due to current Vala support implementation of Automake. See bug GNU bug #13002.

But now I on stub! No one have checked 13002, Christian Hergert  have no time to review my patches, well not all of them and Builder is a big project, and personally I now I’m not good enough on Autotools to create a clean implementation, but with Christian feedback I’ve get my best and will write better cleaner implementation.

Is better to fix Automake Vala implementation, in order to produce clean and easy to write Makefile.am for Vala projects, less code and less work around. All implementation should pass both make check and make distcheck.

If no response found, then may I need to write Autotools macros and mk files to be imported to your Makefile.am file in order to provide a clean implementation and easy to use, only after Autotools is fixed.

This will me help too, to write my own libraries more easy. Now I have to fix manually and find the current configuration for each one, most of the time based on GXml, but is a time consuming task, requires Autotools knowlage and should be fixed each time you added new stuff. I really like libgee’s Makefile.am, which is clean and just works, but all the time I start to use it as template, it just not work for me. Then I think I need to create my own and push it to Builder to produce good templates for all of you too.

Now while fixing compilation of GXml’s implementation of DOM4, I found lot of API incompatibilities between existing generic GXml API using Gee collections and DOM4 interfaces.

In some cases when API incompatibilities comes from methods names, no problem, because just instruct Valac to override the correct interface, but properties is another beast.

Properties should be same type between interfaces if you want to implement one property with the same name in two or more interfaces.

While I see lot of advantages to use DOM4 API, because it is well documented in its specification, I’m using it when conflicts appear, modifying existing one in GXml.

Doing so and while GXml is perfectly usable in many cases, like embedded in Python code for web pages, DOM4’s API is more binding friendly than Vala’s generic one, while the last is powerful and easy to use in Vala code.

All this work will be present in upcoming GXml 0.11 version, for you to test. Next versions of 0.11.x series will be to fix DOM4 implementations by adding Unit Tests.

Today I’ve finished to prototype most DOM4 interfaces implementation on GNode series.

I’m starting to fix building and some issues here and there. All my work is in my local repository jet, just want to provide a buildable commit to you, releasing a 0.11.0 development release.

DOM4 makes some changes, making old DOM implementation in GXml, well, obsolete. Once I’ve finished to add all Unit Test and passing, I think I can promote a new release 0.12.

May be at 0.14 release window and with user’s feedback on DOM4 implementation, I can remove old DOM implementation and all xNode classes, by cleaner, faster and more maintainable GNode classes.

There are lot of interfaces in DOM4 I have no implementations in GXml, just leave there to implement later. I hope we can have a clean interfaces before to implement in order to avoid API changes, but any way, this is why we are at 0.x release series.

Vala programing language is, let say, misunderstood most of the time. May this explain, why there are few support for IDEs, like GNOME Builder, at least at beginning.

In 3.20.4, GNOME Builder has improved and stabilized its support for Vala development, proven to be stable enough for daily usage. Even I started to use it for GXml upstream development. But it was a little difficult, because I want to stay in a stable long term supported OS, like Debian 8.

Debian 8, has been discarded by GNOME wiki, to install and develop using jhbuild, making hard for me to develop upstream. In order to solve this, I started to test Builder from xdg-app and nightly builds, because, it suppose to be in sync with master (upstream) versions of basic Platform, for upcoming 3.22. While I rather happy with Builder running this way, you need some extra configuration to develop any Vala project under xdg-app sanboxed environment.

While Vala 0.32 is available in org.gnome.Sdk 3.20, the one I’m using to develop GXml, no libgee is installed and you can’t simple compile and install it, because in the Builder sanboxed environment, /usr is mounted read-only. So I first:

1. Get libgee sources
2. Set “Installation Prefix” to /home/yourusername/.local
3. Disable instrospection (–disable-introspection), by setting “Configure Options”
4. Use “Host operating system”

This will make the trick to compile and install libgee in your home directory. Libgee doesn’t requires other dependencies. But for GXml, we need a few more work, because you should setup it to find pc files for libgee and more important, to find its VAPI file.

To configure GXml on Builder, in sanboxed environment:

1. Get sources
2. Set “Installation Prefix” to /home/yourusername/.local
3. Disable instrospection (–disable-introspection), by setting “Configure Options”
4. Use “Host operating system”
5. Set “Environment” variables for VALAFLAGS and PKG_CONFIG_PATH
6. In your Makefile.am make sure you add –vapidir=/home/yourusername/.local/share/vala-0.32/vapi to your Vala compile flags.

VALAFLAGS is useful for code completion in Builder, add most of your project Vala flags. PKG_CONFIG_PATH should be set to /home/yourusername/.local/lib/pkgconfig in order to find pc files of your locally installed dependencies.

You’ll find Builder complaint by reporting some warnings, most of them coming from libgee usage.

Building your Vala project in Builder, is no jet really integrated, because most errors are shown in terminal “Build Output”, but not in build messages, no other than the libgee ones. Fortunately, you have color output from valac, making more easy to find errors and warnings.

Most of you may will use a distribution, to use Builder and jhbuild, making easy to develop upstream. I can’t do that, because some other activities requires me to have an stable system, avoid interruptions because my unpaid contributions to GNOME.

Using W3C specifications for DOM 4, I’ve managed to copy & paste its interfaces, then with few adoptions are now GObject interfaces thanks to Vala.

Now I’m implementing them using GNode classes, this is in order to deprecate xNode classes, while we provide a more modern API.

The progress are so straightforward, at least for now, with few code. I’ll try to avoid any API break this time, unless it is impossible to implement DOM4 API.

While actual API is powerful enough to do most DOM4, there are missing or just useful API we can take advantage of.

For example, DOM4 provides events API, witch we can implement provide using GObject signals, but even so I’ll try to do my best to keep the DOM’s one.

I will implement step by step each interfaces functionality, on existing classes; may I leave events for a second try. I need to implement all basic interfaces, before I can push to repository.

Even so, all API interfaces are in place, and may will suffer some Vala adaptions, but not too much. If I can’t implement them I’ll hide them from public API, until they are implemented.