glib-mkenums(1)



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)

Man(1) output converted with man2html
list of all man pages