| <refentry id="glib-genmarshal" lang="en"> |
| |
| <refentryinfo> |
| <title>glib-genmarshal</title> |
| <productname>GObject</productname> |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Emmanuele</firstname> |
| <surname>Bassi</surname> |
| </author> |
| <author> |
| <contrib>Original developer</contrib> |
| <firstname>Tim</firstname> |
| <surname>Janik</surname> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>glib-genmarshal</refentrytitle> |
| <manvolnum>1</manvolnum> |
| <refmiscinfo class="manual">User Commands</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>glib-genmarshal</refname> |
| <refpurpose>C code marshaller generation utility for GLib closures</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>glib-genmarshal</command> |
| <arg choice="opt" rep="repeat">OPTION</arg> |
| <arg choice="opt" rep="repeat">FILE</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1><title>Description</title> |
| <para><command>glib-genmarshal</command> is a small utility that generates C code |
| marshallers for callback functions of the GClosure mechanism in the GObject |
| sublibrary of GLib. The marshaller functions have a standard signature, |
| they get passed in the invoking closure, an array of value structures holding |
| the callback function parameters and a value structure for the return value |
| of the callback. The marshaller is then responsible to call the respective C |
| code function of the closure with all the parameters on the stack and to |
| collect its return value. |
| </para> |
| |
| <para><command>glib-genmarshal</command> takes a list of marshallers to generate as |
| input. The marshaller list is either read from files passed as additional arguments |
| on the command line; or from standard input, by using <literal>-</literal> as the |
| input file. |
| </para> |
| |
| <refsect2><title>Marshaller list format</title> |
| <para> |
| The marshaller lists are processed line by line, a line can contain a |
| comment in the form of |
| <informalexample><programlisting> |
| # this is a comment |
| </programlisting></informalexample> |
| or a marshaller specification of the form |
| <programlisting> |
| <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable> |
| <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable> |
| <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable> |
| </programlisting> |
| </para> |
| <para> |
| The <replaceable>RTYPE</replaceable> part specifies the callback's return |
| type and the <replaceable>PTYPE</replaceable>s right to the colon specify |
| the callback's parameter list, except for the first and the last arguments |
| which are always pointers. |
| </para> |
| </refsect2> |
| <refsect2><title>Parameter types</title> |
| <para> |
| Currently, the following types are supported: |
| <variablelist> |
| <varlistentry> |
| <term><replaceable>VOID</replaceable></term> |
| <listitem><para> |
| indicates no return type, or no extra parameters. |
| If <replaceable>VOID</replaceable> is used as the parameter list, no |
| additional parameters may be present. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>BOOLEAN</replaceable></term> |
| <listitem><para> |
| for boolean types (gboolean) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>CHAR</replaceable></term> |
| <listitem><para> |
| for signed char types (gchar) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>UCHAR</replaceable></term> |
| <listitem><para> |
| for unsigned char types (guchar) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>INT</replaceable></term> |
| <listitem><para> |
| for signed integer types (gint) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>UINT</replaceable></term> |
| <listitem><para> |
| for unsigned integer types (guint) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>LONG</replaceable></term> |
| <listitem><para> |
| for signed long integer types (glong) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>ULONG</replaceable></term> |
| <listitem><para> |
| for unsigned long integer types (gulong) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>INT64</replaceable></term> |
| <listitem><para> |
| for signed 64bit integer types (gint64) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>UINT64</replaceable></term> |
| <listitem><para> |
| for unsigned 64bit integer types (guint64) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>ENUM</replaceable></term> |
| <listitem><para> |
| for enumeration types (gint) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>FLAGS</replaceable></term> |
| <listitem><para> |
| for flag enumeration types (guint) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>FLOAT</replaceable></term> |
| <listitem><para> |
| for single-precision float types (gfloat) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>DOUBLE</replaceable></term> |
| <listitem><para> |
| for double-precision float types (gdouble) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>STRING</replaceable></term> |
| <listitem><para> |
| for string types (gchar*) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>BOXED</replaceable></term> |
| <listitem><para> |
| for boxed (anonymous but reference counted) types (GBoxed*) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>PARAM</replaceable></term> |
| <listitem><para> |
| for GParamSpec or derived types (GParamSpec*) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>POINTER</replaceable></term> |
| <listitem><para> |
| for anonymous pointer types (gpointer) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>OBJECT</replaceable></term> |
| <listitem><para> |
| for GObject or derived types (GObject*) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>VARIANT</replaceable></term> |
| <listitem><para> |
| for GVariant types (GVariant*) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>NONE</replaceable></term> |
| <listitem><para> |
| deprecated alias for <replaceable>VOID</replaceable> |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable>BOOL</replaceable></term> |
| <listitem><para> |
| deprecated alias for <replaceable>BOOLEAN</replaceable> |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1><title>Options</title> |
| <variablelist> |
| |
| <varlistentry> |
| <term><option>--header</option></term> |
| <listitem><para> |
| Generate header file contents of the marshallers. This option is mutually |
| exclusive with the <option>--body</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--body</option></term> |
| <listitem><para> |
| Generate C code file contents of the marshallers. This option is mutually |
| exclusive with the <option>--header</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term> |
| <listitem><para> |
| Specify marshaller prefix. The default prefix is <literal>`g_cclosure_user_marshal'</literal>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--skip-source</option></term> |
| <listitem><para> |
| Skip source location remarks in generated comments. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--stdinc</option></term> |
| <listitem><para> |
| Use the standard marshallers of the GObject library, and include |
| <filename>glib-object.h</filename> in generated header files. This |
| option is mutually exclusive with the <option>--nostdinc</option> |
| option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--nostdinc</option></term> |
| <listitem><para> |
| Do not use the standard marshallers of the GObject library, and skip |
| <filename>glib-object.h</filename> include directive in generated header files. |
| This option is mutually exclusive with the <option>--stdinc</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--internal</option></term> |
| <listitem><para> |
| Mark generated functions as internal, using <literal>G_GNUC_INTERNAL</literal>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--valist-marshallers</option></term> |
| <listitem><para> |
| Generate valist marshallers, for use with <function>g_signal_set_va_marshaller()</function>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-v</option>, <option>--version</option></term> |
| <listitem><para> |
| Print version information. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--g-fatal-warnings</option></term> |
| <listitem><para> |
| Make warnings fatal, that is, exit immediately once a warning occurs. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-h</option>, <option>--help</option></term> |
| <listitem><para> |
| Print brief help and exit. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-v</option>, <option>--version</option></term> |
| <listitem><para> |
| Print version and exit. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--output=FILE</option></term> |
| <listitem><para> |
| Write output to <replaceable>FILE</replaceable> instead of the standard output. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--prototypes</option></term> |
| <listitem><para> |
| Generate function prototypes before the function definition in the C source |
| file, in order to avoid a <literal>missing-prototypes</literal> compiler |
| warning. This option is only useful when using the <option>--body</option> |
| option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--pragma-once</option></term> |
| <listitem><para> |
| Use the <literal>once</literal> pragma instead of an old style header guard |
| when generating the C header file. This option is only useful when using the |
| <option>--header</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--include-header=<replaceable>HEADER</replaceable></option></term> |
| <listitem><para> |
| Adds a <literal>#include</literal> directive for the given file in the C |
| source file. This option is only useful when using the <option>--body</option> |
| option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-D <replaceable>SYMBOL[=VALUE]</replaceable></option></term> |
| <listitem><para> |
| Adds a <literal>#define</literal> C pre-processor directive for |
| <replaceable>SYMBOL</replaceable> and its given <replaceable>VALUE</replaceable>, |
| or "1" if the value is unset. You can use this option multiple times; if you do, |
| all the symbols will be defined in the same order given on the command line, before |
| the symbols undefined using the <option>-U</option> option. This option is only |
| useful when using the <option>--body</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-U <replaceable>SYMBOL</replaceable></option></term> |
| <listitem><para> |
| Adds a <literal>#undef</literal> C pre-processor directive to undefine the |
| given <replaceable>SYMBOL</replaceable>. You can use this option multiple times; |
| if you do, all the symbols will be undefined in the same order given on the |
| command line, after the symbols defined using the <option>-D</option> option. |
| This option is only useful when using the <option>--body</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--quiet</option></term> |
| <listitem><para> |
| Minimizes the output of <command>glib-genmarshal</command>, by printing only |
| warnings and errors. This option is mutually exclusive with the |
| <option>--verbose</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--verbose</option></term> |
| <listitem><para> |
| Increases the verbosity of <command>glib-genmarshal</command>, by printing |
| debugging information. This option is mutually exclusive with the |
| <option>--quiet</option> option. |
| </para></listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </refsect1> |
| |
| <refsect1><title>Using <command>glib-genmarshal</command> with Meson</title> |
| <para> |
| Meson supports generating closure marshallers using <command>glib-genmarshal</command> |
| out of the box in its "gnome" module. |
| </para> |
| |
| <para> |
| In your <filename>meson.build</filename> file you will typically call the |
| <literal>gnome.genmarshal()</literal> method with the source list of marshallers |
| to generate: |
| </para> |
| <informalexample><programlisting> |
| gnome = import('gnome') |
| marshal_files = gnome.genmarshal('marshal', |
| sources: 'marshal.list', |
| internal: true, |
| ) |
| </programlisting></informalexample> |
| <para> |
| The <literal>marshal_files</literal> variable will contain an array of two elements |
| in the following order: |
| </para> |
| <itemizedlist> |
| <listitem><para>a build target for the source file</para></listitem> |
| <listitem><para>a build target for the header file</para></listitem> |
| </itemizedlist> |
| <para> |
| You should use the returned objects to provide a dependency on every other |
| build target that references the source or header file; for instance, if you |
| are using the source to build a library: |
| </para> |
| <informalexample><programlisting> |
| mainlib = library('project', |
| sources: project_sources + marshal_files, |
| ... |
| ) |
| </programlisting></informalexample> |
| <para> |
| Additionally, if you are including the generated header file inside a build |
| target that depends on the library you just built, you must ensure that the |
| internal dependency includes the generated header as a required source file: |
| </para> |
| <informalexample><programlisting> |
| mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib) |
| </programlisting></informalexample> |
| <para> |
| You should not include the generated source file as well, otherwise it will |
| be built separately for every target that depends on it, causing build |
| failures. To know more about why all this is required, please refer to the |
| <ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers"> |
| corresponding Meson FAQ entry</ulink>. |
| </para> |
| <para> |
| For more information on how to use the method, see the |
| <ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson |
| documentation for <literal>gnome.genmarshal()</literal></ulink>. |
| </para> |
| </refsect1> |
| |
| <refsect1><title>Using <command>glib-genmarshal</command> with Autotools</title> |
| <para> |
| In order to use <command>glib-genmarshal</command> in your project when using |
| Autotools as the build system, you will first need to modify your |
| <filename>configure.ac</filename> file to ensure you find the appropriate |
| command using <command>pkg-config</command>, similarly as to how you discover |
| the compiler and linker flags for GLib. |
| </para> |
| <informalexample><programlisting> |
| PKG_PROG_PKG_CONFIG([0.28]) |
| |
| PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal]) |
| </programlisting></informalexample> |
| <para> |
| In your <filename>Makefile.am</filename> file you will typically need very |
| simple rules to generate the C files needed for the build. |
| </para> |
| <informalexample><programlisting> |
| marshal.h: marshal.list |
| $(AM_V_GEN)$(GLIB_GENMARSHAL) \ |
| --header \ |
| --output=$@ \ |
| $< |
| |
| marshal.c: marshal.list marshal.h |
| $(AM_V_GEN)$(GLIB_GENMARSHAL) \ |
| --include-header=marshal.h \ |
| --body \ |
| --output=$@ \ |
| $< |
| |
| BUILT_SOURCES += marshal.h marshal.c |
| CLEANFILES += marshal.h marshal.c |
| EXTRA_DIST += marshal.list |
| </programlisting></informalexample> |
| <para> |
| In the example above, the first rule generates the header file and depends on |
| a <filename>marshal.list</filename> file in order to regenerate the result in |
| case the marshallers list is updated. The second rule generates the source file |
| for the same <filename>marshal.list</filename>, and includes the file generated |
| by the header rule. |
| </para> |
| </refsect1> |
| |
| <refsect1><title>Example</title> |
| <para> |
| To generate marshallers for the following callback functions: |
| </para> |
| <informalexample><programlisting> |
| void foo (gpointer data1, |
| gpointer data2); |
| void bar (gpointer data1, |
| gint param1, |
| gpointer data2); |
| gfloat baz (gpointer data1, |
| gboolean param1, |
| guchar param2, |
| gpointer data2); |
| </programlisting></informalexample> |
| <para> |
| The <filename>marshaller.list</filename> file has to look like this: |
| </para> |
| <programlisting> |
| VOID:VOID |
| VOID:INT |
| FLOAT:BOOLEAN,UCHAR |
| </programlisting> |
| <para> |
| and you call glib-genmarshal like this: |
| </para> |
| <programlisting> |
| glib-genmarshal --header marshaller.list > marshaller.h |
| glib-genmarshal --body marshaller.list > marshaller.c |
| </programlisting> |
| <para> |
| The generated marshallers have the arguments encoded in their function name. |
| For this particular list, they are |
| </para> |
| <programlisting> |
| g_cclosure_user_marshal_VOID__VOID(...), |
| g_cclosure_user_marshal_VOID__INT(...), |
| g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...). |
| </programlisting> |
| <para> |
| They can be used directly for GClosures or be passed in as the |
| GSignalCMarshaller c_marshaller; argument upon creation of signals: |
| </para> |
| <informalexample><programlisting> |
| GClosure *cc_foo, *cc_bar, *cc_baz; |
| |
| cc_foo = g_cclosure_new (NULL, foo, NULL); |
| g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID); |
| cc_bar = g_cclosure_new (NULL, bar, NULL); |
| g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT); |
| cc_baz = g_cclosure_new (NULL, baz, NULL); |
| g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR); |
| </programlisting></informalexample> |
| </refsect1> |
| <refsect1><title>See also</title> |
| <para> |
| <citerefentry> |
| <refentrytitle>glib-mkenums</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry> |
| </para> |
| </refsect1> |
| </refentry> |