“…why should we not calmly and patiently review our own thoughts, and thoroughly examine and see what these appearances in us really are?” — Plato
GObject Introspection is a pretty neat tool from the Gnome project that allows you to expose a common API from a C library to various scripting languages. This is accomplished by “introspection” (my favorite computer metaphor I’ve come across so far) where by a coder may follow conventions that enable the program to take an inventory of its internal state after compiling and describe itself in a structured, language-agnostic kind of way.
The downside of this approach is the complexity it imposes on the library’s initial creators. The most challenging aspect for me was actually getting the thing to build. The best supported build system is the venerable autotools aka the GNU build system, with autoconf, automake, libtool, et al.
This guide is meant to be a gentle introduction to setting up a build system for a GI library. You should have a basic understanding of the GObject class before you begin. All the files discussed here are available on the Github project page.
The name of this project is called Maman (“Maman” is French for “mother”). Maman has one object called
Bar, which is the main thing we are trying to build. Let’s have a look at the structure of the project.
1 2 3 4 5 6 7 8 9 10 11 12
The source files
maman-bar.h define the Bar object. They are discussed in detail in the GObject reference manual under the tutorial on how to define and implement a new GObject. Most of the code in these files are boilerplate required to define a GObject. You can extend these files to implement your own methods, properties, and event signals.
The build system source code consists of the files
Using the build system
The executable shell file
autogen.sh (short for “automatically generate” I guess) should make the GNU Build System files. It usually consists of just a few lines of portable shell to prepare the project.
1 2 3 4
This step of the process requires autotools. If you want to distribute a buildable package without requiring autotools, the generated files are designed to be included in your project repository. Do not edit these files by hand because they will be overwritten the next time
autogen.sh is run.
autogen.sh is run, you can generate a
Makefile for your system with the included
./configure script, and use
make to build the project. The GNU Build System takes care of all the platform-specific details of this process, so your library will now build on a toaster.
Examining the build system source
Now that you know how it is supposed to work, let’s have a look at the build system source files
maman/Makefile.am. Be warned that one of the most common criticisms of autotools is that it tends to be less accessible to non-experts. There are indeed plenty of magic words to be spoken here. Like, you are seriously going to feel like Harry Potter after you write these files. The advantage of the GNU system however is that once written, they tend to be low maintenance.
Let’s look at each file individually and examine its purpose and implementation so you know what to do if you ever need to make any changes to your build.
configure.ac file is used to make the
./configure script. Each line in this script is actually being expanded to shell code that will become
./configure. Use square brackets (
]) to quote argument parameters.
The configuration script defined by this file has two important purposes. The first is to test that the system has everything that is required to build the project in a way that clearly lets people know if something is missing. The second is to define important variables that will be used in other parts of the build system representing the best choice for the target environment, including compiler tools, the path to library headers, environment flags, and the location of resources within the project.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
Once you have this written, you can use
autoscan to get suggestions for additional macros to improve portability based on your source code.
Writing the Makefile.am files
There are two
Makefile.am files, one at the project root and one in the source directory. These files describe your project in such a way that autotools can write Makefiles to build the project for the environment it was configured for.
First lets look at the top-level Makefile.am.
1 2 3
The first line points to the location we defined for the
AC_CONFIG_MACRO_DIR and the second is required for GObject-introspection.
SUBDIRS definition tells where to look for other Makefiles, such as the one that will be made in
maman, our source code directory.
The last file in our build system is
maman/Makefile.am. This is where the project is really defined.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
Using the bindings
Once your library is built, set up the development environment for the bindings by defining some variables in your shell.
When the PyGObject module available, the following python script should now work as you expect it to.
1 2 3 4 5 6 7 8 9 10 11