Generating the .defs files

Generating the .defs files
	Appendix G. Wrapping C Libraries with gmmproc

The .defs files are text files, in a lisp format, that describe the API of a C library, including its

objects (GObjects, widgets, interfaces, boxed-types and plain structs)
functions
enums
signals
properties
vfuncs

We split these .defs files into separate files. For instance, in the gtk/src directory of the gtkmm sources, you will find these files:

gtk.defs: Includes the other files.
gtk_methods.defs: Objects and functions.
gtk_enums.defs: Enumerations.
gtk_signals.defs: Signals and properties.
gtk_vfuncs.defs: vfuncs (function pointer member fields in structs), written by hand.

The skeletonmm/tools/generate_defs_and_docs.sh script generates all .defs files and the *_docs.xml file, described in the Documentation section.

If the wrapped C library uses GObject-introspection and generates a GIR file, you can alternatively copy and adapt the skeletonmm/tools/generate_from_gir.sh script, which also generates all .defs files and the *_docs.xml file.

Generating .defs without a GIR file

Generating the methods .defs

This .defs file describes objects and their functions. It is generated by the h2def.py script which you can find in glibmm's tools/defs_gen directory. For instance,

$ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs

Generating the enums .defs

This .defs file describes enum types and their possible values. It is generated by the enumextract.py script which you can also find in glibmm's tools/defs_gen directory. For instance,

$ ./enumextract.py /usr/include/gtk-4.0/gtk/*.h > gtk_enums.defs

Generating the signals and properties .defs

This .defs file describes signals and properties. It is generated by the special generate_extra_defs utility that is in every wrapping project, such as gtkmm/tools/extra_defs_gen/. For instance

$ cd tools/extra_defs_gen
$ ./generate_extra_defs > gtk_signals.defs

You must edit the source code of your own generate_extra_defs tool in order to generate the .defs for the GObject C types that you wish to wrap. In the skeleton source tree, the source file is named tools/extra_defs_gen/generate_defs_skeleton.cc. If not done so already, the file should be renamed, with the basename of your new binding substituted for the skeleton placeholder. The tools/extra_defs_gen/meson.build file should also mention the new source filename.

Then edit the .cc file to specify the correct types. For instance, your main() function might look like this:

#include <glibmm_generate_extra_defs/generate_extra_defs.h>
#include <libsomething.h>
#include <iostream>

int main(int, char**)
{
  something_init();

  std::cout << get_defs(SOME_TYPE_WIDGET)
            << get_defs(SOME_TYPE_STUFF);
  return 0;
}

Writing the vfuncs .defs

This .defs file describes virtual functions (vfuncs). It must be written by hand. There is the skeleton file skeleton/src/skeleton_vfunc.defs to start from. You can also look at gtkmm's gtk/src/gtk_vfuncs.defs file.

Generating .defs from a GIR file

Glibmm since version 2.88.1 contains the mmgir tool. This is a C++ program. To use it, build glibmm with meson with the -Dbuild-mmgir=true option.

mmgir can generate all the .defs files. For instance,

$ ./mmgir --gir /usr/share/gir-1.0/Gtk-4.0.gir \
    --gir-search-dir /usr/share/gir-1.0 \
    --enum-defs gtk_enums.defs \
    --function-defs gtk_methods.defs \
    --signal-defs gtk_signals.defs \
    --vfunc-defs gtk_vfuncs.defs


Appendix G. Wrapping C Libraries with gmmproc		The .hg and .ccg files