GSoC 2024: Week 1-2 Report

Project

Add support for the latest GIR attributes and GI-Docgen formatting to Valadoc.

Mentor

Lorenz Wildberg

Project Planning

In the Phase I of this project, our focus is on adding support for latest GObject Introspection attributes to vapigen and the vala compiler. Currently we are adding support for the glib:sync-func, glib:async-func, and glib:finish-func attribute for method, and the default-value attribute for property. To accomplish this, we need to understand how the GirParser builds the AST from the GIR data, and how the GirWriter writes into the GIR file using the AST. The latter is a bit easy, because the GirWriter simply visits all code nodes and prints each one of them into the GIR file. However, we found the first one to be pretty challenging, about which we will discuss in a bit!

Week 1: Support for glib:sync-func, glib:async-func, and glib:finish-func attributes

Firstly we went through vala GIR files to decide how to implement support for these attributes:

                                    The glib:finish-func attribute for method

Then we decided to begin by adding support for the glib:sync-func, glib:async-func and glib:finish-func attributes:

• glib:sync-func: denotes the synchronous version of the asynchronous function.
• glib:async-func: denotes the asynchronous version of a synchronous function.
• glib:finish-func: denotes the finish function of the asynchronous function.

In the GirParser: It is clear that the property coroutine of Vala.Method is true for both async-func and finish-func in the AST. This is because there is only an asynchronous function, but no finish function in Vala. We have implemented support for glib:finish-func by using this attribute to identify whether a node in the AST created by the GirParser is an async-func. With the introduction of this attribute we no longer need to guess the finish function corresponding to an async-func by appending "_finish" to the name of the async-func. We can easily determine the finish function from the glib:finish-func attribute using:

                m.finish_func = girdata["glib:finish-func"];

In the GirWriter: To write these attributes onto the GIR files, we made the GirWriter to:

• write the glib:async-func attribute if the method is a synchronous function and the corresponding asynchronous function exists.
• write the glib:sync-func attribute and the glib:finish-func attribute if the method is an asynchronous function.




We also added a new property to Vala.Method - the property finish_func which, in addition to telling us the finish-func of the method, also tells if the method is an async-func (finish_func would be null if the method were not an async-func), thus making it possible to differentiate between async-func and finish-func in the GIR:

                                                                            

Week 2: Support for default-value attribute for property

As the name suggests, the default-value attribute gives the default value of a property. 

                                    The default-value attribute for property

It is worth mentioning that support for this attribute was already present in the GirWriter. So we only needed to implement support in the GirParser, and also ensure that the default value is outputted in the generated vapi files by adding support to the CodeWriter. We used the default-value attribute to set the initializer property of  Vala.Property. We then used initializer to output the default value onto the generated vapi files. This was a challenge to implement because the initializer is a Vala.Expression but the default-value that we get from the girdata is a string. So we need to convert the expression to a string in CodeWriter and parse the string into an expression in the GirParser. We are trying to accomplish by writing a function value_string_to_literal_expression in the GirParser:
 

Apart from working on these two attributes and adding test cases for them, we also worked on the merge request !374 which generates properties from getters and setters of compact classes in bindings. It needed some minor fixes and we are now closer to getting it merged. 

Challenges

Now let's talk about the challenges, because after all challenges are what make a project fun! As part of this project, we are working to add support for the latest GObject Introspection attributes in the GirParser. The GirParser works by building an AST of different code nodes in the code context. This involves parsing different symbols in the source file, and because there are so many symbols, the GirParser is dependent on over a hundred different files that are located in the directory vala/vala, and many of them have over thousands of lines of code. We need to understand how all of this is put together and how it results in the GirParser being able to parse GIR files. Currently we are trying to use a structured approach to code reading so that we can implement support for these attributes within the time we have to complete this project!

Thanks for reading :) Stay tuned for more updates!