1GLIB-GENMARSHAL(1)               User Commands              GLIB-GENMARSHAL(1)
2
3
4

NAME

6       glib-genmarshal - C code marshaller generation utility for GLib
7       closures
8

SYNOPSIS

10       glib-genmarshal [OPTION...] [FILE...]
11

DESCRIPTION

13       glib-genmarshal is a small utility that generates C code marshallers
14       for callback functions of the GClosure mechanism in the GObject
15       sublibrary of GLib. The marshaller functions have a standard signature,
16       they get passed in the invoking closure, an array of value structures
17       holding the callback function parameters and a value structure for the
18       return value of the callback. The marshaller is then responsible to
19       call the respective C code function of the closure with all the
20       parameters on the stack and to collect its return value.
21
22       glib-genmarshal takes a list of marshallers to generate as input. The
23       marshaller list is either read from files passed as additional
24       arguments on the command line; or from standard input, by using - as
25       the input file.
26
27   Marshaller list format
28       The marshaller lists are processed line by line, a line can contain a
29       comment in the form of
30       or a marshaller specification of the form
31
32           RTYPE:PTYPE
33           RTYPE:PTYPE,PTYPE
34           RTYPE:PTYPE,PTYPE,PTYPE
35
36       The RTYPE part specifies the callback's return type and the PTYPEs
37       right to the colon specify the callback's parameter list, except for
38       the first and the last arguments which are always pointers.
39
40   Parameter types
41       Currently, the following types are supported:
42
43       VOID
44           indicates no return type, or no extra parameters. If VOID is used
45           as the parameter list, no additional parameters may be present.
46
47       BOOLEAN
48           for boolean types (gboolean)
49
50       CHAR
51           for signed char types (gchar)
52
53       UCHAR
54           for unsigned char types (guchar)
55
56       INT
57           for signed integer types (gint)
58
59       UINT
60           for unsigned integer types (guint)
61
62       LONG
63           for signed long integer types (glong)
64
65       ULONG
66           for unsigned long integer types (gulong)
67
68       INT64
69           for signed 64bit integer types (gint64)
70
71       UINT64
72           for unsigned 64bit integer types (guint64)
73
74       ENUM
75           for enumeration types (gint)
76
77       FLAGS
78           for flag enumeration types (guint)
79
80       FLOAT
81           for single-precision float types (gfloat)
82
83       DOUBLE
84           for double-precision float types (gdouble)
85
86       STRING
87           for string types (gchar*)
88
89       BOXED
90           for boxed (anonymous but reference counted) types (GBoxed*)
91
92       PARAM
93           for GParamSpec or derived types (GParamSpec*)
94
95       POINTER
96           for anonymous pointer types (gpointer)
97
98       OBJECT
99           for GObject or derived types (GObject*)
100
101       VARIANT
102           for GVariant types (GVariant*)
103
104       NONE
105           deprecated alias for VOID
106
107       BOOL
108           deprecated alias for BOOLEAN
109

OPTIONS

111       --header
112           Generate header file contents of the marshallers. This option is
113           mutually exclusive with the --body option.
114
115       --body
116           Generate C code file contents of the marshallers. This option is
117           mutually exclusive with the --header option.
118
119       --prefix=PREFIX
120           Specify marshaller prefix. The default prefix is
121           `g_cclosure_user_marshal'.
122
123       --skip-source
124           Skip source location remarks in generated comments.
125
126       --stdinc
127           Use the standard marshallers of the GObject library, and include
128           glib-object.h in generated header files. This option is mutually
129           exclusive with the --nostdinc option.
130
131       --nostdinc
132           Do not use the standard marshallers of the GObject library, and
133           skip glib-object.h include directive in generated header files.
134           This option is mutually exclusive with the --stdinc option.
135
136       --internal
137           Mark generated functions as internal, using G_GNUC_INTERNAL.
138
139       --valist-marshallers
140           Generate valist marshallers, for use with
141           g_signal_set_va_marshaller().
142
143       -v, --version
144           Print version information.
145
146       --g-fatal-warnings
147           Make warnings fatal, that is, exit immediately once a warning
148           occurs.
149
150       -h, --help
151           Print brief help and exit.
152
153       -v, --version
154           Print version and exit.
155
156       --output=FILE
157           Write output to FILE instead of the standard output.
158
159       --prototypes
160           Generate function prototypes before the function definition in the
161           C source file, in order to avoid a missing-prototypes compiler
162           warning. This option is only useful when using the --body option.
163
164       --pragma-once
165           Use the once pragma instead of an old style header guard when
166           generating the C header file. This option is only useful when using
167           the --header option.
168
169       --include-header=HEADER
170           Adds a #include directive for the given file in the C source file.
171           This option is only useful when using the --body option.
172
173       -D SYMBOL[=VALUE]
174           Adds a #define C pre-processor directive for SYMBOL and its given
175           VALUE, or "1" if the value is unset. You can use this option
176           multiple times; if you do, all the symbols will be defined in the
177           same order given on the command line, before the symbols undefined
178           using the -U option. This option is only useful when using the
179           --body option.
180
181       -U SYMBOL
182           Adds a #undef C pre-processor directive to undefine the given
183           SYMBOL. You can use this option multiple times; if you do, all the
184           symbols will be undefined in the same order given on the command
185           line, after the symbols defined using the -D option. This option is
186           only useful when using the --body option.
187
188       --quiet
189           Minimizes the output of glib-genmarshal, by printing only warnings
190           and errors. This option is mutually exclusive with the --verbose
191           option.
192
193       --verbose
194           Increases the verbosity of glib-genmarshal, by printing debugging
195           information. This option is mutually exclusive with the --quiet
196           option.
197

USING GLIB-GENMARSHAL WITH MESON

199       Meson supports generating closure marshallers using glib-genmarshal out
200       of the box in its "gnome" module.
201
202       In your meson.build file you will typically call the gnome.genmarshal()
203       method with the source list of marshallers to generate:
204
205           gnome = import('gnome')
206           marshal_files = gnome.genmarshal('marshal',
207             sources: 'marshal.list',
208             internal: true,
209           )
210
211       The marshal_files variable will contain an array of two elements in the
212       following order:
213
214       •   a build target for the source file
215
216       •   a build target for the header file
217
218       You should use the returned objects to provide a dependency on every
219       other build target that references the source or header file; for
220       instance, if you are using the source to build a library:
221
222           mainlib = library('project',
223             sources: project_sources + marshal_files,
224             ...
225           )
226
227       Additionally, if you are including the generated header file inside a
228       build target that depends on the library you just built, you must
229       ensure that the internal dependency includes the generated header as a
230       required source file:
231
232           mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
233
234       You should not include the generated source file as well, otherwise it
235       will be built separately for every target that depends on it, causing
236       build failures. To know more about why all this is required, please
237       refer to the corresponding Meson FAQ entry[1].
238
239       For more information on how to use the method, see the Meson
240       documentation for gnome.genmarshal()[2].
241

USING GLIB-GENMARSHAL WITH AUTOTOOLS

243       In order to use glib-genmarshal in your project when using Autotools as
244       the build system, you will first need to modify your configure.ac file
245       to ensure you find the appropriate command using pkg-config, similarly
246       as to how you discover the compiler and linker flags for GLib.
247
248           PKG_PROG_PKG_CONFIG([0.28])
249
250           PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
251
252       In your Makefile.am file you will typically need very simple rules to
253       generate the C files needed for the build.
254
255           marshal.h: marshal.list
256                   $(AM_V_GEN)$(GLIB_GENMARSHAL) \
257                           --header \
258                           --output=$@ \
259                           $<
260
261           marshal.c: marshal.list marshal.h
262                   $(AM_V_GEN)$(GLIB_GENMARSHAL) \
263                           --include-header=marshal.h \
264                           --body \
265                           --output=$@ \
266                           $<
267
268           BUILT_SOURCES += marshal.h marshal.c
269           CLEANFILES += marshal.h marshal.c
270           EXTRA_DIST += marshal.list
271
272       In the example above, the first rule generates the header file and
273       depends on a marshal.list file in order to regenerate the result in
274       case the marshallers list is updated. The second rule generates the
275       source file for the same marshal.list, and includes the file generated
276       by the header rule.
277

EXAMPLE

279       To generate marshallers for the following callback functions:
280
281           void   foo (gpointer data1,
282                       gpointer data2);
283           void   bar (gpointer data1,
284                       gint     param1,
285                       gpointer data2);
286           gfloat baz (gpointer data1,
287                       gboolean param1,
288                       guchar   param2,
289                       gpointer data2);
290
291       The marshaller.list file has to look like this:
292
293           VOID:VOID
294           VOID:INT
295           FLOAT:BOOLEAN,UCHAR
296
297       and you call glib-genmarshal like this:
298
299           glib-genmarshal --header marshaller.list > marshaller.h
300           glib-genmarshal --body marshaller.list > marshaller.c
301
302       The generated marshallers have the arguments encoded in their function
303       name. For this particular list, they are
304
305           g_cclosure_user_marshal_VOID__VOID(...),
306           g_cclosure_user_marshal_VOID__INT(...),
307           g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
308
309       They can be used directly for GClosures or be passed in as the
310       GSignalCMarshaller c_marshaller; argument upon creation of signals:
311
312           GClosure *cc_foo, *cc_bar, *cc_baz;
313
314           cc_foo = g_cclosure_new (NULL, foo, NULL);
315           g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
316           cc_bar = g_cclosure_new (NULL, bar, NULL);
317           g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
318           cc_baz = g_cclosure_new (NULL, baz, NULL);
319           g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
320

SEE ALSO

322       glib-mkenums(1)
323

NOTES

325        1. corresponding Meson FAQ entry
326           https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
327
328        2. Meson documentation for gnome.genmarshal()
329           https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
330
331
332
333GObject                                                     GLIB-GENMARSHAL(1)
Impressum