| <refentry id="glib-mkenums" lang="en"> |
| |
| <refentryinfo> |
| <title>gdbus</title> |
| <productname>GObject</productname> |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Owen</firstname> |
| <surname>Taylor</surname> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>glib-mkenums</refentrytitle> |
| <manvolnum>1</manvolnum> |
| <refmiscinfo class="manual">User Commands</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>glib-mkenums</refname> |
| <refpurpose>C language enum description generation utility</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>glib-mkenums</command> |
| <arg choice="opt" rep="repeat">OPTION</arg> |
| <arg choice="opt" rep="repeat">FILE</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1><title>Description</title> |
| <para><command>glib-mkenums</command> 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. |
| </para> |
| |
| <para><command>glib-mkenums</command> 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. |
| </para> |
| |
| <refsect2><title>Production text substitutions</title> |
| <para> |
| 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: |
| <informalexample><programlisting> |
| typedef enum |
| { |
| PREFIX_THE_XVALUE = 1 << 3, |
| PREFIX_ANOTHER_VALUE = 1 << 4 |
| } PrefixTheXEnum; |
| </programlisting></informalexample> |
| <variablelist> |
| <varlistentry> |
| <term>@EnumName@</term> |
| <listitem><para> |
| 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. <literal>PrefixTheXEnum</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@enum_name@</term> |
| <listitem><para> |
| The enum name with words lowercase and word-separated by underscores |
| (e.g. <literal>prefix_the_xenum</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@ENUMNAME@</term> |
| <listitem><para> |
| The enum name with words uppercase and word-separated by underscores |
| (e.g. <literal>PREFIX_THE_XENUM</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@ENUMSHORT@</term> |
| <listitem><para> |
| The enum name with words uppercase and word-separated by underscores, |
| prefix stripped (e.g. <literal>THE_XENUM</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@ENUMPREFIX@</term> |
| <listitem><para> |
| The prefix of the enum name (e.g. <literal>PREFIX</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@VALUENAME@</term> |
| <listitem><para> |
| 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. <literal>PREFIX_THE_XVALUE</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@valuenick@</term> |
| <listitem><para> |
| 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. <literal>the-xvalue</literal>). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@valuenum@</term> |
| <listitem><para> |
| The integer value for the enum value currently being processed. If the |
| evaluation fails then <command>glib-mkenums</command> will exit with an |
| error status, but this only happens if <literal>@valuenum@</literal> |
| appears in your value production template. (Since: 2.26) |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@type@</term> |
| <listitem><para> |
| This is substituted either by "enum" or "flags", depending on whether the |
| enum value definitions contained bit-shift operators or not (e.g. flags). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@Type@</term> |
| <listitem><para> |
| The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@TYPE@</term> |
| <listitem><para> |
| The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@filename@</term> |
| <listitem><para> |
| The name of the input file currently being processed (e.g. foo.h). |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>@basename@</term> |
| <listitem><para> |
| The base name of the input file currently being processed (e.g. foo.h). Typically |
| 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) |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| </refsect2> |
| <refsect2><title>Trigraph extensions</title> |
| <para> |
| Some C comments are treated specially in the parsed enum definitions, |
| such comments start out with the trigraph sequence <literal>/*<</literal> |
| and end with the trigraph sequence <literal>>*/</literal>. |
| 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, <literal>/*< underscore_name=gnome_vfs_uri_hide_options >*/</literal>. |
| </para> |
| <para> |
| 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: |
| <informalexample><programlisting> |
| typedef enum /*< skip >*/ |
| { |
| PREFIX_FOO |
| } PrefixThisEnumWillBeSkipped; |
| typedef enum /*< flags,prefix=PREFIX >*/ |
| { |
| PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ |
| PREFIX_THE_FIRST_VALUE, |
| PREFIX_THE_SECOND_VALUE, |
| PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ |
| } PrefixTheFlagsEnum; |
| </programlisting></informalexample> |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1><title>Options</title> |
| <variablelist> |
| |
| <varlistentry> |
| <term><option>--fhead</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> prior to processing input files. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be prepended to the template's <literal>file-header</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--fprod</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> every time a new input file |
| is being processed. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be appended to the template's <literal>file-production</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--ftail</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> after all input files have been |
| processed. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be appended to the template's <literal>file-tail</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--eprod</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> everytime an enum is encountered |
| in the input files. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--vhead</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> before iterating over the set of |
| values of an enum. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be prepended to the template's <literal>value-header</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--vprod</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> for every value of an enum. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be appended to the template's <literal>value-production</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--vtail</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Emits <replaceable>TEXT</replaceable> after iterating over all values |
| of an enum. |
| </para> |
| <para> |
| You can specify this option multiple times, and the <replaceable>TEXT</replaceable> |
| will be concatenated. |
| </para> |
| <para> |
| When used along with a template file, <replaceable>TEXT</replaceable> |
| will be appended to the template's <literal>value-tail</literal> section. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--comments</option> <replaceable>TEXT</replaceable></term> |
| <listitem><para> |
| Template for auto-generated comments, the default (for C code generations) is |
| <literal>"/* @comment@ */"</literal>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--template</option> <replaceable>FILE</replaceable></term> |
| <listitem><para> |
| Read templates from the given file. The templates are enclosed in |
| specially-formatted C comments |
| <informalexample><programlisting> |
| /*** BEGIN section ***/ |
| /*** END section ***/ |
| </programlisting></informalexample> |
| where section may be <literal>file-header</literal>, |
| <literal>file-production</literal>, <literal>file-tail</literal>, |
| <literal>enumeration-production</literal>, <literal>value-header</literal>, |
| <literal>value-production</literal>, <literal>value-tail</literal> or |
| <literal>comment</literal>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term> |
| <listitem><para> |
| Indicates what portion of the enum name should be intepreted as the |
| prefix (eg, the "<literal>Gtk</literal>" in |
| "<literal>GtkDirectionType</literal>"). Normally this will be figured |
| out automatically, but you may need to override the default if your |
| namespace is capitalized oddly. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term> |
| <listitem><para> |
| Indicates what prefix should be used to correspond to the identifier |
| prefix in related C function names (eg, the "<literal>gtk</literal>" |
| in "<literal>gtk_direction_type_get_type</literal>". Equivalently, |
| this is the lowercase version of the prefix component of the enum |
| value names (eg, the "<literal>GTK</literal>" in |
| "<literal>GTK_DIR_UP</literal>". The default value is the identifier |
| prefix, converted to lowercase. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--help</option></term> |
| <listitem><para> |
| Print brief help and exit. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--version</option></term> |
| <listitem><para> |
| Print version and exit. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--output=FILE</option></term> |
| <listitem><para> |
| Write output to FILE instead of stdout. |
| </para></listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </refsect1> |
| |
| <refsect1><title>Using glib-mkenums with Autotools</title> |
| <para> |
| In order to use <command>glib-mkenums</command> in your project when using |
| Autotools as the build system, you will first need to modify your |
| <filename>configure.ac</filename> file to ensure you find the appropriate |
| command using <command>pkg-config</command>, similarly as to how you discover |
| the compiler and linker flags for GLib. |
| </para> |
| <informalexample><programlisting> |
| PKG_PROG_PKG_CONFIG([0.28]) |
| |
| PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums]) |
| </programlisting></informalexample> |
| <para> |
| In your <filename>Makefile.am</filename> file you will typically use rules |
| like these: |
| </para> |
| <informalexample><programlisting> |
| # 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 |
| </programlisting></informalexample> |
| <para> |
| In the example above, we have a variable called <literal>project_headers</literal> |
| where we reference all header files we want to inspect for generating enumeration |
| GTypes. In the <filename>enum-types.h</filename> rule we use <command>glib-mkenums</command> |
| with a template called <filename>enum-types.h.in</filename> in order to generate the |
| header file; a header template file will typically look like this: |
| </para> |
| <informalexample><programlisting> |
| /*** 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 ***/ |
| </programlisting></informalexample> |
| <para> |
| The <filename>enum-types.c</filename> rule is similar to the rule for the |
| header file, but will use a different <filename>enum-types.c.in</filename> template |
| file, similar to this: |
| </para> |
| <informalexample><programlisting> |
| /*** 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 ***/ |
| </programlisting></informalexample> |
| </refsect1> |
| |
| <refsect1><title>See also</title> |
| <para> |
| <citerefentry> |
| <refentrytitle>glib-genmarshal</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry> |
| </para> |
| </refsect1> |
| </refentry> |