docs/reference/gobject/glib-mkenums.xml

   1 <refentry id="glib-mkenums" lang="en">
   2
   3 <refentryinfo>
   4   <title>gdbus</title>
   5   <productname>GObject</productname>
   6   <authorgroup>
   7     <author>
   8       <contrib>Developer</contrib>
   9       <firstname>Owen</firstname>
  10       <surname>Taylor</surname>
  11     </author>
  12   </authorgroup>
  13 </refentryinfo>
  14
  15 <refmeta>
  16 <refentrytitle>glib-mkenums</refentrytitle>
  17 <manvolnum>1</manvolnum>
  18 <refmiscinfo class="manual">User Commands</refmiscinfo>
  19 </refmeta>
  20
  21 <refnamediv>
  22 <refname>glib-mkenums</refname>
  23 <refpurpose>C language enum description generation utility</refpurpose>
  24 </refnamediv>
  25
  26 <refsynopsisdiv>
  27 <cmdsynopsis>
  28 <command>glib-mkenums</command>
  29 <arg choice="opt" rep="repeat">OPTION</arg>
  30 <arg choice="opt" rep="repeat">FILE</arg>
  31 </cmdsynopsis>
  32 </refsynopsisdiv>
  33
  34 <refsect1><title>Description</title>
  35 <para><command>glib-mkenums</command> is a small utility that parses C code to
  36 extract enum definitions and produces enum descriptions based on text templates
  37 specified by the user. Typically, you can use this tool to generate enumeration
  38 types for the GType type system, for #GObject properties and signal marshalling;
  39 additionally, you can use it to generate enumeration values of #GSettings schemas.
  40 </para>
  41
  42 <para><command>glib-mkenums</command> takes a list of valid C code files as
  43 input. The options specified control the text that generated, substituting various
  44 keywords enclosed in @ characters in the templates.
  45 </para>
  46
  47 <refsect2><title>Production text substitutions</title>
  48 <para>
  49 Certain keywords enclosed in @ characters will be substituted in the
  50 emitted text. For the substitution examples of the keywords below,
  51 the following example enum definition is assumed:
  52 <informalexample><programlisting>
  53 typedef enum
  54 {
  55   PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
  56   PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
  57 } PrefixTheXEnum;
  58 </programlisting></informalexample>
  59 <variablelist>
  60 <varlistentry>
  61 <term>@EnumName@</term>
  62 <listitem><para>
  63 The name of the enum currently being processed, enum names are assumed to be
  64 properly namespaced and to use mixed capitalization to separate
  65 words (e.g. <literal>PrefixTheXEnum</literal>).
  66 </para></listitem>
  67 </varlistentry>
  68
  69 <varlistentry>
  70 <term>@enum_name@</term>
  71 <listitem><para>
  72 The enum name with words lowercase and word-separated by underscores
  73 (e.g. <literal>prefix_the_xenum</literal>).
  74 </para></listitem>
  75 </varlistentry>
  76
  77 <varlistentry>
  78 <term>@ENUMNAME@</term>
  79 <listitem><para>
  80 The enum name with words uppercase and word-separated by underscores
  81 (e.g. <literal>PREFIX_THE_XENUM</literal>).
  82 </para></listitem>
  83 </varlistentry>
  84
  85 <varlistentry>
  86 <term>@ENUMSHORT@</term>
  87 <listitem><para>
  88 The enum name with words uppercase and word-separated by underscores,
  89 prefix stripped (e.g. <literal>THE_XENUM</literal>).
  90 </para></listitem>
  91 </varlistentry>
  92
  93 <varlistentry>
  94 <term>@ENUMPREFIX@</term>
  95 <listitem><para>
  96 The prefix of the enum name (e.g. <literal>PREFIX</literal>).
  97 </para></listitem>
  98 </varlistentry>
  99
 100 <varlistentry>
 101 <term>@VALUENAME@</term>
 102 <listitem><para>
 103 The enum value name currently being processed with words uppercase and
 104 word-separated by underscores,
 105 this is the assumed literal notation of enum values in the C sources
 106 (e.g. <literal>PREFIX_THE_XVALUE</literal>).
 107 </para></listitem>
 108 </varlistentry>
 109
 110 <varlistentry>
 111 <term>@valuenick@</term>
 112 <listitem><para>
 113 A nick name for the enum value currently being processed, this is usually
 114 generated by stripping common prefix words of all the enum values of the
 115 current enum, the words are lowercase and underscores are substituted by a
 116 minus (e.g. <literal>the-xvalue</literal>).
 117 </para></listitem>
 118 </varlistentry>
 119
 120 <varlistentry>
 121 <term>@valuenum@</term>
 122 <listitem><para>
 123 The integer value for the enum value currently being processed. If the
 124 evaluation fails then <command>glib-mkenums</command> will exit with an
 125 error status, but this only happens if <literal>@valuenum@</literal>
 126 appears in your value production template. (Since: 2.26)
 127 </para></listitem>
 128 </varlistentry>
 129
 130 <varlistentry>
 131 <term>@type@</term>
 132 <listitem><para>
 133 This is substituted either by "enum" or "flags", depending on whether the
 134 enum value definitions contained bit-shift operators or not (e.g. flags).
 135 </para></listitem>
 136 </varlistentry>
 137
 138 <varlistentry>
 139 <term>@Type@</term>
 140 <listitem><para>
 141 The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
 142 </para></listitem>
 143 </varlistentry>
 144
 145 <varlistentry>
 146 <term>@TYPE@</term>
 147 <listitem><para>
 148 The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
 149 </para></listitem>
 150 </varlistentry>
 151
 152 <varlistentry>
 153 <term>@filename@</term>
 154 <listitem><para>
 155 The name of the input file currently being processed (e.g. foo.h).
 156 </para></listitem>
 157 </varlistentry>
 158
 159 <varlistentry>
 160 <term>@basename@</term>
 161 <listitem><para>
 162 The base name of the input file currently being processed (e.g. foo.h). Typically
 163 you want to use <literal>@basename@</literal> in place of <literal>@filename@</literal> in your templates, to improve the reproducibility of the build. (Since: 2.22)
 164 </para></listitem>
 165 </varlistentry>
 166 </variablelist>
 167 </para>
 168 </refsect2>
 169 <refsect2><title>Trigraph extensions</title>
 170 <para>
 171 Some C comments are treated specially in the parsed enum definitions,
 172 such comments start out with the trigraph sequence <literal>/*&lt;</literal>
 173 and end with the trigraph sequence <literal>&gt;*/</literal>.
 174 Per enum definition, the options "skip" and "flags" can be specified, to
 175 indicate this enum definition to be skipped, or for it to be treated as
 176 a flags definition, or to specify the common prefix to be stripped from
 177 all values to generate value nicknames, respectively. The "underscore_name"
 178 option can be used to specify the word separation used in the *_get_type()
 179 function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
 180 </para>
 181 <para>
 182 Per value definition, the options "skip" and "nick" are supported.
 183 The former causes the value to be skipped, and the latter can be used to
 184 specify the otherwise auto-generated nickname.
 185 Examples:
 186 <informalexample><programlisting>
 187 typedef enum /*&lt; skip &gt;*/
 188 {
 189   PREFIX_FOO
 190 } PrefixThisEnumWillBeSkipped;
 191 typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
 192 {
 193   PREFIX_THE_ZEROTH_VALUE,      /*&lt; skip &gt;*/
 194   PREFIX_THE_FIRST_VALUE,
 195   PREFIX_THE_SECOND_VALUE,
 196   PREFIX_THE_THIRD_VALUE,       /*&lt; nick=the-last-value &gt;*/
 197 } PrefixTheFlagsEnum;
 198 </programlisting></informalexample>
 199 </para>
 200 </refsect2>
 201 </refsect1>
 202
 203 <refsect1><title>Options</title>
 204 <variablelist>
 205
 206 <varlistentry>
 207 <term><option>--fhead</option> <replaceable>TEXT</replaceable></term>
 208 <listitem><para>
 209 Emits <replaceable>TEXT</replaceable> prior to processing input files.
 210 </para>
 211 <para>
 212 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 213 will be concatenated.
 214 </para>
 215 <para>
 216 When used along with a template file, <replaceable>TEXT</replaceable>
 217 will be prepended to the template's <literal>file-header</literal> section.
 218 </para></listitem>
 219 </varlistentry>
 220
 221 <varlistentry>
 222 <term><option>--fprod</option> <replaceable>TEXT</replaceable></term>
 223 <listitem><para>
 224 Emits <replaceable>TEXT</replaceable> every time a new input file
 225 is being processed.
 226 </para>
 227 <para>
 228 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 229 will be concatenated.
 230 </para>
 231 <para>
 232 When used along with a template file, <replaceable>TEXT</replaceable>
 233 will be appended to the template's <literal>file-production</literal> section.
 234 </para></listitem>
 235 </varlistentry>
 236
 237 <varlistentry>
 238 <term><option>--ftail</option> <replaceable>TEXT</replaceable></term>
 239 <listitem><para>
 240 Emits <replaceable>TEXT</replaceable> after all input files have been
 241 processed.
 242 </para>
 243 <para>
 244 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 245 will be concatenated.
 246 </para>
 247 <para>
 248 When used along with a template file, <replaceable>TEXT</replaceable>
 249 will be appended to the template's <literal>file-tail</literal> section.
 250 </para></listitem>
 251 </varlistentry>
 252
 253 <varlistentry>
 254 <term><option>--eprod</option> <replaceable>TEXT</replaceable></term>
 255 <listitem><para>
 256 Emits <replaceable>TEXT</replaceable> everytime an enum is encountered
 257 in the input files.
 258 </para></listitem>
 259 </varlistentry>
 260
 261 <varlistentry>
 262 <term><option>--vhead</option> <replaceable>TEXT</replaceable></term>
 263 <listitem><para>
 264 Emits <replaceable>TEXT</replaceable> before iterating over the set of
 265 values of an enum.
 266 </para>
 267 <para>
 268 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 269 will be concatenated.
 270 </para>
 271 <para>
 272 When used along with a template file, <replaceable>TEXT</replaceable>
 273 will be prepended to the template's <literal>value-header</literal> section.
 274 </para></listitem>
 275 </varlistentry>
 276
 277 <varlistentry>
 278 <term><option>--vprod</option> <replaceable>TEXT</replaceable></term>
 279 <listitem><para>
 280 Emits <replaceable>TEXT</replaceable> for every value of an enum.
 281 </para>
 282 <para>
 283 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 284 will be concatenated.
 285 </para>
 286 <para>
 287 When used along with a template file, <replaceable>TEXT</replaceable>
 288 will be appended to the template's <literal>value-production</literal> section.
 289 </para></listitem>
 290 </varlistentry>
 291
 292 <varlistentry>
 293 <term><option>--vtail</option> <replaceable>TEXT</replaceable></term>
 294 <listitem><para>
 295 Emits <replaceable>TEXT</replaceable> after iterating over all values
 296 of an enum.
 297 </para>
 298 <para>
 299 You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
 300 will be concatenated.
 301 </para>
 302 <para>
 303 When used along with a template file, <replaceable>TEXT</replaceable>
 304 will be appended to the template's <literal>value-tail</literal> section.
 305 </para></listitem>
 306 </varlistentry>
 307
 308 <varlistentry>
 309 <term><option>--comments</option> <replaceable>TEXT</replaceable></term>
 310 <listitem><para>
 311 Template for auto-generated comments, the default (for C code generations) is
 312 <literal>"/* @comment@ */"</literal>.
 313 </para></listitem>
 314 </varlistentry>
 315
 316 <varlistentry>
 317 <term><option>--template</option> <replaceable>FILE</replaceable></term>
 318 <listitem><para>
 319 Read templates from the given file. The templates are enclosed in
 320 specially-formatted C comments
 321 <informalexample><programlisting>
 322 /*** BEGIN section ***/
 323 /*** END section ***/
 324 </programlisting></informalexample>
 325 where section may be <literal>file-header</literal>,
 326 <literal>file-production</literal>, <literal>file-tail</literal>,
 327 <literal>enumeration-production</literal>, <literal>value-header</literal>,
 328 <literal>value-production</literal>, <literal>value-tail</literal> or
 329 <literal>comment</literal>.
 330 </para></listitem>
 331 </varlistentry>
 332
 333 <varlistentry>
 334 <term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term>
 335 <listitem><para>
 336 Indicates what portion of the enum name should be intepreted as the
 337 prefix (eg, the "<literal>Gtk</literal>" in
 338 "<literal>GtkDirectionType</literal>"). Normally this will be figured
 339 out automatically, but you may need to override the default if your
 340 namespace is capitalized oddly.
 341 </para></listitem>
 342 </varlistentry>
 343
 344 <varlistentry>
 345 <term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term>
 346 <listitem><para>
 347 Indicates what prefix should be used to correspond to the identifier
 348 prefix in related C function names (eg, the "<literal>gtk</literal>"
 349 in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
 350 this is the lowercase version of the prefix component of the enum
 351 value names (eg, the "<literal>GTK</literal>" in
 352 "<literal>GTK_DIR_UP</literal>". The default value is the identifier
 353 prefix, converted to lowercase.
 354 </para></listitem>
 355 </varlistentry>
 356
 357 <varlistentry>
 358 <term><option>--help</option></term>
 359 <listitem><para>
 360 Print brief help and exit.
 361 </para></listitem>
 362 </varlistentry>
 363
 364 <varlistentry>
 365 <term><option>--version</option></term>
 366 <listitem><para>
 367 Print version and exit.
 368 </para></listitem>
 369 </varlistentry>
 370
 371 <varlistentry>
 372 <term><option>--output=FILE</option></term>
 373 <listitem><para>
 374 Write output to FILE instead of stdout.
 375 </para></listitem>
 376 </varlistentry>
 377
 378 </variablelist>
 379 </refsect1>
 380
 381 <refsect1><title>Using glib-mkenums with Autotools</title>
 382 <para>
 383 In order to use <command>glib-mkenums</command> in your project when using
 384 Autotools as the build system, you will first need to modify your
 385 <filename>configure.ac</filename> file to ensure you find the appropriate
 386 command using <command>pkg-config</command>, similarly as to how you discover
 387 the compiler and linker flags for GLib.
 388 </para>
 389 <informalexample><programlisting>
 390 PKG_PROG_PKG_CONFIG([0.28])
 391
 392 PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
 393 </programlisting></informalexample>
 394 <para>
 395 In your <filename>Makefile.am</filename> file you will typically use rules
 396 like these:
 397 </para>
 398 <informalexample><programlisting>
 399 # A list of headers to inspect
 400 project_headers = \
 401         project-foo.h \
 402         project-bar.h \
 403         project-baz.h
 404
 405 enum-types.h: $(project_headers) enum-types.h.in
 406         $(AM_V_GEN)$(GLIB_MKENUMS) \
 407                 --template=enum-types.h.in \
 408                 --output=$@ \
 409                 $(project_headers)
 410
 411 enum-types.c: $(project_headers) enum-types.c.in enum-types.h
 412         $(AM_V_GEN)$(GLIB_MKENUMS) \
 413                 --template=enum-types.c.in \
 414                 --output=$@ \
 415                 $(project_headers)
 416
 417 BUILT_SOURCES += enum-types.h enum-types.c
 418 CLEANFILES += enum-types.h enum-types.c
 419 EXTRA_DIST += enum-types.h.in enum-types.c.in
 420 </programlisting></informalexample>
 421 <para>
 422 In the example above, we have a variable called <literal>project_headers</literal>
 423 where we reference all header files we want to inspect for generating enumeration
 424 GTypes. In the <filename>enum-types.h</filename> rule we use <command>glib-mkenums</command>
 425 with a template called <filename>enum-types.h.in</filename> in order to generate the
 426 header file; a header template file will typically look like this:
 427 </para>
 428 <informalexample><programlisting>
 429 /*** BEGIN file-header ***/
 430 #pragma once
 431
 432 /* Include the main project header */
 433 #include "project.h"
 434
 435 G_BEGIN_DECLS
 436 /*** END file-header ***/
 437
 438 /*** BEGIN file-production ***/
 439
 440 /* enumerations from "@filename@" */
 441 /*** END file-production ***/
 442
 443 /*** BEGIN value-header ***/
 444 GType @enum_name@_get_type (void) G_GNUC_CONST;
 445 #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
 446 /*** END value-header ***/
 447
 448 /*** BEGIN file-tail ***/
 449 G_END_DECLS
 450 /*** END file-tail ***/
 451 </programlisting></informalexample>
 452 <para>
 453 The <filename>enum-types.c</filename> rule is similar to the rule for the
 454 header file, but will use a different <filename>enum-types.c.in</filename> template
 455 file, similar to this:
 456 </para>
 457 <informalexample><programlisting>
 458 /*** BEGIN file-header ***/
 459 #include "config.h"
 460 #include "enum-types.h"
 461
 462 /*** END file-header ***/
 463
 464 /*** BEGIN file-production ***/
 465 /* enumerations from "@filename@" */
 466 /*** END file-production ***/
 467
 468 /*** BEGIN value-header ***/
 469 GType
 470 @enum_name@_get_type (void)
 471 {
 472   static volatile gsize g_@type@_type_id__volatile;
 473
 474   if (g_once_init_enter (&amp;g_define_type_id__volatile))
 475     {
 476       static const G@Type@Value values[] = {
 477 /*** END value-header ***/
 478
 479 /*** BEGIN value-production ***/
 480             { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
 481 /*** END value-production ***/
 482
 483 /*** BEGIN value-tail ***/
 484             { 0, NULL, NULL }
 485       };
 486
 487       GType g_@type@_type_id =
 488         g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
 489
 490       g_once_init_leave (&amp;g_@type@_type_id__volatile, g_@type@_type_id);
 491     }
 492   return g_@type@_type_id__volatile;
 493 }
 494
 495 /*** END value-tail ***/
 496 </programlisting></informalexample>
 497 </refsect1>
 498
 499 <refsect1><title>See also</title>
 500 <para>
 501 <citerefentry>
 502 <refentrytitle>glib-genmarshal</refentrytitle>
 503 <manvolnum>1</manvolnum>
 504 </citerefentry>
 505 </para>
 506 </refsect1>
 507 </refentry>