2.1.1 use-typelibs

The easiest 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.
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.

use-typelibs is a simple interface for Guile scripts not broken into multiple modules.

2.1.2 require and load-by-name

For efficiency’s sake, you may want to only load parts, e.g. just GtkApplication and GtkWindow to significantly speed up loading. By targeted use of require and load-by-name, you can load only the procedures you intend to use. (gi repository) has primitives to facilitate exactly that. See Typelib Introspection.

(define-module (doc ex-load-by-name)
  #:use-module (gi)
  #:use-module (gi repository))
(require "GLib" "2.0")
(load-by-name "GLib" "MainLoop")
(load-by-name "GLib" "MainContext")
(export <GMainLoop>
        main-loop:new
        is-running?
        <GMainContext>
        get-context)

2.1.3 typelib->module

If you don’t care much about waiting times – perhaps you only have a set of small dependencies, or you really need everything from a library – but you need the ability to refer to a module specifically through use-modules, you will have to provide your own module. However, writing all the require and load-by-names when you don’t care about granularity is tedious and error-prone.

As a convenience (gi repository) also contains typelib->module. This procedure loads a typelib into the current module and also adds all functionality loaded in the process to the public inferface.

(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

You may use it to create one such module per dependency, or one module for all dependencies. Together with Guile’s module system, you can even do some advanced operations, like loading all of Gtk under the prefix gtk:: together with all of Gstreamer under the prefix gst::. See Modules in The Guile reference manual.