Appendix G. Wrapping C Libraries with gmmproc

Table of Contents

gtkmm uses the gmmproc tool to generate most of its source code, using .defs files that define the APIs of GObject-based libraries. So it's quite easy to create additional gtkmm-style wrappers of other glib/GObject-based libraries.

This involves a variety of tools, some of them crufty, but at least they work, and has been used successfully by several projects.

The build structure

Generation of the source code for a gtkmm-style wrapper API requires use of tools such as gmmproc and generate_wrap_init.pl, which are included in glibmm. In theory you could write your own build files to use these appropriately, but a much better option is to make use of the build infrastructure provided by the mm-common module. To get started, it helps a lot to pick an existing binding module as an example to look at.

For instance, let's pretend that we are wrapping a C library called libsomething. It provides a GObject-based API with types named, for instance, SomeWidget and SomeStuff.

Copying the skeleton project

Typically our wrapper library would be called libsomethingmm. We can start by copying the skeleton source tree from the mm-common module. Starting with mm-common 1.0.0 this skeleton application is built with the Meson build system.

  $ git clone https://gitlab.gnome.org/GNOME/mm-common.git
  $ cp -a mm-common/skeletonmm libsomethingmm

This provides a directory structure for the source .hg and .ccg files and the hand-written .h and .cc files, with meson.build files that can specify the various files in use, in terms of Meson variables. The directory structure usually looks like this, after we have renamed the directories appropriately:

libsomethingmm: The top-level directory.
- libsomething: Contains the main include file and the pkg-config .pc file.
  - src: Contains .hg and .ccg source files.
  - libsomethingmm: Contains hand-written .h and .cc files.

As well as renaming the directories, we should rename some of the source files. For instance:

$ for f in $(find libsomethingmm -depth -name '*skeleton*'); do \
    d="${f%/*}"; b="${f##*/}"; mv "$f" "$d/${b//skeleton/libsomething}"; \
  done

A number of the skeleton files must still be filled in with project-specific content later.

Note that files ending in .in will be used to generate files with the same name but without the .in suffix, by replacing some variables with actual values during the configure stage.

Generated files are saved in the build tree, which is separated from the source tree when meson and ninja are used.

Modifying build files

Now we edit the files to adapt them to our needs. You might prefer to use a multiple-file search-replace utility for this, such as regexxer. Note that nearly all of the files provided with the skeleton source tree contain placeholder text. Thus, the substitutions should be performed globally, and not be limited to the Meson files.

All mentions of skeleton should be replaced by the correct name of the C library you are wrapping, such as "something" or "libsomething". In the same manner, all instances of SKELETON should be replaced by "SOMETHING" or "LIBSOMETHING", and all occurrences of Skeleton changed to "Something".

Likewise, replace all instances of Joe Hacker by the name of the intended copyright holder, which is probably you. Do the same for the joe@example.com email address.

meson.build in the top-level directory

It is common for binding modules to track the version number of the library they are wrapping. So, for instance, if the C library is at version 1.23.4, then the initial version of the binding module would be 1.23.0. However, avoid starting with an even minor version number as that usually indicates a stable release.
In the project() function, change the license and the C++ version, if necessary.
You probably need to add more required modules than glibmm and skeleton (libsomething).

Other meson.build files

Next we must adapt the other meson.build files:

skeleton/meson.build: Perhaps not much to change here more than the global name substitutions.
skeleton/skeletonmm/meson.build

defs_basefiles

If we have more .defs and docs.xml files, we add them here.

hg_ccg_basenames

We must mention all of our .hg and .ccg files here.

extra_cc_files, extra_h_files

Any additional hand-written .h and .cc source files go here.

Creating .hg and .ccg files

We should now create our first .hg and .ccg files, to wrap one of the objects in the C library. One pair of example source files already exists: skeleton.ccg and skeleton.hg. Create copies of these files as necessary.

In the .hg and .ccg files section you can learn about the syntax used in these files.


Installing and Using the git version of gtkmm		Generating the .defs files.