docs/reference/gobject/glib-genmarshal.xml

   1 <refentry id="glib-genmarshal" lang="en">
   2
   3 <refentryinfo>
   4   <title>glib-genmarshal</title>
   5   <productname>GObject</productname>
   6   <authorgroup>
   7     <author>
   8       <contrib>Developer</contrib>
   9       <firstname>Emmanuele</firstname>
  10       <surname>Bassi</surname>
  11     </author>
  12     <author>
  13       <contrib>Original developer</contrib>
  14       <firstname>Tim</firstname>
  15       <surname>Janik</surname>
  16     </author>
  17   </authorgroup>
  18 </refentryinfo>
  19
  20 <refmeta>
  21 <refentrytitle>glib-genmarshal</refentrytitle>
  22 <manvolnum>1</manvolnum>
  23 <refmiscinfo class="manual">User Commands</refmiscinfo>
  24 </refmeta>
  25
  26 <refnamediv>
  27 <refname>glib-genmarshal</refname>
  28 <refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
  29 </refnamediv>
  30
  31 <refsynopsisdiv>
  32 <cmdsynopsis>
  33 <command>glib-genmarshal</command>
  34 <arg choice="opt" rep="repeat">OPTION</arg>
  35 <arg choice="opt" rep="repeat">FILE</arg>
  36 </cmdsynopsis>
  37 </refsynopsisdiv>
  38
  39 <refsect1><title>Description</title>
  40 <para><command>glib-genmarshal</command> is a small utility that generates C code
  41 marshallers for callback functions of the GClosure mechanism in the GObject
  42 sublibrary of GLib. The marshaller functions have a standard signature,
  43 they get passed in the invoking closure, an array of value structures holding
  44 the callback function parameters and a value structure for the return value
  45 of the callback. The marshaller is then responsible to call the respective C
  46 code function of the closure with all the parameters on the stack and to
  47 collect its return value.
  48 </para>
  49
  50 <para><command>glib-genmarshal</command> takes a list of marshallers to generate as
  51 input. The marshaller list is either read from files passed as additional arguments
  52 on the command line; or from standard input, by using <literal>-</literal> as the
  53 input file.
  54 </para>
  55
  56 <refsect2><title>Marshaller list format</title>
  57 <para>
  58 The marshaller lists are processed line by line, a line can contain a
  59 comment in the form of
  60 <informalexample><programlisting>
  61 # this is a comment
  62 </programlisting></informalexample>
  63 or a marshaller specification of the form
  64 <programlisting>
  65 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
  66 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
  67 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
  68 </programlisting>
  69 </para>
  70 <para>
  71 The <replaceable>RTYPE</replaceable> part specifies the callback's return
  72 type and the <replaceable>PTYPE</replaceable>s right to the colon specify
  73 the callback's parameter list, except for the first and the last arguments
  74 which are always pointers.
  75 </para>
  76 </refsect2>
  77 <refsect2><title>Parameter types</title>
  78 <para>
  79 Currently, the following types are supported:
  80 <variablelist>
  81 <varlistentry>
  82 <term><replaceable>VOID</replaceable></term>
  83 <listitem><para>
  84 indicates no return type, or no extra parameters.
  85 If <replaceable>VOID</replaceable> is used as the parameter list, no
  86 additional parameters may be present.
  87 </para></listitem>
  88 </varlistentry>
  89
  90 <varlistentry>
  91 <term><replaceable>BOOLEAN</replaceable></term>
  92 <listitem><para>
  93 for boolean types (gboolean)
  94 </para></listitem>
  95 </varlistentry>
  96
  97 <varlistentry>
  98 <term><replaceable>CHAR</replaceable></term>
  99 <listitem><para>
 100 for signed char types (gchar)
 101 </para></listitem>
 102 </varlistentry>
 103
 104 <varlistentry>
 105 <term><replaceable>UCHAR</replaceable></term>
 106 <listitem><para>
 107 for unsigned char types (guchar)
 108 </para></listitem>
 109 </varlistentry>
 110
 111 <varlistentry>
 112 <term><replaceable>INT</replaceable></term>
 113 <listitem><para>
 114 for signed integer types (gint)
 115 </para></listitem>
 116 </varlistentry>
 117
 118 <varlistentry>
 119 <term><replaceable>UINT</replaceable></term>
 120 <listitem><para>
 121 for unsigned integer types (guint)
 122 </para></listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term><replaceable>LONG</replaceable></term>
 127 <listitem><para>
 128 for signed long integer types (glong)
 129 </para></listitem>
 130 </varlistentry>
 131
 132 <varlistentry>
 133 <term><replaceable>ULONG</replaceable></term>
 134 <listitem><para>
 135 for unsigned long integer types (gulong)
 136 </para></listitem>
 137 </varlistentry>
 138
 139 <varlistentry>
 140 <term><replaceable>INT64</replaceable></term>
 141 <listitem><para>
 142 for signed 64bit integer types (gint64)
 143 </para></listitem>
 144 </varlistentry>
 145
 146 <varlistentry>
 147 <term><replaceable>UINT64</replaceable></term>
 148 <listitem><para>
 149 for unsigned 64bit integer types (guint64)
 150 </para></listitem>
 151 </varlistentry>
 152
 153 <varlistentry>
 154 <term><replaceable>ENUM</replaceable></term>
 155 <listitem><para>
 156 for enumeration types (gint)
 157 </para></listitem>
 158 </varlistentry>
 159
 160 <varlistentry>
 161 <term><replaceable>FLAGS</replaceable></term>
 162 <listitem><para>
 163 for flag enumeration types (guint)
 164 </para></listitem>
 165 </varlistentry>
 166
 167 <varlistentry>
 168 <term><replaceable>FLOAT</replaceable></term>
 169 <listitem><para>
 170 for single-precision float types (gfloat)
 171 </para></listitem>
 172 </varlistentry>
 173
 174 <varlistentry>
 175 <term><replaceable>DOUBLE</replaceable></term>
 176 <listitem><para>
 177 for double-precision float types (gdouble)
 178 </para></listitem>
 179 </varlistentry>
 180
 181 <varlistentry>
 182 <term><replaceable>STRING</replaceable></term>
 183 <listitem><para>
 184 for string types (gchar*)
 185 </para></listitem>
 186 </varlistentry>
 187
 188 <varlistentry>
 189 <term><replaceable>BOXED</replaceable></term>
 190 <listitem><para>
 191 for boxed (anonymous but reference counted) types (GBoxed*)
 192 </para></listitem>
 193 </varlistentry>
 194
 195 <varlistentry>
 196 <term><replaceable>PARAM</replaceable></term>
 197 <listitem><para>
 198 for GParamSpec or derived types (GParamSpec*)
 199 </para></listitem>
 200 </varlistentry>
 201
 202 <varlistentry>
 203 <term><replaceable>POINTER</replaceable></term>
 204 <listitem><para>
 205 for anonymous pointer types (gpointer)
 206 </para></listitem>
 207 </varlistentry>
 208
 209 <varlistentry>
 210 <term><replaceable>OBJECT</replaceable></term>
 211 <listitem><para>
 212 for GObject or derived types (GObject*)
 213 </para></listitem>
 214 </varlistentry>
 215
 216 <varlistentry>
 217 <term><replaceable>VARIANT</replaceable></term>
 218 <listitem><para>
 219 for GVariant types (GVariant*)
 220 </para></listitem>
 221 </varlistentry>
 222
 223 <varlistentry>
 224 <term><replaceable>NONE</replaceable></term>
 225 <listitem><para>
 226 deprecated alias for <replaceable>VOID</replaceable>
 227 </para></listitem>
 228 </varlistentry>
 229
 230 <varlistentry>
 231 <term><replaceable>BOOL</replaceable></term>
 232 <listitem><para>
 233 deprecated alias for <replaceable>BOOLEAN</replaceable>
 234 </para></listitem>
 235 </varlistentry>
 236 </variablelist>
 237 </para>
 238 </refsect2>
 239 </refsect1>
 240
 241 <refsect1><title>Options</title>
 242 <variablelist>
 243
 244 <varlistentry>
 245 <term><option>--header</option></term>
 246 <listitem><para>
 247 Generate header file contents of the marshallers. This option is mutually
 248 exclusive with the <option>--body</option> option.
 249 </para></listitem>
 250 </varlistentry>
 251
 252 <varlistentry>
 253 <term><option>--body</option></term>
 254 <listitem><para>
 255 Generate C code file contents of the marshallers. This option is mutually
 256 exclusive with the <option>--header</option> option.
 257 </para></listitem>
 258 </varlistentry>
 259
 260 <varlistentry>
 261 <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
 262 <listitem><para>
 263 Specify marshaller prefix. The default prefix is <literal>`g_cclosure_user_marshal'</literal>.
 264 </para></listitem>
 265 </varlistentry>
 266
 267 <varlistentry>
 268 <term><option>--skip-source</option></term>
 269 <listitem><para>
 270 Skip source location remarks in generated comments.
 271 </para></listitem>
 272 </varlistentry>
 273
 274 <varlistentry>
 275 <term><option>--stdinc</option></term>
 276 <listitem><para>
 277 Use the standard marshallers of the GObject library, and include
 278 <filename>glib-object.h</filename> in generated header files. This
 279 option is mutually exclusive with the <option>--nostdinc</option>
 280 option.
 281 </para></listitem>
 282 </varlistentry>
 283
 284 <varlistentry>
 285 <term><option>--nostdinc</option></term>
 286 <listitem><para>
 287 Do not use the standard marshallers of the GObject library, and skip
 288 <filename>glib-object.h</filename> include directive in generated header files.
 289 This option is mutually exclusive with the <option>--stdinc</option> option.
 290 </para></listitem>
 291 </varlistentry>
 292
 293 <varlistentry>
 294 <term><option>--internal</option></term>
 295 <listitem><para>
 296 Mark generated functions as internal, using <literal>G_GNUC_INTERNAL</literal>.
 297 </para></listitem>
 298 </varlistentry>
 299
 300 <varlistentry>
 301 <term><option>--valist-marshallers</option></term>
 302 <listitem><para>
 303 Generate valist marshallers, for use with <function>g_signal_set_va_marshaller()</function>.
 304 </para></listitem>
 305 </varlistentry>
 306
 307 <varlistentry>
 308 <term><option>-v</option>, <option>--version</option></term>
 309 <listitem><para>
 310 Print version information.
 311 </para></listitem>
 312 </varlistentry>
 313
 314 <varlistentry>
 315 <term><option>--g-fatal-warnings</option></term>
 316 <listitem><para>
 317 Make warnings fatal, that is, exit immediately once a warning occurs.
 318 </para></listitem>
 319 </varlistentry>
 320
 321 <varlistentry>
 322 <term><option>-h</option>, <option>--help</option></term>
 323 <listitem><para>
 324 Print brief help and exit.
 325 </para></listitem>
 326 </varlistentry>
 327
 328 <varlistentry>
 329 <term><option>-v</option>, <option>--version</option></term>
 330 <listitem><para>
 331 Print version and exit.
 332 </para></listitem>
 333 </varlistentry>
 334
 335 <varlistentry>
 336 <term><option>--output=FILE</option></term>
 337 <listitem><para>
 338 Write output to <replaceable>FILE</replaceable> instead of the standard output.
 339 </para></listitem>
 340 </varlistentry>
 341
 342 <varlistentry>
 343 <term><option>--prototypes</option></term>
 344 <listitem><para>
 345 Generate function prototypes before the function definition in the C source
 346 file, in order to avoid a <literal>missing-prototypes</literal> compiler
 347 warning. This option is only useful when using the <option>--body</option>
 348 option.
 349 </para></listitem>
 350 </varlistentry>
 351
 352 <varlistentry>
 353 <term><option>--pragma-once</option></term>
 354 <listitem><para>
 355 Use the <literal>once</literal> pragma instead of an old style header guard
 356 when generating the C header file. This option is only useful when using the
 357 <option>--header</option> option.
 358 </para></listitem>
 359 </varlistentry>
 360
 361 <varlistentry>
 362 <term><option>--include-header=<replaceable>HEADER</replaceable></option></term>
 363 <listitem><para>
 364 Adds a <literal>#include</literal> directive for the given file in the C
 365 source file. This option is only useful when using the <option>--body</option>
 366 option.
 367 </para></listitem>
 368 </varlistentry>
 369
 370 <varlistentry>
 371 <term><option>-D <replaceable>SYMBOL[=VALUE]</replaceable></option></term>
 372 <listitem><para>
 373 Adds a <literal>#define</literal> C pre-processor directive for
 374 <replaceable>SYMBOL</replaceable> and its given <replaceable>VALUE</replaceable>,
 375 or "1" if the value is unset. You can use this option multiple times; if you do,
 376 all the symbols will be defined in the same order given on the command line, before
 377 the symbols undefined using the <option>-U</option> option. This option is only
 378 useful when using the <option>--body</option> option.
 379 </para></listitem>
 380 </varlistentry>
 381
 382 <varlistentry>
 383 <term><option>-U <replaceable>SYMBOL</replaceable></option></term>
 384 <listitem><para>
 385 Adds a <literal>#undef</literal> C pre-processor directive to undefine the
 386 given <replaceable>SYMBOL</replaceable>. You can use this option multiple times;
 387 if you do, all the symbols will be undefined in the same order given on the
 388 command line, after the symbols defined using the <option>-D</option> option.
 389 This option is only useful when using the <option>--body</option> option.
 390 </para></listitem>
 391 </varlistentry>
 392
 393 <varlistentry>
 394 <term><option>--quiet</option></term>
 395 <listitem><para>
 396 Minimizes the output of <command>glib-genmarshal</command>, by printing only
 397 warnings and errors. This option is mutually exclusive with the
 398 <option>--verbose</option> option.
 399 </para></listitem>
 400 </varlistentry>
 401
 402 <varlistentry>
 403 <term><option>--verbose</option></term>
 404 <listitem><para>
 405 Increases the verbosity of <command>glib-genmarshal</command>, by printing
 406 debugging information. This option is mutually exclusive with the
 407 <option>--quiet</option> option.
 408 </para></listitem>
 409 </varlistentry>
 410
 411 </variablelist>
 412 </refsect1>
 413
 414 <refsect1><title>Using <command>glib-genmarshal</command> with Meson</title>
 415 <para>
 416 Meson supports generating closure marshallers using <command>glib-genmarshal</command>
 417 out of the box in its "gnome" module.
 418 </para>
 419
 420 <para>
 421 In your <filename>meson.build</filename> file you will typically call the
 422 <literal>gnome.genmarshal()</literal> method with the source list of marshallers
 423 to generate:
 424 </para>
 425 <informalexample><programlisting>
 426 gnome = import('gnome')
 427 marshal_files = gnome.genmarshal('marshal',
 428   sources: 'marshal.list',
 429   internal: true,
 430 )
 431 </programlisting></informalexample>
 432 <para>
 433 The <literal>marshal_files</literal> variable will contain an array of two elements
 434 in the following order:
 435 </para>
 436 <itemizedlist>
 437   <listitem><para>a build target for the source file</para></listitem>
 438   <listitem><para>a build target for the header file</para></listitem>
 439 </itemizedlist>
 440 <para>
 441 You should use the returned objects to provide a dependency on every other
 442 build target that references the source or header file; for instance, if you
 443 are using the source to build a library:
 444 </para>
 445 <informalexample><programlisting>
 446 mainlib = library('project',
 447   sources: project_sources + marshal_files,
 448   ...
 449 )
 450 </programlisting></informalexample>
 451 <para>
 452 Additionally, if you are including the generated header file inside a build
 453 target that depends on the library you just built, you must ensure that the
 454 internal dependency includes the generated header as a required source file:
 455 </para>
 456 <informalexample><programlisting>
 457 mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
 458 </programlisting></informalexample>
 459 <para>
 460 You should not include the generated source file as well, otherwise it will
 461 be built separately for every target that depends on it, causing build
 462 failures. To know more about why all this is required, please refer to the
 463 <ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
 464 corresponding Meson FAQ entry</ulink>.
 465 </para>
 466 <para>
 467 For more information on how to use the method, see the
 468 <ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
 469 documentation for <literal>gnome.genmarshal()</literal></ulink>.
 470 </para>
 471 </refsect1>
 472
 473 <refsect1><title>Using <command>glib-genmarshal</command> with Autotools</title>
 474 <para>
 475 In order to use <command>glib-genmarshal</command> in your project when using
 476 Autotools as the build system, you will first need to modify your
 477 <filename>configure.ac</filename> file to ensure you find the appropriate
 478 command using <command>pkg-config</command>, similarly as to how you discover
 479 the compiler and linker flags for GLib.
 480 </para>
 481 <informalexample><programlisting>
 482 PKG_PROG_PKG_CONFIG([0.28])
 483
 484 PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
 485 </programlisting></informalexample>
 486 <para>
 487 In your <filename>Makefile.am</filename> file you will typically need very
 488 simple rules to generate the C files needed for the build.
 489 </para>
 490 <informalexample><programlisting>
 491 marshal.h: marshal.list
 492         $(AM_V_GEN)$(GLIB_GENMARSHAL) \
 493                 --header \
 494                 --output=$@ \
 495                 $&lt;
 496
 497 marshal.c: marshal.list marshal.h
 498         $(AM_V_GEN)$(GLIB_GENMARSHAL) \
 499                 --include-header=marshal.h \
 500                 --body \
 501                 --output=$@ \
 502                 $&lt;
 503
 504 BUILT_SOURCES += marshal.h marshal.c
 505 CLEANFILES += marshal.h marshal.c
 506 EXTRA_DIST += marshal.list
 507 </programlisting></informalexample>
 508 <para>
 509 In the example above, the first rule generates the header file and depends on
 510 a <filename>marshal.list</filename> file in order to regenerate the result in
 511 case the marshallers list is updated. The second rule generates the source file
 512 for the same <filename>marshal.list</filename>, and includes the file generated
 513 by the header rule.
 514 </para>
 515 </refsect1>
 516
 517 <refsect1><title>Example</title>
 518 <para>
 519 To generate marshallers for the following callback functions:
 520 </para>
 521 <informalexample><programlisting>
 522 void   foo (gpointer data1,
 523             gpointer data2);
 524 void   bar (gpointer data1,
 525             gint     param1,
 526             gpointer data2);
 527 gfloat baz (gpointer data1,
 528             gboolean param1,
 529             guchar   param2,
 530             gpointer data2);
 531 </programlisting></informalexample>
 532 <para>
 533 The <filename>marshaller.list</filename> file has to look like this:
 534 </para>
 535 <programlisting>
 536 VOID:VOID
 537 VOID:INT
 538 FLOAT:BOOLEAN,UCHAR
 539 </programlisting>
 540 <para>
 541 and you call glib-genmarshal like this:
 542 </para>
 543 <programlisting>
 544 glib-genmarshal --header marshaller.list > marshaller.h
 545 glib-genmarshal --body marshaller.list > marshaller.c
 546 </programlisting>
 547 <para>
 548 The generated marshallers have the arguments encoded in their function name.
 549 For this particular list, they are
 550 </para>
 551 <programlisting>
 552 g_cclosure_user_marshal_VOID__VOID(...),
 553 g_cclosure_user_marshal_VOID__INT(...),
 554 g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
 555 </programlisting>
 556 <para>
 557 They can be used directly for GClosures or be passed in as the
 558 GSignalCMarshaller c_marshaller; argument upon creation of signals:
 559 </para>
 560 <informalexample><programlisting>
 561 GClosure *cc_foo, *cc_bar, *cc_baz;
 562
 563 cc_foo = g_cclosure_new (NULL, foo, NULL);
 564 g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
 565 cc_bar = g_cclosure_new (NULL, bar, NULL);
 566 g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
 567 cc_baz = g_cclosure_new (NULL, baz, NULL);
 568 g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
 569 </programlisting></informalexample>
 570 </refsect1>
 571 <refsect1><title>See also</title>
 572 <para>
 573 <citerefentry>
 574 <refentrytitle>glib-mkenums</refentrytitle>
 575 <manvolnum>1</manvolnum>
 576 </citerefentry>
 577 </para>
 578 </refsect1>
 579 </refentry>