GObjectIntrospection

App Developer Week -- GObject Introspection: The New Way For Developing GNOME Apps in Python, JavaScript and Others -- tomeu -- Mon, Apr 11th, 2011

   1 [18:03] <tomeu> Hi, I'm a GNOME developer working at Collabora.
   2 [18:03] <tomeu> During the past few years it has been evident that trying to keep the GNOME APIs available to languages other than C required more resources than were available.
   3 [18:03] <tomeu> If you were working on a Python app using GNOME stuff, you probably realized about that.
   4 [18:03] <tomeu> GObject Introspection's main goal is to radically lower the amount of effort required to do that.
   5 [18:04] <tomeu> Feel free to make questions at any point, I will address them as I see them fitting in the plan of the talk.
   6 

The problem

   1 [18:04] <tomeu> Before introspection was available for GObject-based APIs, bindings maintainers had to produce C code that would bridge between the host language and each C API that would be made accessible.
   2 [18:04] <tomeu> There were code generators that saved a lot of time, but still, corner cases had to be handled manually and the generated code had to be maintained.
   3 [18:05] <tomeu> The total amount of work required to keep the C APIs callable from other languages was a factor of the size of the APIs, the number of languages that would be able to call into them, and the distros where such bindings had to be packaged.
   4 [18:05] <tomeu> As you can see, the amount of work to be done was growing very quickly, far faster than resource availability in a mature project such as GNOME.
   5 

The solution

   1 [18:06] <tomeu> The reason why bindings weren't able to generate code that wouldn't need manual modifications is that by scanning the C sources there's only so much information available.
   2 [18:07] <tomeu> There is critical information that bindings need that was only available in natural-language API documentation or in the code itself.
   3 [18:07] <tomeu> Some bindings allowed this information to be manually added and fed to the generator, but it meant that each binding had to write that extra information by themselves, maintain it, etc.
   4 [18:07] <tomeu> Based on that experience, it turned out to be clear that the extra information required to call the C API had to be added to the API sources themselves, so all bindings could benefit. This extra information is added in what we call "annotations" and we'll get into a bit of detail later.
   5 [18:08] <tomeu> But that's not enough to reduce the workload at the distro level, if each binding had to generate code based on that extra information, distros would still need to package each binding for each API and each language.
   6 [18:09] <tomeu> This is the reason why all the introspection information needs to be available at runtime, so a system which has bindings for, say Python, can call some new C API without having to write, package and deploy specific software for it.
   7 [18:09] <tomeu> So introspection information is available at runtime with acceptable performance, it is compiled into "typelibs": tightly packed files that can be mmapped and queried with low overhead.
   8 

Workflow changes

   1 [18:10] <tomeu> ASCII art overview of GI's architecture: http://live.gnome.org/GObjectIntrospection/Architecture
   2 [18:11] <tomeu> (I'm going to go through it, so I recommend to give it a look now)
   3 [18:11] <tomeu> When building a shared library, g-ir-scanner is called which will scan the source code, query GType for some more bits of info, and produce a XML file with the .gir suffix.
   4 [18:12] <tomeu> The .gir file is then compiled into a typelib, with the .typelib suffix.
   5 [18:12] <tomeu> The typelib is distributed along with the shared library and the .gir file is distributed with the header files.
   6 [18:12] <tomeu> When an application that uses introspection is running, the introspection bindings for its programming language will use the information in the typelib to find out how it should call the C API, being helped by the GType system and by libraries such as libffi.
   7 [18:13] <tomeu> Now I'm going to make a pause until someone says in #*-chat that I'm not going too fast :)
   8 

Annotations

   1 [18:14] <tomeu> The needed information that is missing in the signature of the C API includes mainly:
   2 [18:14] <tomeu> * details about the contents of collections (element-type),
   3 [18:15] <tomeu> * memory management expectations (transfer xxx),
   4 [18:15] <tomeu> * which functions are convenience API for C users and should not be exposed (skip),
   5 [18:15] <tomeu> * scope of callbacks (scope),
   6 [18:15] <tomeu> * auxiliar arguments (closure) (array length=2),
   7 [18:15] <tomeu> * is NULL accepted as an input argument (allow-none),
   8 [18:15] <tomeu> * and more.
   9 [18:15] <tomeu> For more details: http://live.gnome.org/GObjectIntrospection/Annotations
  10 [18:15] <tomeu> Example from GTK:
  11 [18:15] <tomeu> --------------------- 8< -----------------
  12 

   1 /**
   2  * gtk_tree_model_filter_new:
   3  * @child_model: A #GtkTreeModel.
   4  * @root: (allow-none): A #GtkTreePath or %NULL.
   5  *
   6  * Creates a new #GtkTreeModel, with @child_model as the child_model
   7  * and @root as the virtual root.
   8  *
   9  * Return value: (transfer full): A new #GtkTreeModel.
  10  */
  11 GtkTreeModel *
  12 gtk_tree_model_filter_new (GtkTreeModel *child_model,
  13                            GtkTreePath  *root)
  14 

   1 [18:16] <tomeu> --------------------- 8< -----------------
   2 

Other benefits

   1 [18:16] <tomeu> Having available all the required information at runtime means that bindings can decide more freely when to allocate resources such as datas structures and function stubs, this allows bindings to address long-time issues such as slow startup and high memory usage.
   2 [18:16] <tomeu> Another consequence of bindings calling the C APIs as exposed by upstream means that documentation can be generated directly from the introspectable information, without any per-API work.
   3 [18:17] <tomeu> By lowering the barrier to expose APIs to other languages, more applications are being made extensible through the use of plugins.
   4 [18:18] <tomeu> Libpeas helps your application to expose some extension points that can be used by plugins written in C, JavaScript and Python. It is already being used by Totem, GEdit, Vinagre, Eye of GNOME, etc
   5 

Changes for library authors

   1 [18:18] <tomeu> Library authors that wish their API was available to other languages need to mainly do these three things:
   2 [18:18] <tomeu> * mark all the API that cannot be called from other languages with (skip) so it doesn't appear in the typelib,
   3 [18:19] <tomeu> that API could be considered as a convenience for C users
   4 [18:19] <tomeu> * make sure all the functionality is available to bindings (by adding overlapping API),
   5 [18:19] <tomeu> * modify their build system to generate and install the .gir and .typelib files (http://live.gnome.org/GObjectIntrospection/AutotoolsIntegration),
   6 [18:19] <tomeu> * add annotations as mentioned before.
   7 [18:19] <tomeu> In practical terms and for existing libraries, it uses to be better if people trying to use your API are the ones that submit patches adding annotations as they have a more readily available way to check for their correctness.
   8 [18:20] <tomeu> But for the author of the API it should be generally obvious which annotations are needed provided some exposure to how bindings use the introspected information.
   9 

Changes for application authors

   1 [18:20] <tomeu> Application authors need to be aware that, until the whole callable API becomes used through introspection by applications, they cannot expect for the annotations to be perfect.
   2 [18:20] <tomeu> So instead of waiting for introspection to "mature", consider starting right now and get involved upstream by pointing out issues and proposing annotations and alternative API when needed.
   3 [18:21] <tomeu> For now, may be best to look at the .gir to figure out how to call something, if the C docs aren't enough.
   4 [18:21] <tomeu> In the future there will be documentation generated for each language from the .gir files, but nobody has got anything usable yet.
   5 [18:22] <tomeu> so I don't have any more text to copy&paste, I will gladly answer any questions
   6 [18:23] <ClassBot> crazedpsyc asked: is this available for languages other than C?
   7 [18:24] <tomeu> no, it would be really hard depending on the particular language
   8 [18:24] <tomeu> and the turnout would be smaller because platform code tends to be written in C in the GObject world
   9 [18:25] <ClassBot> patrickd asked: Are there examples any where of getting started using these bindings in say, something like python?
  10 [18:25] <tomeu> we have some material at http://live.gnome.org/PyGObject/IntrospectionPorting
  11 [18:26] <tomeu> but tomorrow you will get a session here by pitti just about python and introspection
  12 [18:26] <tomeu> this was intended to present the basic concepts, tomorrow will be more about practical stuff
  13 [18:28] <ClassBot> abhinav81 asked: so a language binding (say python) for a library ultimately calls the C API ?
  14 [18:28] <tomeu> yes, there will be some glue code in python that will be calling the same API that C programs use
  15 [18:29] <tomeu> PyGObject uses libffi directly, there's another alternative implementation that uses python's ctypes (which in turn also uses libffi)
  16 [18:29] <tomeu> we also have an experimental branch of pygobject by jdahlin that uses LLVM to generate wrappers
  17 [18:30] <tomeu> I know python best, but I guess other languages will have other mechanisms to call into C code at runtime
  18 [18:30] <ClassBot> chadadavis asked: is the plan to currently move everything to PyGI then? What types of applications would be better off staying with PyGTK?
  19 [18:31] <tomeu> at this moment, pygtk won't be updated to support gtk3
  20 [18:31] <tomeu> also, pygobject+introspection doesn't support gtk2
  21 [18:32] <tomeu> so my recommendation is to do what most GNOME apps do: branch and keep a maintenance branch which still uses pygtk/gtk2, and move master to introspection and gtk3
  22 [18:32] <ClassBot> geojorg asked: What is the current status of PyGI in Python 3 ?
  23 [18:33] <tomeu> haven't been personally involved on that, but I think someone at the last hackfest rebased the python3 branch
  24 [18:33] <tomeu> I think fedora is aiming for gtk3+python3 for their next release
  25 [18:35] <tomeu> I will hang around for a while in case there's some more questions before the next talk starts
  26 [18:35] <ClassBot> JanC asked: how similar are code for PyGtk & PyGI (and thus how much work is it to port an application and keep parallel branches)?
  27 [18:36] <tomeu> IMO is not that dissimilar, you have some tips about porting here:http://live.gnome.org/PyGObject/IntrospectionPorting
  28 [18:37] <tomeu> and you can get an idea of the kind of transformations needed by reading this script: http://git.gnome.org/browse/pygobject/tree/pygi-convert.sh
  29 [18:37] <tomeu> you may find that the changes between gtk2 and gtk3 are more worrying, depending on how much of the API your app uses
  30 [18:37] <ClassBot> pecisk asked: is the any deadlines when all base apps should be correctly supported by g-i?
  31 [18:38] <tomeu> you say you meant base libs, so the deadline was GNOME 3 for all libraries in GNOME
  32 [18:39] <tomeu> no doubt some libraries will have better annotations than others
  33 [18:40] <tomeu> as I said before, the quality of their introspection support depends greatly on the contributions from application authors, which went on submitting annotations for the API that their app uses
  34 [18:40] <ClassBot> crazedpsyc asked: can I get PyGI in maverick? how?
  35 [18:40] <tomeu> I have heard you can, but I'm not sure how (I don't use ubuntu)
  36 [18:41] <tomeu> but even then, maverick has gtk2 afaik, so I would recommend to try to move to natty for development
  37 [18:41] <tomeu> gtk2 lacks a lot of annotations because the focus has been on gtk3
  38 [18:44] <tomeu> there may exist a PPA, not sure
  39 

Where to go from here?

   1 [18:49] <tomeu> http://live.gnome.org/GObjectIntrospection
   2 [18:49] <tomeu> In GIMPNet: #introspection, #python, #javascript, ...
   3 [18:50] <tomeu> Thanks for the attention and the questions, I also have to thank Martin Pitt for passing me his notes on GI
   4 [18:51] <tomeu> as said, he will be giving tomorrow a session focused on python and introspection
   5 [18:52] <tomeu> laszlok: QUESTION: is there a bug report or a wiki page about the status of generating documentation for the new API?
   6 [18:52] <tomeu> let me get some links for you
   7 [18:52] <tomeu> http://blog.tomeuvizoso.net/2011/02/generating-api-docs-from-gir-files.html
   8 [18:52] <tomeu> https://bugzilla.gnome.org/show_bug.cgi?id=625494
   9 [18:53] <ClassBot> There are 10 minutes remaining in the current session.
  10 [18:53] <ClassBot> laszlok asked: is there a bug report or a wiki page about the status of generating documentation for the new API?
  11 [18:53] <tomeu> http://live.gnome.org/Hackfests/Introspection2011#line-19
  12 

MeetingLogs/appdevweek1104/GObjectIntrospection (last edited 2011-04-12 07:26:08 by dpm)