Documentation for Contributors to Vala¶

Compiler Guide

Vala follows a collaborative, open source development model. The following guidelines are here to help if you want to contribute back to the project.

Building from Source¶

See the ‘Building Vala’ section of the README.md file in Vala’s source repository.

Development Process¶

Submitting Bug Reports¶

Vala uses GNOME’s GitLab to track issues.

Submitting Patches¶

Patches should be submitted through Vala’s GNOME GitLab instance as a merge request. See the GNOME Wiki’s GitLab documentation for more details.

If you are not a GNOME developer then you will need to first create a fork of Vala to your personal GNOME GitLab instance, which you then clone to your local machine.

Patches to the compiler should include one or more test cases.

Patches will also be accepted as attachments to an issue.

Reviewing and Updating Patches¶

If your merge request requires updating after review then use git rebase --interactive to squash the changes and git push --force the updated branch to your GNOME GitLab instance. GitLab will then pick up the changes and show them in the merge request.

Committing Patches¶

Todo

Add information about how to commit patches to the compiler project.

Feel free to help: Vala Docs Repository.

Maintaining Bindings¶

The Vala repository carries a number of bindings to libraries. The bindings are written in one of three ways:

Manually
Generated using vapigen from a GIR (GObject Introspection Repository) file
Generated using vapigen from a deprecated GIDL file

To update a binding the first thing to do is find how the binding is written. Look at the top of the VAPI file. If there is no comment generated by vapigen, do not modify then the VAPI is written manually. For example glib-2.0.vapi is written manually. If the VAPI is generated using files from the ./metadata/ directory then the VAPI is generated from a GIR file. For example gio-2.0.vapi is generated from a GIR file. If the VAPI is generated using files from the ./packages/ directory then the VAPI is generated from a GIDL file. For example the gtk+-2.0.vapi is generated from a GIDL file, but the gtk+-3.0.vapi is generated from the GIR.

Patches should be submitted through the merge request process outlined above. Patches for generated bindings should also include the changes to the VAPI itself. The Vala repository keeps the generated VAPIs in version control as well as the metadata. There is no need for test cases to be added for bindings.

Writing a VAPI Without Using GObject Introspection - detailed guide on writing a VAPI manually
Generating a VAPI with GObject Introspection- details on generating a VAPI using vapigen

Developing the Compiler¶

Documentation¶

Compiler Guide - Documentation for hacking on the compiler
Code Attributes

The internal API documentation, in Valadoc form, should be built from the source:

make -C doc internal-api-docs

This will generate output similar to https://gnome.pages.gitlab.gnome.org/vala/docs/index.html

Debugging¶

Using --enable-debug will include debugging symbols in the Vala compiler:

make distclean
./autogen.sh --enable-debug

This will enable Vala source files with line numbers to be shown when using gdb to generate a backtrace after a segmentation fault.

You can also change GLib criticals and warnings to generate a segmentation fault to enable a backtrace. This is done with the G_DEBUG environment variable:

G_DEBUG=fatal-criticals gdb --args <em>my_valac_version</em> my_test_program.vala

See Running and debugging GLib Applications for more information on G_DEBUG.

The Build Server¶

Vala maintainers make use of a Buildbot server to build a selection of projects written in Vala with a version of Vala from the main GNOME git repository. Of main interest to contributors is the vala-staging builder and also the vala-master builder. Builds from these servers include log files from STDIO for each build. This helps identify any problems with a patch that was committed to Vala.