@node Getting started, The GLib type system, Top, Top
@chapter Getting started

Early in the development of guile-gnome, we realized that at some
point we might need to make incompatible changes. Of course, we would
not want to force a correctly-written program to break when
guile-gnome gets upgraded. For this reason, we decided to make
guile-gnome parallel-installable. A program is completely specified
when it indicates which version of guile-gnome it should use.

Guile-gnome has the concept of an API version, which indicates a
stable API series. For example, a program written against API version
1 of guile-gnome will continue to work against all future releases of
that API version. It is permitted to add interfaces within a stable
series, but never to remove or change them incompatibly.

There is a special API version, version 0, which has no stability
guarantees, used for development.

Changing the API version is expected to be a relatively infrequent
operation. Indeed, we have not yet reached stable version 1. At the
time of this writing, guile-gnome is still unstable.

There are two manners for a program to specify the
guile-gnome-version:

@enumerate
@item
Via importing the @code{(gnome-@var{version})} module.

This special module alters guile's load path to include the path of
the specified API version of guile-gnome. For example:

@lisp
(use-modules (gnome-0))
@end lisp

@item
Via invoking guile as guile-gnome-@var{version}.

This shell script is installed when building a particular version of
guile-gnome, and serves to automatically load the
@code{(gnome-@var{apiversion})} module. For example, to get a repl
ready for guile-gnome:

@example
$ guile-gnome-0
@end example

To load a script with a particular version of guile-gnome:

@example
$ guile-gnome-0 -s @var{script} @var{args...}
@end example

To specify the guile-gnome version in a script, you might begin the
file with:

@example
#! /bin/sh
# -*- scheme -*-
exec guile-gnome-0 -s $0
!#
;; scheme code here...
@end example
@end enumerate

A program must select the guile-gnome version before importing any
guile-gnome modules. Indeed, one cannot even import @code{(gnome
gobject)} before doing so.

For a further rationale on parallel installability, see
@uref{http://ometer.com/parallel.html}.
