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 glib-genmarshal with Autotools</title>
 415 <para>
 416 In order to use <command>glib-genmarshal</command> in your project when using
 417 Autotools as the build system, you will first need to modify your
 418 <filename>configure.ac</filename> file to ensure you find the appropriate
 419 command using <command>pkg-config</command>, similarly as to how you discover
 420 the compiler and linker flags for GLib.
 421 </para>
 422 <informalexample><programlisting>
 423 PKG_PROG_PKG_CONFIG([0.28])
 424
 425 PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
 426 </programlisting></informalexample>
 427 <para>
 428 In your <filename>Makefile.am</filename> file you will typically need very
 429 simple rules to generate the C files needed for the build.
 430 </para>
 431 <informalexample><programlisting>
 432 marshal.h: marshal.list
 433         $(AM_V_GEN)$(GLIB_GENMARSHAL) \
 434                 --header \
 435                 --output=$@ \
 436                 $&lt;
 437
 438 marshal.c: marshal.list marshal.h
 439         $(AM_V_GEN)$(GLIB_GENMARSHAL) \
 440                 --include-header=marshal.h \
 441                 --body \
 442                 --output=$@ \
 443                 $&lt;
 444
 445 BUILT_SOURCES += marshal.h marshal.c
 446 CLEANFILES += marshal.h marshal.c
 447 EXTRA_DIST += marshal.list
 448 </programlisting></informalexample>
 449 <para>
 450 In the example above, the first rule generates the header file and depends on
 451 a <filename>marshal.list</filename> file in order to regenerate the result in
 452 case the marshallers list is updated. The second rule generates the source file
 453 for the same <filename>marshal.list</filename>, and includes the file generated
 454 by the header rule.
 455 </para>
 456 </refsect1>
 457
 458 <refsect1><title>Example</title>
 459 <para>
 460 To generate marshallers for the following callback functions:
 461 </para>
 462 <informalexample><programlisting>
 463 void   foo (gpointer data1,
 464             gpointer data2);
 465 void   bar (gpointer data1,
 466             gint     param1,
 467             gpointer data2);
 468 gfloat baz (gpointer data1,
 469             gboolean param1,
 470             guchar   param2,
 471             gpointer data2);
 472 </programlisting></informalexample>
 473 <para>
 474 The <filename>marshaller.list</filename> file has to look like this:
 475 </para>
 476 <programlisting>
 477 VOID:VOID
 478 VOID:INT
 479 FLOAT:BOOLEAN,UCHAR
 480 </programlisting>
 481 <para>
 482 and you call glib-genmarshal like this:
 483 </para>
 484 <programlisting>
 485 glib-genmarshal --header marshaller.list > marshaller.h
 486 glib-genmarshal --body marshaller.list > marshaller.c
 487 </programlisting>
 488 <para>
 489 The generated marshallers have the arguments encoded in their function name.
 490 For this particular list, they are
 491 </para>
 492 <programlisting>
 493 g_cclosure_user_marshal_VOID__VOID(...),
 494 g_cclosure_user_marshal_VOID__INT(...),
 495 g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
 496 </programlisting>
 497 <para>
 498 They can be used directly for GClosures or be passed in as the
 499 GSignalCMarshaller c_marshaller; argument upon creation of signals:
 500 </para>
 501 <informalexample><programlisting>
 502 GClosure *cc_foo, *cc_bar, *cc_baz;
 503
 504 cc_foo = g_cclosure_new (NULL, foo, NULL);
 505 g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
 506 cc_bar = g_cclosure_new (NULL, bar, NULL);
 507 g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
 508 cc_baz = g_cclosure_new (NULL, baz, NULL);
 509 g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
 510 </programlisting></informalexample>
 511 </refsect1>
 512 <refsect1><title>See also</title>
 513 <para>
 514 <citerefentry>
 515 <refentrytitle>glib-mkenums</refentrytitle>
 516 <manvolnum>1</manvolnum>
 517 </citerefentry>
 518 </para>
 519 </refsect1>
 520 </refentry>