mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-30 17:36:16 +01:00
3732f9bd07
And also link to the Meson FAQ that explains why this is needed so people aren't just cargo-culting code.
580 lines
17 KiB
XML
580 lines
17 KiB
XML
<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>
|