GObject Introspection
Contents
What is introspection?
GObject introspection is a middleware layer between C libraries (using GObject) and language bindings. The C library can be scanned at compile time and generate metadata files, in addition to the actual native C library. Then language bindings can read this metadata and automatically provide bindings to call into the C library.
Goals
The introspection project has two major goals, and a variety of more minor ones.
Two level applications - C and <your favorite runtime>
It makes sense to build many kinds of applications using (at least) two different levels and languages — one for the low level elements, interfacing with the OS and/or the hardware; and one for the high level application logic. C is good for graphics, multimedia, and lower level systems work. However, writing complex software in C is difficult and error-prone. A managed runtime such as JavaScript, Python, Perl, Java, Lua, .NET, Scheme etc. makes a lot of sense for non-fast-path application logic such as configuration, layout, dialogs, etc.
Note: to achieve this goal you need to write your code using GObject convention. if you don't know about gobject please see here
Thus, one of the major goals of the GObject introspection project is to be a convenient bridge between these two worlds, and allow you to choose the right tool for the job, rather than being limited inside one or the other. With the introspection project, you can write for example a ClutterActor or GtkWidget subclass in C, and then without any additional work use that class inside the high level language of your choice.
Sharing binding infrastructure work, and making the platform even more binding-friendly
Historically in GNOME, the core platform has been relatively binding-friendly, but there are several details not captured in the C+GObject layer that bindings have needed. For example, reference counting semantics and the item type inside GList's. Up until now various language bindings such as Python, Mono, java-gnome etc. had duplicated copies of hand-maintained metadata, and this led to a situation where bindings tended to lag behind until these manual fixups were done, or were simply wrong, and your application would crash when calling a more obscure function.
The introspection project solves this by putting all of the metadata inside the GObject library itself, using annotations in the comments. This will lead to less duplicate work from binding authors, and a more reliable experience for binding consumers.
Additionally, because the introspection build process will occur inside the GObject libraries themselves, a goal is to encourage GObject authors to consider shaping their APIs to be more binding friendly from the start, rather than as an afterthought.
Additional goals and uses
- API verification - Sometimes the API of a library in our stack changes by accident. Usually by a less experienced developer making a change without realizing it will break applications. Introspecting the available API in each release of the library and comparing it to the last one makes it easy to see what changed
Documentation tools - The tools written inside of the GObjectIntrospection can easily be reused to improve that problem. Essentially; replacing gtk-doc. We want to document what we export so it makes sense to glue this together with API verification mentioned above (see BindingsDocumentation)
- UI Designer infrastructure
- Serialization/RPC/DBus
Using GI
Documentation
GObject Introspection Reference Manual
General Example Step by Step
../FromHereToThere is a tutorial on how to use the introspection system to create multilevel (polyglot) applications
GObject Introspection Tutorial is a "Hello World" type tutorial on how to create multilevel applications and libraries with GObject Introspection.
https://github.com/antono/vala-object - Use single GObject function from your favorite language
Annotation System
../Annotations Annotation documentation
Convention
http://developer.gnome.org/gobject/stable/gtype-conventions.html
Integrate GI in Autotools
../AutotoolsIntegration How to integration your library's build system with gobject-introspection
GI Library Boilerplate is a complete example of a build system based on the the reference manual.
Applications and Languages Bindings
../Users Language bindings and Applications using GObjectIntrospection
Write a Language Bindings
../HowToWriteALanguageBinding How to write an introspection binding for your language
Write Bindable API
../WritingBindingableAPIs is a set of best practices on writing C libraries to be easily bindable
Who is using GI
Initiatives/GnomeGoals/AddGObjectIntrospectionSupport Upstream status of introspection
Architecture
../Architecture ASCII-art diagram showing how things fit together
Contents of the package
It provides:
- An XML format called GIR containing introspection information in a machine parseable format
- Python package to create and parse the GIR format
- scanner to generate GIR format from C source and headers
- a typelib similar to xpcom/msole which stores the information on disk in a binary format
- a compiler to compile the typelib from a xml format (and vice versa)
- C library to read the typelib
Getting the code
The latest stable release is available from download.gnome.org
GObject Introspection is now stored in git and can be fetched:
git clone https://gitlab.gnome.org/GNOME/gobject-introspection.git
You can browse the repository only here.
GIR files are built in their respective modules.
Reporting bugs
For a list of existing bugs and feature requests, see the Issues page. You can also open an issue.
Contact
- For questions or additional information, please use:
Mailing list: gtk-devel-list@gnome.org
- IRC: #introspection on irc.gnome.org