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.