To understand how Guile-GI works, one needs to distinguish between itself and the bindings it creates.
typelibfiles, which describe code modules. It has a handful of procedures for inspecting
typelibfiles as well as some helper procedures for dynamically creating procedures and types.
typelibfiles. These are created at runtime as Guile loads them from the
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
Gtk-3.0) – and loads the entire typelib into them. This approach has
two major drawbacks.
(gi repository)has primitives to facilitate exactly that. See Typelib Introspection.
use-moduleson 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
(gi repository) defines
which loads a typelib into a module and also adds all loaded
functionality to its public interface. Use it as in the following
(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
#!/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.