Next: , Previous: , Up: Getting Started   [Contents][Index]


1.2 Guile-GI and Typelibs

To understand how Guile-GI works, one needs to distinguish between itself and the bindings it creates.

In order to make use of the latter, you must load a typelib through Guile-GI in one form or another. The easiest and recommended way of doing so is use-typelibs, as shown below.

(use-modules (gi))
(use-typelibs ("GLib" "2.0") ("Gtk" "3.0"))

use-typelibs works quite similar to use-modules and is in fact implemented in terms of it. The only difference in syntax is, that instead of a list of symbols describing a module, you have a list of exactly two strings, the first being the name of the typelib and the second being the version.

Semantically, however, the difference to use-modules is bigger. Internally, Guile-GI creates modules for the typelibs as needed – in this example these modules would be (%gi GLib-2.0) and (%gi Gtk-3.0) – and loads the entire typelib into them. This approach has two major drawbacks.

  1. Guile-GI has to load the entire typelib. For large typelibs, such as GTK, this takes a lot of time. Instead, you may want to only load parts, e.g. just GtkApplication and GtkWindow to significantly speed up loading. (gi repository) has primitives to facilitate exactly that. See Typelib Introspection.
  2. Even though Guile-GI internally uses modules, these modules are not available to the user in any meaningful way. Even another use-modules on them actually leads to undefined behaviour. It may load the module if it has already been defined somewhere else, but it might also throw an error, claiming that no code for the module could be found. This is to be expected, given that the modules are not backed by actual files.

    If you need to use use-modules (e.g. as a part of a define-module), you need to write the module yourself. As a convenience, (gi repository) defines typelib->module, which loads a typelib into a module and also adds all loaded functionality to its public interface. Use it as in the following example.

    (define-module (gi gtk-3)
      #:use-module (gi)
      #:use-module (gi repository))
    
    (typelib->module (current-module) "Gtk" "3.0")
    
    ;; additional code you might want to add and export
    

Loading typelibs alone might be all you need if you have perfect knowledge of all the libraries you are going to use and an intuitive understanding of how they are mapped to Scheme procedures. Chances are, however, that you do not. In this case, it might be useful to generate some documentation. See Typelib Documentation.

Upon installation of Guile-GI, we install a script called gi-gtkdoc, that can be invoked through guild. You may also want to create a guile-procedures.txt file for use in the REPL. We currently have no script for that, but one can easily be written. The following for example exports all the documentation for GObject-2.0.

#!/path/to/guile
!#
(use-modules (gi documentation))

(let ((%typelib (typelib "GObject" "2.0"))
      (%gir (false-if-exception (gir "GObject" "2.0")))
      (%doc '()))
  (set! %doc (parse %typelib %doc))
  (close %typelib)
  (when %gir
    (set! %doc (parse %gir %doc))
    (close %gir))
  (->guile-procedures.txt %doc))

Use shell pipes to redirect the output into a file, preferably one called “guile-procedures.txt”. Guile will search for documentation in such files in a few locations, including the current working directory.


Next: , Previous: , Up: Getting Started   [Contents][Index]