DragonFly On-Line Manual Pages

GLIB-MKENUMS(1) 		 User Commands		       GLIB-MKENUMS(1)

NAME
       glib-mkenums - C language enum description generation utility

SYNOPSIS
       glib-mkenums [OPTION...] [FILE...]

DESCRIPTION
       glib-mkenums is a small utility that parses C code to extract enum
       definitions and produces enum descriptions based on text templates
       specified by the user. Typically, you can use this tool to generate
       enumeration types for the GType type system, for #GObject properties
       and signal marshalling; additionally, you can use it to generate
       enumeration values of #GSettings schemas.

       glib-mkenums takes a list of valid C code files as input. The options
       specified control the text that generated, substituting various
       keywords enclosed in @ characters in the templates.

   Production text substitutions
       Certain keywords enclosed in @ characters will be substituted in the
       emitted text. For the substitution examples of the keywords below, the
       following example enum definition is assumed:

       @EnumName@
	   The name of the enum currently being processed, enum names are
	   assumed to be properly namespaced and to use mixed capitalization
	   to separate words (e.g.  PrefixTheXEnum).

       @enum_name@
	   The enum name with words lowercase and word-separated by
	   underscores (e.g.  prefix_the_xenum).

       @ENUMNAME@
	   The enum name with words uppercase and word-separated by
	   underscores (e.g.  PREFIX_THE_XENUM).

       @ENUMSHORT@
	   The enum name with words uppercase and word-separated by
	   underscores, prefix stripped (e.g.  THE_XENUM).

       @ENUMPREFIX@
	   The prefix of the enum name (e.g.  PREFIX).

       @VALUENAME@
	   The enum value name currently being processed with words uppercase
	   and word-separated by underscores, this is the assumed literal
	   notation of enum values in the C sources (e.g.  PREFIX_THE_XVALUE).

       @valuenick@
	   A nick name for the enum value currently being processed, this is
	   usually generated by stripping common prefix words of all the enum
	   values of the current enum, the words are lowercase and underscores
	   are substituted by a minus (e.g.  the-xvalue).

       @valuenum@
	   The integer value for the enum value currently being processed. If
	   the evaluation fails then glib-mkenums will exit with an error
	   status, but this only happens if @valuenum@ appears in your value
	   production template. (Since: 2.26)

       @type@
	   This is substituted either by "enum" or "flags", depending on
	   whether the enum value definitions contained bit-shift operators or
	   not (e.g. flags).

       @Type@
	   The same as @type@ with the first letter capitalized (e.g. Flags).

       @TYPE@
	   The same as @type@ with all letters uppercased (e.g. FLAGS).

       @filename@
	   The name of the input file currently being processed (e.g. foo.h).

       @basename@
	   The base name of the input file currently being processed (e.g.
	   foo.h). Typically you want to use @basename@ in place of @filename@
	   in your templates, to improve the reproducibility of the build.
	   (Since: 2.22)

   Trigraph extensions
       Some C comments are treated specially in the parsed enum definitions,
       such comments start out with the trigraph sequence /*< and end with the
       trigraph sequence >*/. Per enum definition, the options "skip" and
       "flags" can be specified, to indicate this enum definition to be
       skipped, or for it to be treated as a flags definition, or to specify
       the common prefix to be stripped from all values to generate value
       nicknames, respectively. The "underscore_name" option can be used to
       specify the word separation used in the *_get_type() function. For
       instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.

       Per value definition, the options "skip" and "nick" are supported. The
       former causes the value to be skipped, and the latter can be used to
       specify the otherwise auto-generated nickname. Examples:

OPTIONS
       --fhead TEXT
	   Emits TEXT prior to processing input files.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be prepended to the
	   template's file-header section.

       --fprod TEXT
	   Emits TEXT every time a new input file is being processed.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be appended to the
	   template's file-production section.

       --ftail TEXT
	   Emits TEXT after all input files have been processed.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be appended to the
	   template's file-tail section.

       --eprod TEXT
	   Emits TEXT everytime an enum is encountered in the input files.

       --vhead TEXT
	   Emits TEXT before iterating over the set of values of an enum.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be prepended to the
	   template's value-header section.

       --vprod TEXT
	   Emits TEXT for every value of an enum.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be appended to the
	   template's value-production section.

       --vtail TEXT
	   Emits TEXT after iterating over all values of an enum.

	   You can specify this option multiple times, and the TEXT will be
	   concatenated.

	   When used along with a template file, TEXT will be appended to the
	   template's value-tail section.

       --comments TEXT
	   Template for auto-generated comments, the default (for C code
	   generations) is "/* @comment@ */".

       --template FILE
	   Read templates from the given file. The templates are enclosed in
	   specially-formatted C comments
	   where section may be file-header, file-production, file-tail,
	   enumeration-production, value-header, value-production, value-tail
	   or comment.

       --identifier-prefix PREFIX
	   Indicates what portion of the enum name should be intepreted as the
	   prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this will be
	   figured out automatically, but you may need to override the default
	   if your namespace is capitalized oddly.

       --symbol-prefix PREFIX
	   Indicates what prefix should be used to correspond to the
	   identifier prefix in related C function names (eg, the "gtk" in
	   "gtk_direction_type_get_type". Equivalently, this is the lowercase
	   version of the prefix component of the enum value names (eg, the
	   "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
	   converted to lowercase.

       --help
	   Print brief help and exit.

       --version
	   Print version and exit.

       --output=FILE
	   Write output to FILE instead of stdout.

USING GLIB-MKENUMS WITH AUTOTOOLS
       In order to use glib-mkenums in your project when using Autotools as
       the build system, you will first need to modify your configure.ac file
       to ensure you find the appropriate command using pkg-config, similarly
       as to how you discover the compiler and linker flags for GLib.

	   PKG_PROG_PKG_CONFIG([0.28])

	   PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])

       In your Makefile.am file you will typically use rules like these:

	   # A list of headers to inspect
	   project_headers = \
		   project-foo.h \
		   project-bar.h \
		   project-baz.h

	   enum-types.h: $(project_headers) enum-types.h.in
		   $(AM_V_GEN)$(GLIB_MKENUMS) \
			   --template=enum-types.h.in \
			   --output=$@ \
			   $(project_headers)

	   enum-types.c: $(project_headers) enum-types.c.in enum-types.h
		   $(AM_V_GEN)$(GLIB_MKENUMS) \
			   --template=enum-types.c.in \
			   --output=$@ \
			   $(project_headers)

	   BUILT_SOURCES += enum-types.h enum-types.c
	   CLEANFILES += enum-types.h enum-types.c
	   EXTRA_DIST += enum-types.h.in enum-types.c.in

       In the example above, we have a variable called project_headers where
       we reference all header files we want to inspect for generating
       enumeration GTypes. In the enum-types.h rule we use glib-mkenums with a
       template called enum-types.h.in in order to generate the header file; a
       header template file will typically look like this:

	   /*** BEGIN file-header ***/
	   #pragma once

	   /* Include the main project header */
	   #include "project.h"

	   G_BEGIN_DECLS
	   /*** END file-header ***/

	   /*** BEGIN file-production ***/

	   /* enumerations from "@filename@" */
	   /*** END file-production ***/

	   /*** BEGIN value-header ***/
	   GType @enum_name@_get_type (void) G_GNUC_CONST;
	   #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
	   /*** END value-header ***/

	   /*** BEGIN file-tail ***/
	   G_END_DECLS
	   /*** END file-tail ***/

       The enum-types.c rule is similar to the rule for the header file, but
       will use a different enum-types.c.in template file, similar to this:

	   /*** BEGIN file-header ***/
	   #include "config.h"
	   #include "enum-types.h"

	   /*** END file-header ***/

	   /*** BEGIN file-production ***/
	   /* enumerations from "@filename@" */
	   /*** END file-production ***/

	   /*** BEGIN value-header ***/
	   GType
	   @enum_name@_get_type (void)
	   {
	     static volatile gsize g_@type@_type_id__volatile;

	     if (g_once_init_enter (&g_define_type_id__volatile))
	       {
		 static const G@Type@Value values[] = {
	   /*** END value-header ***/

	   /*** BEGIN value-production ***/
		       { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
	   /*** END value-production ***/

	   /*** BEGIN value-tail ***/
		       { 0, NULL, NULL }
		 };

		 GType g_@type@_type_id =
		   g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);

		 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
	       }
	     return g_@type@_type_id__volatile;
	   }

	   /*** END value-tail ***/

SEE ALSO
       glib-genmarshal(1)

GObject 						       GLIB-MKENUMS(1)