2. Overview
Gnome-class extends the Rust language to support a very particular kind of classes with inheritance, for the GObject type system. Gnome-class is implemented as a procedural macro in Rust; this means that it runs as part of the Rust compiler itself, and parses the user's Gnome-like code and generates Rust code for it.
Stages
Gnome-class operates in various stages, similar to a compiler:
-
Parsing into an Abstract Syntax Tree. We parse the code that the user put inside the
gobject_gen!
invocation using a syn-based parser. The parser generates an Abstract Syntax Tree (AST), which closely matches the structure of the user's code. At the end of this process, the code will be fully parsed into an AST (or it will have failed with a syntax error), but the AST may not be semantically valid. The AST is defined insrc/ast.rs
. -
We check the AST for semantic errors. For example, there cannot be two classes defined with the same name.
-
We create a High-level Internal Representation (HIR) from the AST. The HIR matches GObject concepts more closely. For example, while the AST may contain separate items for
class Foo
andimpl Foo
, the HIR has a singleClass
struct who knows which methods are defined for it, which virtual methods have default implementations, etc. This is also where we ensure that the user's code is semantically valid. For example, we check that the same signal name is not being declared twice for a class. The HIR is defined insrc/hir
. -
Code generation. We generate code based on the HIR. For each class defined in the HIR, we emit the necessary GObject boilerplate to register that class, its methods, signals, properties, etc. We emit the actual code for methods and signal handlers, and the necessary trampolines to call Rust methods and signal handlers from C. The code generator is defined in
src/gen
. In there, the one-time, per-class GObject boilerplate is insrc/gen/boilerplate.rs
. The other files in thesrc/gen
directory are used for things that require extra code generation like signals and traits for method trampolines.
Code structure
The entry point for gnome-class is the gobject_gen!
procedural
macro. It is defined in src/lib.rs
.
The AST structures are defined in src/ast.rs
.
The parser is in src/parser/mod.rs
.
Some of the AST validation code is in src/checking.rs
. Other checks
happen in the HIR.
The HIR is in src/hir/mod.rs
.
Finally, code generation is in src/gen/*.rs
.