danigm.net - gnome-class

GIR support in gnome-class

danigm — Sat, 01 Sep 2018 00:00:00 +0200

Recently I've been working again in the rust port of libgepub, libgepub is C code, but in the rust-migration branch almost all the real functionality is done with rust and the GepubDoc class is a GObject wrapper around that code.

For this reason I was thinking about to use gnome-class to implement GepubDoc.

Gnome-class is a rust lib to write GObject code in rust that's compatible with the C binary API so then you can call this new GObject code written with gnome-class from C. I've worked a little in gnome-class, implementing a basic properties support.

GObject Introspection

A great advantage of write GObject code in C is that you can have automatic bindings using GObject Introspection. This is great because you only need to write the C code, write correctly the documentation of the public API and then you'll get GIR for free, and that means that you can use your lib from gjs, python and other automatic bindings.

GIR defines a simple XML document to declare the public API and there is the meta information needed for bindings, to know how to call the lib functions and how to convert params and also provides memory management information, for languages with garbage collector and so. These files are places under /usr/share/gir-1.0/ and it looks like this:

      <method name="get_cover" c:identifier="gepub_doc_get_cover">
        <return-value transfer-ownership="full">
          <doc xml:space="preserve">cover file path to retrieve with
gepub_doc_get_resource</doc>
          <type name="utf8" c:type="gchar*"/>
        </return-value>
        <parameters>
          <instance-parameter name="doc" transfer-ownership="none">
            <doc xml:space="preserve">a #GepubDoc</doc>
            <type name="Doc" c:type="GepubDoc*"/>
          </instance-parameter>
        </parameters>
      </method>

This xml is compiled to a binary format to be used from bindings and those compiled gir files are places under /usr/lib64/girepository-1.0/ with the .typelib extension.

This is great, and the GepubDoc class is exported as GIR and indeed it's used from javascript code in the gnome-books application using this. If we want to migrate libgepub from C to rust, we need to provide this GIR to don't break the compatibility in other apps. That's done currently in the rust-migration branch by hand, creating the GepubDoc in C and calling the rust code from there.

With gnome-class it should be possible to write that GepubDoc code in rust and have the same ABI, but currently gnome-class doesn't generate GIR, that's a little problem that I can try to solve using my dev skills.

Adding GIR to gnome-class

So, libgepub is the excuse to start to implement GIR in gnome-class. There's an issue in the gitlab with an initial syntax proposal and I started from that:

#[generate_gir("foo.gir")]
#[generate_c_header("foo.h")]
gobject_gen! {
    "foo.gir",
    "foo.h",

    class Foo {
        ...
    }

    impl Foo {
        ...
    }
}

The first thing to do is to add a way to tell that we want to generate the GIR file in the class definition. In this proposal, the GIR tag is before the gobject_gen proc-macro, that can't be done, or I don't know how to do that easily, so I changed to a declaration inside the proc-macro, that's what we're parsing in gnome-class:

gobject_gen! {
    #[generate_gir("Counter.gir")]
    class Counter {
      f: Cell<u32>,
    }

    impl Counter {
        pub fn add(&self, x: u32) -> u32 {
            self.get_priv().f.set(self.get() + x);
            self.get()
        }

        pub fn get(&self) -> u32 {
            self.get_priv().f.get()
        }
    }
}

With the code insithe de gobject_gen I only need to update the parser to allow this new syntax:

named!{parse_gir -> Option<LitStr>,
    option!(do_parse!(
        punct!(#)                               >>
        name: brackets!(do_parse!(
            call!(keyword("generate_gir"))      >>
            name: parens!(syn!(LitStr))         >>
            (name.1)
        )) >>
        (name.1)
    ))
}

impl Synom for ast::Class {
    named!(parse -> Self, do_parse!(
        gir: call!(parse_gir)                                    >>
        call!(keyword("class"))                                  >>
        name: syn!(Ident)                                        >>
        extends: option!(do_parse!(
            punct!(:)                                            >>
            superclass: syn!(Path)                               >>
            // FIXME: interfaces
            (superclass)))                                       >>
        fields: syn!(FieldsNamed)                                >>
        (ast::Class {
            gir,
            name,
            extends,
            fields,
        })
    ));

Then, I'm storing the GIR file name in the ast class so I can check if that field is None or Some and generate the GIR in that case.

Generating the XML

The parser was the easier part, we've now the hability to define if we want to generate the GIR file and we're storing that information in the High-level Internal Representation (hir).

To generate the XML I've to add a new call before generating the code:

     let result: Result<proc_macro2::TokenStream> =
-        hir::Program::from_ast_program(&ast_program).and_then(|program| Ok(gen::codegen(&program)));
+        hir::Program::from_ast_program(&ast_program)
+            .and_then(|program| {
+                gen::gir::generate(&program)?;
+                Ok(gen::codegen(&program))
+            });

     match result {
         Ok(tokens) => {

The gir module generates the XML, iterating over all classes defined in the program.

The XML isn't really hard to generate, we've almost all the information so we can iterate over all the class methods and add to the XML. There's some information that's not really easy to get so I've let some TODO in this initial version, like:

Find the parent class name (GObject.Object by default)
Get the library version and shared-lib path (lib#CLASSNAME#1.0.0 by default)
Get dependencies

So this is not a full featured GIR support, but it's an initial step to get it, and it works, at least with simple examples :D

Example project

To test that this is working correctly I've created a simple example project, that uses gnome-class, generates the gir and has an small script to call the generated code from python.

This is the rust code:

gobject_gen! {
    #[generate_gir("Counter.gir")]
    class Counter {
      f: Cell<u32>,
    }

    impl Counter {
        pub fn add(&self, x: u32) -> u32 {
            self.get_priv().f.set(self.get() + x);
            self.get()
        }

        pub fn get(&self) -> u32 {
            self.get_priv().f.get()
        }
    }
}

I've a bash script to compile and generate the typelib file from the xml, generated by gnome-class:

cargo +nightly build
g-ir-compiler Counter.gir > Counter-1.0.typelib

And I've written a test in python using gi.repository:

import unittest
from gi.repository import Counter

class TestCounter(unittest.TestCase):

    def test_new(self):
        c = Counter.Counter()
        self.assertEqual(c.get(), 0)

    def test_add(self):
        c = Counter.Counter()
        self.assertEqual(c.add(1), 1)
        self.assertEqual(c.add(3), 4)

    def test_get(self):
        c = Counter.Counter()
        self.assertEqual(c.get(), 0)
        self.assertEqual(c.add(1), 1)
        self.assertEqual(c.get(), 1)

if __name__ == '__main__':
    unittest.main()

This is working right now, so we're getting closer to the final goal of having libgepub written with rust code and have GIR generation.

GNOME 💙 Rust Hackfest in Madrid

danigm — Thu, 26 Apr 2018 00:00:00 +0200

The last week was the GNOME 💙 Rust hackfest in Madrid. I was there, only for the first two days, but was a great experience to meet the people working with Rust in GNOME a great community with a lot of talented people.

The event was in the OpenShine office, that was a great place and the OpenShine people was very friendly too so thank you very much to OpenShine for support this kind of events.

What I did during the Hackfest

I arrive at 10:30, more or less, and there are some people there, but two or three comes after the lunch, so the first morning we started to work, each one in their project.

I've some patches for Fractal to review and I was working on the glade file splitting. After that I downloaded the gnome-class code and started to read and try to understand the code because I want to help in the gnome-class development during the Hackfest.

After the lunch, the missing people from the morning was there so we did an official "Hackfest presentation" everyone did a little presentation about his work and what want to do during the event.

Gnome-class was the main project to join GNOME and Rust, and it's still in a early alpha stage so Federico give us a little talk about what's gnome-class and its parts.

Gnome-class

Gnome-class is basically a compiler that translate custom syntax to Gobject binary compatible Rust code. Using the proc-macro, gnome-class parses a Gobject like declaration and creates all the Rust code needed to use the Glib so we can have binary code that can be called from C or from Rust. With this we can do Object Oriented programming in Rust using the Gobject library and types.

So we've three parts in gnome-class, the parser, the High-level Internal Representation (HIR) and the code generation.

gobject_gen! {
    class Counter {
      f: Cell<u32>,
    }

    impl Counter {
        pub fn add(&self, x: u32) -> u32 {
            self.get_priv().f.set(self.get() + x);
            self.get()
        }

        pub fn get(&self) -> u32 {
            self.get_priv().f.get()
        }
    }
}

#[test]
fn test() {
    let c: Counter = Counter::new();

    println!("Counter has value: {}", c.get());

    c.add(2);
    c.add(20);
    assert_eq!(c.get(), 22);

    println!("Counter has value: {}", c.get());
}

This is Rust code with gnome-class, here we're creating a new Class called Counter with two public methods, then we've a test that use this. Behind this code, gnome-class generates a lot of ugly code with pointers and so to make all of this C-Compatible and generate all the needed binary using the GObject data scheme.

My work in gnome-class

Properties declaration was not supported in gnome-class so took that task. There was a proposed syntax and I started to work in the parser to try to support that syntax and convert all the relevant information into a Rust struct in the HIR tree.

To parse that I needed to learn syn that's a parser based in nom. That was not easy, but there's a lot of code in gnome-class so I can read and learn from that and at the end of the day I had a working properties parser.

The second day I continue with my work and started to generate code. Here I have more problems because the code generated is too low level and I didn't now much about the GObject internals so I was playing around types conversions.

I've to go just after the lunch, but during the back to home train trip I was able to create a Merge Request with all the work I've done.

I've work to do during the week so I can't continue working on properties support in gnome-class. But this week I've more time and I've been working to complete the code generation, so now we've this test working:

#![feature(proc_macro)]

extern crate gobject_gen;

#[macro_use]
extern crate glib;
use gobject_gen::gobject_gen;

use std::cell::Cell;

gobject_gen! {
    class ClassWithProps {
        p: Cell<u32>,
        p2: Cell<u32>,
    }

    impl ClassWithProps {
        pub fn get(&self) -> u32 {
            self.get_priv().p.get() +
            self.get_priv().p2.get()
        }

        property MyProp: T where T: u32 {
            get(&self) -> T {
                let private = self.get_priv();
                return private.p.get();
            }

            set(&self, value: T) {
                let mut private = self.get_priv();
                private.p.set(value);
            }
        }

        property Prop2: T where T: u32 {
            get(&self) -> T {
                let private = self.get_priv();
                return private.p2.get();
            }

            set(&self, value: T) {
                let mut private = self.get_priv();
                private.p2.set(value);
            }
        }
    }
}

#[test]
fn test_props() {
    let obj: ClassWithProps = ClassWithProps::new();
    assert_eq!(obj.get(), 0);

    assert_eq!(obj.get_property_prop2(), 0);
    obj.set_property_prop2(42);
    assert_eq!(obj.get(), 42);
    assert_eq!(obj.get_property_prop2(), 42);

    obj.set_property_myprop(58);
    assert_eq!(obj.get_property_myprop(), 58);
}

My first GNOME hackfest

This was my first GNOME hackfest. I've been in different GUADECs and other events with GNOME devs, but this was the first time that I travel to work on a specific project and not just to meet the people and view talks from the distance.

It was a great experience. Rust is really new in the desktop development, but there's a lot of people working so it's great.

The next milestone is the Fractal Hackfest, we'll be in Strasbourg four days working.

I want to thank all the great GNOME community that makes collaboration so easy, it's a great community.

Currently all of my work on this is voluntary so I need to thank my coworkers at Wadobo, because I'm spending some work time in this. I can do this because my company is great.