Wrapping C Libraries with gmmproc
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. 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.

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

This provides a directory structure for the source .hg and .ccg files and the generated .h and .cc files, with filelist.am Automake include files that can specify the various files in use, in terms of generic Automake 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 generated and hand-written .h and .cc files.
private: Contains generated *_p.h 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.

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 Automake and Autoconf 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.

configure.ac
In configure.ac,
The AC_CONFIG_SRCDIR() line must mention a file in our source tree. We can edit this later if we don't yet know the names of any of the files that we will create.
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.
The AC_CONFIG_HEADERS() line is used to generate two or more configuration header files. The first header file in the list contains all configuration macros which are set during the configure run. The remaining headers in the list contain only a subset of configuration macros and their corresponding config.h.in file will not be autogenerated. The reason for this separation is that the namespaced configuration headers are installed with your library and define publically visible macros.
The AC_SUBST([SOMETHINGMM_MODULES], ['...']) line may need to be modified to check for the correct dependencies.
The AC_CONFIG_FILES() block must mention the correct directory names, as described above.

Makefile.am files
Next we must adapt the various Makefile.am files:
In skeleton/src/Makefile.am we must mention the correct values for the generic variables that are used elsewhere in the build system:
binding_name 	The name of the library, such as libsomethingmm.
wrap_init_flags 	Additional command-line flags passed to the generate_wrap_init.pl script, such as the C++ namespace and the parent directory prefix of include files.
In skeleton/skeletonmm/Makefile.am we must mention the correct values for the generic variables that are used elsewhere in the build system:
lib_LTLIBRARIES 	This variable must mention the correct library name, and this library name must be used to form the _SOURCES, _LDFLAGS, and _LIBADD variable names. It is permissible to use variables substituted by configure like @SOMETHINGMM_API_VERSION@ as part of the variable names.
AM_CPPFLAGS 	The command line options passed to the C preprocessor.
AM_CXXFLAGS 	The command line options passed to the C++ compiler.

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.
We must mention all of our .hg and .ccg files in the skeleton/src/filelist.am file, typically in the files_hg variable.
Any additional non-generated .h and .cc source files may be placed in skeleton/skeletonmm/ and listed in skeleton/skeletonmm/filelist.am, typically in the files_extra_h and files_extra_cc variables.
In the .hg and .ccg files section you can learn about the syntax used in these files.

Generating the .defs files.
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
At the moment, we have separate tools for generating different parts of these .defs, so we split them up 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/codegen/generate_defs_and_docs.sh script generates all .defs files and the *_docs.xml file, described in the Documentation section.

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-3.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 enum.pl script which you can find in glibmm's tools directory. For instance,

$ ./enum.pl /usr/include/gtk-3.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 codegen/extradefs/generate_extra_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 codegen/Makefile.am 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 <libsomething.h>

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.

The .hg and .ccg files
The .hg and .ccg source files are very much like .h and .cc C++ source files, but they contain extra macros, such as _CLASS_GOBJECT() and _WRAP_METHOD(), from which gmmproc generates appropriate C++ source code, usually at the same position in the header. Any additional C++ source code will be copied verbatim into the corresponding .h or .cc file.
A .hg file will typically include some headers and then declare a class, using some macros to add API or behaviour to this class. For instance, gtkmm's button.hg looks roughly like this:

#include <gtkmm/bin.h>
#include <gtkmm/activatable.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)

namespace Gtk
{

class Button
  : public Bin,
    public Activatable
{
  _CLASS_GTKOBJECT(Button,GtkButton,GTK_BUTTON,Gtk::Bin,GtkBin)
  _IMPLEMENTS_INTERFACE(Activatable)
public:

  _CTOR_DEFAULT
  explicit Button(const Glib::ustring& label, bool mnemonic = false);

  _WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_button_set_label)

  ...

  _WRAP_SIGNAL(void clicked(), "clicked")

  ...

  _WRAP_PROPERTY("label", Glib::ustring)
};

} // namespace Gtk

The macros in this example do the following:
_DEFS() 	Specifies the destination directory for generated sources, and the name of the main .defs file that gmmproc should parse.
_PINCLUDE() 	Tells gmmproc to include a header in the generated private/button_p.h file.
_CLASS_GTKOBJECT() 	Tells gmmproc to add some typedefs, constructors, and standard methods to this class, as appropriate when wrapping a widget.
_IMPLEMENTS_INTERFACE() 	Tells gmmproc to add initialization code for the interface.
_CTOR_DEFAULT 	Add a default constructor.
_WRAP_METHOD(), _WRAP_SIGNAL(), and _WRAP_PROPERTY() 	Add methods to wrap parts of the C API.
The .h and .cc files will be generated from the .hg and .ccg files by processing them with gmmproc like so, though this happens automatically when using the above build structure:

$ cd gtk/src
$ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm

Notice that we provided gmmproc with the path to the .m4 convert files, the path to the .defs file, the name of a .hg file, the source directory, and the destination directory.
You should avoid including the C header from your C++ header, to avoid polluting the global namespace, and to avoid exporting unnecessary public API. But you will need to include the necessary C headers from your .ccg file.
The macros are explained in more detail in the following sections.

m4 Conversions
The macros that you use in the .hg and .ccg files often need to know how to convert a C++ type to a C type, or vice-versa. gmmproc takes this information from an .m4 file in your tools/m4/ directory. This allows it to call a C function in the implementation of your C++ method, passing the appropriate parameters to that C functon. For instance, this tells gmmproc how to convert a GtkTreeView pointer to a Gtk::TreeView pointer:

_CONVERSION(`GtkTreeView*',`TreeView*',`Glib::wrap($3)')

$3 will be replaced by the parameter name when this conversion is used by gmmproc.
Some extra macros make this easier and consistent. Look in gtkmm's .m4 files for examples. For instance:

_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
_CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P)
_CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))

m4 Initializations
Often when wrapping methods, it is desirable to store the return of the C function in what is called an output parameter. In this case, the C++ method returns void but an output parameter in which to store the value of the C function is included in the argument list of the C++ method. gmmproc allows such functionality, but appropriate initialization macros must be included to tell gmmproc how to initialize the C++ parameter from the return of the C function.
For example, if there was a C function that returned a GtkWidget* and for some reason, instead of having the C++ method also return the widget, it was desirable to have the C++ method place the widget in a specified output parameter, an initialization macro such as the following would be necessary:

_INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')

$3 will be replaced by the output parameter name of the C++ method and $4 will be replaced by the return of the C function when this initialization is used by gmmproc. For convenience, $1 will also be replaced by the C++ type without the ampersand (&) and $2 will be replaced by the C type.

Class macros
The class macro declares the class itself and its relationship with the underlying C type. It generates some internal constructors, the member gobject_, typedefs, the gobj() accessors, type registration, and the Glib::wrap() method, among other things.
Other macros, such as _WRAP_METHOD() and _WRAP_SIGNAL() may only be used after a call to a _CLASS_* macro.

_CLASS_GOBJECT
This macro declares a wrapper for a type that is derived from GObject, but whose wrapper is not derived from Gtk::Object.
_CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )
For instance, from accelgroup.hg:

_CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject)

_CLASS_GTKOBJECT
This macro declares a wrapper for a type whose wrapper is derived from Gtk::Object, such as a widget or dialog.
_CLASS_GTKOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )
For instance, from button.hg:

_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)

You will typically use this macro when the class already derives from Gtk::Object. For instance, you will use it when wrapping a GTK+ Widget, because Gtk::Widget derives from Gtk::Object.
You might also derive non-widget classes from Gtk::Object so they can be used without Glib::RefPtr. For instance, they could then be instantiated with Gtk::manage() or on the stack as a member variable. This is convenient, but you should use this only when you are sure that true reference-counting is not needed. We consider it useful for widgets.

_CLASS_BOXEDTYPE
This macro declares a wrapper for a non-GObject struct, registered with g_boxed_type_register_static().
_CLASS_BOXEDTYPE( C++ class, C class, new function, copy function, free function )
For instance, from Gdk::RGBA:

_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)

_CLASS_BOXEDTYPE_STATIC
This macro declares a wrapper for a simple assignable struct such as GdkRectangle. It is similar to _CLASS_BOXEDTYPE, but the C struct is not allocated dynamically.
_CLASS_BOXEDTYPE_STATIC( C++ class, C class )
For instance, for Gdk::Rectangle:

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

_CLASS_OPAQUE_COPYABLE
This macro declares a wrapper for an opaque struct that has copy and free functions. The new, copy and free functions will be used to instantiate the default constructor, copy constructor and destructor.
_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, copy function, free function )
For instance, from Glib::Checksum:

_CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)

_CLASS_OPAQUE_REFCOUNTED
This macro declares a wrapper for a reference-counted opaque struct. The C++ wrapper cannot be directly instantiated and can only be used with Glib::RefPtr.
_CLASS_OPAQUE_REFCOUNTED( C++ class, C class, new function, ref function, unref function )
For instance, for Pango::Coverage:

_CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_coverage_ref, pango_coverage_unref)

_CLASS_GENERIC
This macro can be used to wrap structs which don't fit into any specialized category.
_CLASS_GENERIC( C++ class, C class )
For instance, for Pango::AttrIter:

_CLASS_GENERIC(AttrIter, PangoAttrIterator)

_CLASS_INTERFACE
This macro declares a wrapper for a type that is derived from GTypeInterface.
_CLASS_INTERFACE( C++ class, C class, C casting macro, C interface struct, Base C++ class (optional), Base C class (optional) )
For instance, from celleditable.hg:

_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)

Two extra parameters are optional, for the case that the interface derives from another interface, which should be the case when the GInterface has another GInterface as a prerequisite. For instance, from loadableicon.hg:

_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)

Constructor macros
The _CTOR_DEFAULT() and _WRAP_CTOR() macros add constructors, wrapping the specified *_new() C functions. These macros assume that the C object has properties with the same names as the function parameters, as is usually the case, so that it can supply the parameters directly to a g_object_new() call. These constructors never actually call the *_new() C functions, because gtkmm must actually instantiate derived GTypes, and the *_new() C functions are meant only as convenience functions for C programmers.
When using _CLASS_GOBJECT(), the constructors should be protected (rather than public) and each constructor should have a corresponding _WRAP_CREATE() in the public section. This prevents the class from being instantiated without using a RefPtr. For instance:

class TextMark : public Glib::Object
{
  _CLASS_GOBJECT(TextMark, GtkTextMark, GTK_TEXT_MARK, Glib::Object, GObject)

protected:
  _WRAP_CTOR(TextMark(const Glib::ustring& name, bool left_gravity = true), gtk_text_mark_new)

public:
  _WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)

_CTOR_DEFAULT
This macro creates a default constructor with no arguments.

_WRAP_CTOR
This macro creates a constructor with arguments, equivalent to a *_new() C function. It won't actually call the *_new() function, but will simply create an equivalent constructor with the same argument types. It takes a C++ constructor signature, and a C function name.
It also takes an optional extra argument:
errthrow 	 This tells gmmproc that the C *_new() has a final GError** parameter which should be ignored.

Hand-coding constructors
When a constructor must be partly hand written because, for instance, the *_new() C function's parameters do not correspond directly to object properties, or because the *_new() C function does more than call g_object_new(), the _CONSTRUCT() macro may be used in the .ccg file to save some work. The _CONSTRUCT macro takes a series of property names and values. For instance, from button.ccg:

Button::Button(const Glib::ustring& label, bool mnemonic)
:
  _CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}

Method macros

_WRAP_METHOD
This macro generates the C++ method to wrap a C function.
_WRAP_METHOD( C++ method signature, C function name)
For instance, from entry.hg:

_WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)

The C function (e.g. gtk_entry_set_text) is described more fully in the .defs file, and the convert*.m4 files contain the necessary conversion from the C++ parameter type to the C parameter type. This macro also generates doxygen documentation comments based on the *_docs.xml and *_docs_override.xml files.
There are some optional extra arguments:
refreturn 	 Do an extra reference() on the return value, in case the C function does not provide a reference.
errthrow 	 Use the last GError** parameter of the C function to throw an exception.
deprecated 	 Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
constversion 	 Just call the non-const version of the same function, instead of generating almost duplicate code.
ifdef 	 Puts the generated code in #ifdef blocks.
slot_name 	 Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.
slot_callback 	 Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.
no_slot_copy 	 Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.
Selecting which C++ types should be used is also important when wrapping C API. Though it's usually obvious what C++ types should be used in the C++ method, here are some hints:
Objects used via RefPtr: Pass the RefPtr as a const reference. For instance, const Glib::RefPtr<Gtk::FileFilter>& filter.
Const Objects used via RefPtr: If the object should not be changed by the function, then make sure that the object is const, even if the RefPtr is already const. For instance, const Glib::RefPtr<const Gtk::FileFilter>& filter.
Wrapping GList* and GSList* parameters: First, you need to discover what objects are contained in the list's data field for each item, usually by reading the documentation for the C function. The list can then be wrapped by a std::vector type. For instance, std::vector< Glib::RefPtr<Gdk::Pixbuf> >. You may need to define a Traits type to specify how the C and C++ types should be converted.
Wrapping GList* and GSList* return types: You must discover whether the caller should free the list and whether it should release the items in the list, again by reading the documentation of the C function. With this information you can choose the ownership (none, shallow or deep) for the m4 conversion rule, which you should probably put directly into the .hg file because the ownership depends on the function rather than the type. For instance:

#m4 _CONVERSION(`GSList*',`std::vector<Widget*>',`Glib::SListHandler<Widget*>::slist_to_vector($3, Glib::OWNERSHIP_SHALLOW)')

_WRAP_METHOD_DOCS_ONLY
This macro is like _WRAP_METHOD(), but it generates only the documentation for a C++ method that wraps a C function. Use this when you must hand-code the method, but you want to use the documentation that would be generated if the method was generated.
_WRAP_METHOD_DOCS_ONLY(C function name)
For instance, from container.hg:

_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

_IGNORE / _IGNORE_SIGNAL
gmmproc will warn you on stdout about functions and signals that you have forgotten to wrap, helping to ensure that you are wrapping the complete API. But if you don't want to wrap some functions or signals, or if you chose to hand-code some methods then you can use the _IGNORE() or _IGNORE_SIGNAL() macro to make gmmproc stop complaining.
_IGNORE(C function name 1, C function name2, etc)
_IGNORE_SIGNAL(C signal name 1, C signal name2, etc)
For instance, from buttonbox.hg:

_IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing)

_WRAP_SIGNAL
This macro generates the C++ libsigc++-style signal to wrap a C GObject signal. It actually generates a public accessor method, such as signal_clicked(), which returns a proxy object. gmmproc uses the .defs file to discover the C parameter types and the .m4 convert files to discover appropriate type conversions.
_WRAP_SIGNAL( C++ signal handler signature, C signal name)
For instance, from button.hg:

_WRAP_SIGNAL(void clicked(),"clicked")

Signals usually have function pointers in the GTK struct, with a corresponding enum value and a g_signal_new() in the .c file.
There are some optional extra arguments:
no_default_handler 	 Do not generate an on_something() virtual method to allow easy overriding of the default signal handler. Use this when adding a signal with a default signal handler would break the ABI by increasing the size of the class's virtual function table.
custom_default_handler 	 Generate a declaration of the on_something() virtual method in the .h file, but do not generate a definition in the .cc file. Use this when you must generate the definition by hand.
custom_c_callback 	 Do not generate a C callback function for the signal. Use this when you must generate the callback function by hand.
refreturn 	 Do an extra reference() on the return value of the on_something() virtual method, in case the C function does not provide a reference.
ifdef 	 Puts the generated code in #ifdef blocks.

_WRAP_PROPERTY
This macro generates the C++ method to wrap a C GObject property. You must specify the property name and the wanted C++ type for the property. gmmproc uses the .defs file to discover the C type and the .m4 convert files to discover appropriate type conversions.
_WRAP_PROPERTY(C property name, C++ type)
For instance, from button.hg:

_WRAP_PROPERTY("label", Glib::ustring)

_WRAP_VFUNC
This macro generates the C++ method to wrap a virtual C function.
_WRAP_VFUNC( C++ method signature, C function name)
For instance, from widget.hg:

_WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)

The C function (e.g. get_request_mode) is described more fully in the *_vfuncs.defs file, and the convert*.m4 files contain the necessary conversion from the C++ parameter type to the C parameter type.
There are some optional extra arguments:
refreturn 	 Do an extra reference() on the return value of the something_vfunc() function, in case the virtual C function does not provide a reference.
refreturn_ctype 	 Do an extra reference() on the return value of an overridden something_vfunc() function in the C callback function, in case the calling C function expects it to provide a reference.
errthrow 	 Use the last GError** parameter of the C virtual function (if there is one) to throw an exception.
custom_vfunc 	 Do not generate a definition of the vfunc in the .cc file. Use this when you must generate the vfunc by hand.
custom_vfunc_callback 	 Do not generate a C callback function for the vfunc. Use this when you must generate the callback function by hand.
ifdef 	 Puts the generated code in #ifdef blocks.
slot_name 	 Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.
slot_callback 	 Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.
no_slot_copy 	 Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.
A rule to which there may be exceptions: If the virtual C function returns a pointer to an object derived from GObject, i.e. a reference-counted object, then the virtual C++ function shall return a Glib::RefPtr<> object. One of the extra arguments refreturn or refreturn_ctype is required.

Other macros

_IMPLEMENTS_INTERFACE
This macro generates initialization code for the interface.
_IMPLEMENTS_INTERFACE(C++ interface name)
For instance, from button.hg:

_IMPLEMENTS_INTERFACE(Activatable)

There is one optional extra argument:
ifdef 	 Puts the generated code in #ifdef blocks.

_WRAP_ENUM
This macro generates a C++ enum to wrap a C enum. You must specify the desired C++ name and the name of the underlying C enum.
For instance, from enums.hg:

_WRAP_ENUM(WindowType, GtkWindowType)

If the enum is not a GType, you must pass a third parameter NO_GTYPE. This is the case when there is no *_get_type() function for the C enum, but be careful that you don't just need to include an extra header for that function. You should also file a bug against the C API, because all enums should be registered as GTypes.
For example, from icontheme.hg:

_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)

_WRAP_ENUM_DOCS_ONLY
This macro just generates a Doxygen documentationn block for the enum. This is useful for enums that can't be wrapped with _WRAP_ENUM() because they are complexly defined (maybe using C macros) but including the generated enum documentation is still desired. It is used with the same syntax as _WRAP_ENUM() and also process the same options (though NO_GTYPE is just ignored because it makes no difference when just generating the enum's documentation).

_WRAP_GERROR
This macro generates a C++ exception class, derived from Glib::Error, with a Code enum and a code() method. You must specify the desired C++ name, the name of the corresponding C enum, and the prefix for the C enum values.
This exception can then be thrown by methods which are generated from _WRAP_METHOD() with the errthrow option.
For instance, from pixbuf.hg:

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

_MEMBER_GET / _MEMBER_SET
Use these macros if you're wrapping a simple struct or boxed type that provides direct access to its data members, to create getters and setters for the data members.
_MEMBER_GET(C++ name, C name, C++ type, C type)
_MEMBER_SET(C++ name, C name, C++ type, C type)
For example, in rectangle.hg:

_MEMBER_GET(x, x, int, int)

_MEMBER_GET_PTR / _MEMBER_SET_PTR
Use these macros to automatically provide getters and setters for a data member that is a pointer type. For the getter function, it will create two methods, one const and one non-const.
_MEMBER_GET_PTR(C++ name, C name, C++ type, C type)
_MEMBER_SET_PTR(C++ name, C name, C++ type, C type)
For example, for Pango::Analysis in item.hg:

// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// It's just a comment. It's difficult to find a real-world example.

_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT
Use these macros to provide getters and setters for a data member that is a GObject type that must be referenced before being returned.
_MEMBER_GET_GOBJECT(C++ name, C name, C++ type, C type)
_MEMBER_SET_GOBJECT(C++ name, C name, C++ type, C type)
For example, in Pangomm, layoutline.hg:

_MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)

gmmproc Parameter Processing
gmmproc allows processing the parameters in a method signature for the macros that process method signatures (like _WRAP_METHOD(), _WRAP_CTOR() and _WRAP_CREATE()) in a variety of ways:

Parameter Reordering
For all the macros that process method signatures, it is possible to specify a different order for the C++ parameters than the existing order in the C function, virtual function or signal. For example, say that the following C function were being wrapped as a C++ method for the Gtk::Widget class:

        void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
        GdkEventMask events);

However, changing the order of the C++ method's two parameters is necessary. Something like the following would wrap the function as a C++ method with a different order for the two parameters:

        _WRAP_METHOD(void set_device_events(Gdk::EventMask events{events},
        const Glib::RefPtr<const Gdk::Device>& device{device}),
        gtk_widget_set_device_events)

The {c_param_name} following the method parameter names tells gmmproc to map the C++ parameter to the specified C parameter within the {}. Since the C++ parameter names correspond to the C ones, the above could be re-written as:

        _WRAP_METHOD(void set_device_events(Gdk::EventMask events{.}, const
        Glib::RefPtr<const Gdk::Device>& device{.}),
        gtk_widget_set_device_events)

Please note that when reordering parameters for a _WRAP_SIGNAL() method signature, the C parameter names would always be p0, p1, etc. because the generate_extra_defs utility uses those parameter names no matter what the C API's parameter names may be. It's how the utility is written presently.

Optional Parameter Processing
For all macros processing method signatures except _WRAP_SIGNAL() and _WRAP_VFUNC() it is also possible to make the parameters optional so that extra C++ methods are generated without the specified optional parameter. For example, say that the following *_new() function were being wrapped as a constructor in the Gtk::ToolButton class:

        GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar*
        label);

Also, say that the C API allowed NULL for the function's label parameter so that that parameter is optional. It would be possible to have gmmproc generate the original constructor (with all the parameters) along with an additional constructor without that optional parameter by appending a {?} to the parameter name like so:

        _WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring&
        label{?}), gtk_tool_button_new)

In this case, two constructors would be generated: One with the optional parameter and one without it.

Output Parameter Processing
With _WRAP_METHOD() it is also possible for the return of the wrapped C function (if it has one) to be placed in an output parameter of the C++ method instead of having the C++ method also return a value like the C function does. To do that, simply include the output parameter in the C++ method parameter list appending a {OUT} to the output parameter name. For example, if gtk_widget_get_request_mode() is declared as the following:

        GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);

And having the C++ method set an output parameter is desired instead of returning a SizeRequestMode, something like the following could be used:

        _WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT})
        const, gtk_widget_get_request_mode)

The {OUT} appended to the name of the mode output parameter tells gmmproc to place the return of the C function in that output parameter. In this case, however, a necessary initialization macro like the following would also have to be specified:

        _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
        (SizeRequestMode)($4)')

Which could also be written as:

        _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
        ($1)($4)')

_WRAP_METHOD() also supports setting C++ output parameters from C output parameters if the C function being wrapped has any. Suppose, for example, that we want to wrap the following C function that returns a value in its C output parameter rect:

        gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
        GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);

To have gmmproc place the value returned in the C++ rect output parameter, something like the following _WRAP_METHOD() directive could be used:

        _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path, const
        CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
        gtk_icon_view_get_cell_rect)

The {>>} following the rect parameter name indicates that the C++ output parameter should be set from the value returned in the C parameter from the C function. gmmproc will generate a declaration of a temporary variable in which to store the value of the C output parameter and a statement that sets the C++ output parameter from the temporary variable. In this case it may be necessary to have an _INITIALIZATION() describing how to set a Gdk::Rectangle& from a GdkRectangle* such as the following:

        _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle', `$3 =
        Glib::wrap(&($4))')

Basic Types
Some of the basic types that are used in C APIs have better alternatives in C++. For example, there's no need for a gboolean type since C++ has bool. The following list shows some commonly-used types in C APIs and what you might convert them to in a C++ wrapper library.

Basic Type equivalents
C type
C++ type
gboolean	bool
gint	int
guint	guint
gdouble	double
gunichar	gunichar
gchar*	Glib::ustring (or std::string for filenames)

Hand-coded source files
You might want to include additional source files that will not be generated by gmmproc from .hg and .ccg files. You can simply place these in your libsomething/libsomethingmm directory and mention them in the Makefile.am in the files_extra_h and files_extra_cc variables.

Initialization
Your library must be initialized before it can be used, to register the new types that it makes available. Also, the C library that you are wrapping might have its own initialization function that you should call. You can do this in an init() function that you can place in hand-coded init.h and init.cc files. This function should initialize your dependencies (such as the C function, and gtkmm) and call your generated wrap_init() function. For instance:

void init()
{
  Gtk::Main::init_gtkmm_internals(); //Sets up the g type system and the Glib::wrap() table.
  wrap_init(); //Tells the Glib::wrap() table about the libsomethingmm classes.
}

The implementation of the wrap_init() method in wrap_init.cc is generated by generate_wrap_init.pl, but the declaration in wrap_init.h is hand-coded, so you will need to adjust wrap_init.h so that the wrap_init() function appears in the correct C++ namespace.

Problems in the C API.
You are likely to encounter some problems in the library that you are wrapping, particularly if it is a new project. Here are some common problems, with solutions.

Unable to predeclare structs
By convention, structs are declared in glib/GTK+-style headers like so:

typedef struct _ExampleWidget ExampleWidget;

struct _ExampleWidget
{
  ...
};

The extra typedef allows the struct to be used in a header without including its full definition, simply by predeclaring it, by repeating that typedef. This means that you don't have to include the C library's header in your C++ header, thus keeping it out of your public API. gmmproc assumes that this technique was used, so you will see compiler errors if that is not the case.
This compiler error might look like this:

example-widget.h:56: error: using typedef-name 'ExampleWidget' after 'struct'
../../libexample/libexamplemm/example-widget.h:34: error: 'ExampleWidget' has a previous declaration here
make[4]: *** [example-widget.lo] Error 1

or this:

example-widget.h:60: error: '_ExampleWidget ExampleWidget' redeclared as different kind of symbol
../../libexample/libexamplemm/example-widget.h:34: error: previous declaration of 'typedef struct _ExampleWidget ExampleWidget'

This is easy to correct in the C library, so do send a patch to the relevant maintainer.

Lack of properties
By convention, glib/GTK+-style objects have *_new() functions, such as example_widget_new() that do nothing more than call g_object_new() and return the result. The input parameters are supplied to g_object_new() along with the names of the properties for which they are values. For instance,

GtkWidget* example_widget_new(int something, const char* thing)
{
        return g_object_new (EXAMPLE_TYPE_WIDGET, "something", something, "thing", thing, NULL);
}

This allows language bindings to implement their own equivalents (such as C++ constructors), without using the *_new() function. This is often necessary so that they can actually instantiate a derived GType, to add their own hooks for signal handlers and vfuncs.
At the least, the _new() function should not use any private API (functions that are only in a .c file). Even when there are no functions, we can sometimes reimplement 2 or 3 lines of code in a _new() function as long as those lines of code use API that is available to us.
Another workaround is to add a *_construct() function that the C++ constructor can call after instantiating its own type. For instance,

GtkWidget* example_widget_new(int something, const char* thing)
{
        ExampleWidget* widget;
        widget = g_object_new (EXAMPLE_TYPE_WIDGET, NULL);
        example_widget_construct(widget, "something", something, "thing", thing);
}

void example_widget_construct(ExampleWidget* widget, int something, const char* thing)
{
        //Do stuff that uses private API:
        widget->priv->thing = thing;
        do_something(something);
}

Adding properties, and ensuring that they interact properly with each other, is relatively difficult to correct in the C library, but it is possible, so do file a bug and try to send a patch to the relevant maintainer.

Documentation
In general, gtkmm-style projects use Doxygen, which reads specially formatted C++ comments and generates HTML documentation. You may write these doxygen comments directly in the header files.

Reusing C documentation
You might wish to reuse documentation that exists for the C library that you are wrapping. GTK-style C libraries typically use gtk-doc and therefore have source code comments formatted for gtk-doc and some extra documentation in .sgml and .xml files. The docextract_to_xml.py script, from glibmm's tools/defs_gen directory, can read these files and generate an .xml file that gmmproc can use to generate doxygen comments. gmmproc will even try to transform the documentation to make it more appropriate for a C++ API.
For instance,

./docextract_to_xml.py -s ~/checkout/gnome/gtk+/gtk/ > gtk_docs.xml

Because this automatic transformation is not always appropriate, you might want to provide hand-written text for a particular method. You can do this by copying the XML node for the function from your something_docs.xml file to the something_docs_override.xml file and changing the contents.

Documentation build structure
If you copied the skeleton source tree in mm-common and substituted the placeholder text, then you will already have suitable Makefile.am and Doxyfile.in files. With the mm-common build setup, the list of Doxygen input files is not defined in the Doxygen configuration file, but passed along from make to the standard input of doxygen. The input file list is defined by the doc_input variable in the Makefile.am file.