Vala is designed to allow access to existing C libraries, especially GObject-based libraries, without the need for runtime bindings. Each to be used library requires a Vala API file (.vapi) at compile-time, containing the class and method declarations in Vala syntax. Vala currently comes with experimental bindings for GLib and GTK+. It's planned to provide generated bindings for the full GNOME Platform at a later stage.
To generate bindings for Vala get the source from Vala/Release. Configure vala with "--enable-vapigen" and build the system. You'll find the bindings generator in the vapigen subdirectory.
The binding generation requires several steps:
- generating GObject Introspection GIR file (or a GI file made with vala-gen-introspect)
- generation the VAPI binding from the GIR (or GI) file with vapigen
- tweaking the binding generation with metadata and custom code
Generating the GIR File (GObject Introspection)
The introspection file defines the objects, structures, constants, enumerations and functions in an abstract markup language. Since GLib and GObject follow a well-defined naming convention for object members, functions, etc., it's possible to generate these independent definitions from the source code. .gi or .gir file is then used to generate the .vapi file that defines the vala bindings.
A GIR file can be generated using GObjectIntrospection method.
The traditionnal approach is to use vala-gen-introspect to generate GI files. Bindings are moving away from that method.
A Real-Life Binding Tutorial
Use GObjectIntrospection tools to generate a .gir description file.
Alternatively, you may rely on vala-gen-introspect to generate a .gi file.
Generating the Bindings
To convert the .gir file into a Vala API file use:
$ vapigen --library poppler-glib poppler-glib/poppler-glib.gir
If you are updating an officially maintained vala binding in the source code tree, you can go in the vapi directory and run:
$ ../vapigen/vapigen --library clutter-gtk-1.0 --vapidir=. --metadatadir=packages/clutter-gtk-1.0/ packages/clutter-gtk-1.0/clutter-gtk-1.0.gir or just: $ make clutter-gtk-1.0
Do not forget to include the packages needed by the library. If the library uses GTK+ and GConf, use:
$ vapigen --pkg gtk+-2.0 --pkg gconf-2.0 --library [...]
Otherwise you'll get errors like that, or an incomplete binding:
error: The type name `GLib.tkWidget' could not be found
Tweaking the Bindings Generation
Exclude Files From Parsing
Some header files may be useless for gobject-introspection and can even trigger errors. In this case, add them to poppler-glib/poppler-glib.excludes and gen-introspect will ignore them.
Fix VAPI Generation
Sometimes it is necessary to fix up the generated VAPI file; for instance, vapigen might not identify out or ref parameters, or identify structures that should generally be put on the stack instead of allocated, and passed by reference to methods.
Instead of updating the VAPI file, and keeping it updated with every upstream API change, vapigen output can be tweaked with a .metadata file. For instance, in poppler-glib the poppler_page_get_size function has two out parameters, width and height; in order to create a valid Vala signature in our VAPI file, we need to add these lines inside the poppler-glib.metadata file:
poppler_page_get_size.width is_out="1" poppler_page_get_size.height is_out="1"
Which translates to: "the width parameter of poppler_page_get_size is an out parameter" and "the height parameter of poppler_page_get_size is an out parameter".
Documentation for the .metadata file format can be found on Vala/Manual/GIDL metadata format.
Add Custom Vala Code
Sometimes you need to write extra Vala code like helpers and such. Use poppler-glib-custom.vala and append it to the vapigen params:
$ vapigen --library poppler-glib poppler-glib/poppler-glib.gir poppler-glib/poppler-glib-custom.vala