1GLIB-GENMARSHAL(1) User Commands GLIB-GENMARSHAL(1)
2
6 glib-genmarshal - C code marshaller generation utility for GLib
7 closures
8
10 glib-genmarshal [OPTION...] [FILE...]
11
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 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 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 RTYPE:PTYPE
33 RTYPE:PTYPE,PTYPE
34 RTYPE:PTYPE,PTYPE,PTYPE
35 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 Parameter types
41 Currently, the following types are supported:
42 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 BOOLEAN
48 for boolean types (gboolean)
49 CHAR
51 for signed char types (gchar)
52 UCHAR
54 for unsigned char types (guchar)
55 INT
57 for signed integer types (gint)
58 UINT
60 for unsigned integer types (guint)
61 LONG
63 for signed long integer types (glong)
64 ULONG
66 for unsigned long integer types (gulong)
67 INT64
69 for signed 64bit integer types (gint64)
70 UINT64
72 for unsigned 64bit integer types (guint64)
73 ENUM
75 for enumeration types (gint)
76 FLAGS
78 for flag enumeration types (guint)
79 FLOAT
81 for single-precision float types (gfloat)
82 DOUBLE
84 for double-precision float types (gdouble)
85 STRING
87 for string types (gchar*)
88 BOXED
90 for boxed (anonymous but reference counted) types (GBoxed*)
91 PARAM
93 for GParamSpec or derived types (GParamSpec*)
94 POINTER
96 for anonymous pointer types (gpointer)
97 OBJECT
99 for GObject or derived types (GObject*)
100 VARIANT
102 for GVariant types (GVariant*)
103 NONE
105 deprecated alias for VOID
106 BOOL
108 deprecated alias for BOOLEAN
109
111 --header
112 Generate header file contents of the marshallers. This option is
113 mutually exclusive with the --body option.
114 --body
116 Generate C code file contents of the marshallers. This option is
117 mutually exclusive with the --header option.
118 --prefix=PREFIX
120 Specify marshaller prefix. The default prefix is
121 `g_cclosure_user_marshal'.
122 --skip-source
124 Skip source location remarks in generated comments.
125 --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 --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 --internal
137 Mark generated functions as internal, using G_GNUC_INTERNAL.
138 --valist-marshallers
140 Generate valist marshallers, for use with
141 g_signal_set_va_marshaller().
142 -v, --version
144 Print version information.
145 --g-fatal-warnings
147 Make warnings fatal, that is, exit immediately once a warning
148 occurs.
149 -h, --help
151 Print brief help and exit.
152 -v, --version
154 Print version and exit.
155 --output=FILE
157 Write output to FILE instead of the standard output.
158 --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 --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 --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 -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 -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 --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 --verbose
194 Increases the verbosity of glib-genmarshal, by printing debugging
195 information. This option is mutually exclusive with the --quiet
196 option.
197
199 Meson supports generating closure marshallers using glib-genmarshal out
200 of the box in its "gnome" module.
201 In your meson.build file you will typically call the gnome.genmarshal()
203 method with the source list of marshallers to generate:
204 gnome = import('gnome')
206 marshal_files = gnome.genmarshal('marshal',
207 sources: 'marshal.list',
208 internal: true,
209 )
210 The marshal_files variable will contain an array of two elements in the
212 following order:
213 • a build target for the source file
215 • a build target for the header file
217 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 mainlib = library('project',
223 sources: project_sources + marshal_files,
224 ...
225 )
226 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 mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
233 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 For more information on how to use the method, see the Meson
240 documentation for gnome.genmarshal()[2].
241
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 PKG_PROG_PKG_CONFIG([0.28])
249 PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
251 In your Makefile.am file you will typically need very simple rules to
253 generate the C files needed for the build.
254 marshal.h: marshal.list
256 $(AM_V_GEN)$(GLIB_GENMARSHAL) \
257 --header \
258 --output=$@ \
259 $<
260 marshal.c: marshal.list marshal.h
262 $(AM_V_GEN)$(GLIB_GENMARSHAL) \
263 --include-header=marshal.h \
264 --body \
265 --output=$@ \
266 $<
267 BUILT_SOURCES += marshal.h marshal.c
269 CLEANFILES += marshal.h marshal.c
270 EXTRA_DIST += marshal.list
271 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
279 To generate marshallers for the following callback functions:
280 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 The marshaller.list file has to look like this:
292 VOID:VOID
294 VOID:INT
295 FLOAT:BOOLEAN,UCHAR
296 and you call glib-genmarshal like this:
298 glib-genmarshal --header marshaller.list > marshaller.h
300 glib-genmarshal --body marshaller.list > marshaller.c
301 The generated marshallers have the arguments encoded in their function
303 name. For this particular list, they are
304 g_cclosure_user_marshal_VOID__VOID(...),
306 g_cclosure_user_marshal_VOID__INT(...),
307 g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
308 They can be used directly for GClosures or be passed in as the
310 GSignalCMarshaller c_marshaller; argument upon creation of signals:
311 GClosure *cc_foo, *cc_bar, *cc_baz;
313 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
322 glib-mkenums(1)
323
325 1. corresponding Meson FAQ entry
326 https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
327 2. Meson documentation for gnome.genmarshal()
329 https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
330GObject GLIB-GENMARSHAL(1)