1GLIB-MKENUMS(1)                  User Commands                 GLIB-MKENUMS(1)
2
3
4

NAME

6       glib-mkenums - C language enum description generation utility
7

SYNOPSIS

9       glib-mkenums [OPTION...] [FILE...]
10

DESCRIPTION

12       glib-mkenums is a small utility that parses C code to extract enum
13       definitions and produces enum descriptions based on text templates
14       specified by the user. Typically, you can use this tool to generate
15       enumeration types for the GType type system, for #GObject properties
16       and signal marshalling; additionally, you can use it to generate
17       enumeration values of #GSettings schemas.
18
19       glib-mkenums takes a list of valid C code files as input. The options
20       specified control the text that generated, substituting various
21       keywords enclosed in @ characters in the templates.
22
23   Production text substitutions
24       Certain keywords enclosed in @ characters will be substituted in the
25       emitted text. For the substitution examples of the keywords below, the
26       following example enum definition is assumed:
27
28       @EnumName@
29           The name of the enum currently being processed, enum names are
30           assumed to be properly namespaced and to use mixed capitalization
31           to separate words (e.g.  PrefixTheXEnum).
32
33       @enum_name@
34           The enum name with words lowercase and word-separated by
35           underscores (e.g.  prefix_the_xenum).
36
37       @ENUMNAME@
38           The enum name with words uppercase and word-separated by
39           underscores (e.g.  PREFIX_THE_XENUM).
40
41       @ENUMSHORT@
42           The enum name with words uppercase and word-separated by
43           underscores, prefix stripped (e.g.  THE_XENUM).
44
45       @ENUMPREFIX@
46           The prefix of the enum name (e.g.  PREFIX).
47
48       @VALUENAME@
49           The enum value name currently being processed with words uppercase
50           and word-separated by underscores, this is the assumed literal
51           notation of enum values in the C sources (e.g.  PREFIX_THE_XVALUE).
52
53       @valuenick@
54           A nick name for the enum value currently being processed, this is
55           usually generated by stripping common prefix words of all the enum
56           values of the current enum, the words are lowercase and underscores
57           are substituted by a minus (e.g.  the-xvalue).
58
59       @valuenum@
60           The integer value for the enum value currently being processed. If
61           the evaluation fails then glib-mkenums will exit with an error
62           status, but this only happens if @valuenum@ appears in your value
63           production template. (Since: 2.26)
64
65       @type@
66           This is substituted either by "enum" or "flags", depending on
67           whether the enum value definitions contained bit-shift operators or
68           not (e.g. flags).
69
70       @Type@
71           The same as @type@ with the first letter capitalized (e.g. Flags).
72
73       @TYPE@
74           The same as @type@ with all letters uppercased (e.g. FLAGS).
75
76       @filename@
77           The name of the input file currently being processed (e.g. foo.h).
78
79       @basename@
80           The base name of the input file currently being processed (e.g.
81           foo.h). Typically you want to use @basename@ in place of @filename@
82           in your templates, to improve the reproducibility of the build.
83           (Since: 2.22)
84
85   Trigraph extensions
86       Some C comments are treated specially in the parsed enum definitions,
87       such comments start out with the trigraph sequence /*< and end with the
88       trigraph sequence >*/. Per enum definition, the options "skip" and
89       "flags" can be specified, to indicate this enum definition to be
90       skipped, or for it to be treated as a flags definition, or to specify
91       the common prefix to be stripped from all values to generate value
92       nicknames, respectively. The "underscore_name" option can be used to
93       specify the word separation used in the *_get_type() function. For
94       instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.
95
96       Per value definition, the options "skip" and "nick" are supported. The
97       former causes the value to be skipped, and the latter can be used to
98       specify the otherwise auto-generated nickname. Examples:
99

OPTIONS

101       --fhead TEXT
102           Emits TEXT prior to processing input files.
103
104           You can specify this option multiple times, and the TEXT will be
105           concatenated.
106
107           When used along with a template file, TEXT will be prepended to the
108           template's file-header section.
109
110       --fprod TEXT
111           Emits TEXT every time a new input file is being processed.
112
113           You can specify this option multiple times, and the TEXT will be
114           concatenated.
115
116           When used along with a template file, TEXT will be appended to the
117           template's file-production section.
118
119       --ftail TEXT
120           Emits TEXT after all input files have been processed.
121
122           You can specify this option multiple times, and the TEXT will be
123           concatenated.
124
125           When used along with a template file, TEXT will be appended to the
126           template's file-tail section.
127
128       --eprod TEXT
129           Emits TEXT everytime an enum is encountered in the input files.
130
131       --vhead TEXT
132           Emits TEXT before iterating over the set of values of an enum.
133
134           You can specify this option multiple times, and the TEXT will be
135           concatenated.
136
137           When used along with a template file, TEXT will be prepended to the
138           template's value-header section.
139
140       --vprod TEXT
141           Emits TEXT for every value of an enum.
142
143           You can specify this option multiple times, and the TEXT will be
144           concatenated.
145
146           When used along with a template file, TEXT will be appended to the
147           template's value-production section.
148
149       --vtail TEXT
150           Emits TEXT after iterating over all values of an enum.
151
152           You can specify this option multiple times, and the TEXT will be
153           concatenated.
154
155           When used along with a template file, TEXT will be appended to the
156           template's value-tail section.
157
158       --comments TEXT
159           Template for auto-generated comments, the default (for C code
160           generations) is "/* @comment@ */".
161
162       --template FILE
163           Read templates from the given file. The templates are enclosed in
164           specially-formatted C comments
165           where section may be file-header, file-production, file-tail,
166           enumeration-production, value-header, value-production, value-tail
167           or comment.
168
169       --identifier-prefix PREFIX
170           Indicates what portion of the enum name should be intepreted as the
171           prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this will be
172           figured out automatically, but you may need to override the default
173           if your namespace is capitalized oddly.
174
175       --symbol-prefix PREFIX
176           Indicates what prefix should be used to correspond to the
177           identifier prefix in related C function names (eg, the "gtk" in
178           "gtk_direction_type_get_type". Equivalently, this is the lowercase
179           version of the prefix component of the enum value names (eg, the
180           "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
181           converted to lowercase.
182
183       --help
184           Print brief help and exit.
185
186       --version
187           Print version and exit.
188
189       --output=FILE
190           Write output to FILE instead of stdout.
191

USING GLIB-MKENUMS WITH AUTOTOOLS

193       In order to use glib-mkenums in your project when using Autotools as
194       the build system, you will first need to modify your configure.ac file
195       to ensure you find the appropriate command using pkg-config, similarly
196       as to how you discover the compiler and linker flags for GLib.
197
198           PKG_PROG_PKG_CONFIG([0.28])
199
200           PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
201
202       In your Makefile.am file you will typically use rules like these:
203
204           # A list of headers to inspect
205           project_headers = \
206                   project-foo.h \
207                   project-bar.h \
208                   project-baz.h
209
210           enum-types.h: $(project_headers) enum-types.h.in
211                   $(AM_V_GEN)$(GLIB_MKENUMS) \
212                           --template=enum-types.h.in \
213                           --output=$@ \
214                           $(project_headers)
215
216           enum-types.c: $(project_headers) enum-types.c.in enum-types.h
217                   $(AM_V_GEN)$(GLIB_MKENUMS) \
218                           --template=enum-types.c.in \
219                           --output=$@ \
220                           $(project_headers)
221
222           BUILT_SOURCES += enum-types.h enum-types.c
223           CLEANFILES += enum-types.h enum-types.c
224           EXTRA_DIST += enum-types.h.in enum-types.c.in
225
226       In the example above, we have a variable called project_headers where
227       we reference all header files we want to inspect for generating
228       enumeration GTypes. In the enum-types.h rule we use glib-mkenums with a
229       template called enum-types.h.in in order to generate the header file; a
230       header template file will typically look like this:
231
232           /*** BEGIN file-header ***/
233           #pragma once
234
235           /* Include the main project header */
236           #include "project.h"
237
238           G_BEGIN_DECLS
239           /*** END file-header ***/
240
241           /*** BEGIN file-production ***/
242
243           /* enumerations from "@filename@" */
244           /*** END file-production ***/
245
246           /*** BEGIN value-header ***/
247           GType @enum_name@_get_type (void) G_GNUC_CONST;
248           #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
249           /*** END value-header ***/
250
251           /*** BEGIN file-tail ***/
252           G_END_DECLS
253           /*** END file-tail ***/
254
255       The enum-types.c rule is similar to the rule for the header file, but
256       will use a different enum-types.c.in template file, similar to this:
257
258           /*** BEGIN file-header ***/
259           #include "config.h"
260           #include "enum-types.h"
261
262           /*** END file-header ***/
263
264           /*** BEGIN file-production ***/
265           /* enumerations from "@filename@" */
266           /*** END file-production ***/
267
268           /*** BEGIN value-header ***/
269           GType
270           @enum_name@_get_type (void)
271           {
272             static volatile gsize g_@type@_type_id__volatile;
273
274             if (g_once_init_enter (&g_define_type_id__volatile))
275               {
276                 static const G@Type@Value values[] = {
277           /*** END value-header ***/
278
279           /*** BEGIN value-production ***/
280                       { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
281           /*** END value-production ***/
282
283           /*** BEGIN value-tail ***/
284                       { 0, NULL, NULL }
285                 };
286
287                 GType g_@type@_type_id =
288                   g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
289
290                 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
291               }
292             return g_@type@_type_id__volatile;
293           }
294
295           /*** END value-tail ***/
296

SEE ALSO

298       glib-genmarshal(1)
299
300
301
302GObject                                                        GLIB-MKENUMS(1)
Impressum