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 and
16       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           typedef enum
29           {
30             PREFIX_THE_XVALUE    = 1 << 3,
31             PREFIX_ANOTHER_VALUE = 1 << 4
32           } PrefixTheXEnum;
33
34       @EnumName@>
35           The name of the enum currently being processed, enum names are
36           assumed to be properly namespaced and to use mixed capitalization
37           to separate words (e.g.  PrefixTheXEnum).
38
39       @enum_name@
40           The enum name with words lowercase and word-separated by
41           underscores (e.g.  prefix_the_xenum).
42
43       @ENUMNAME@
44           The enum name with words uppercase and word-separated by
45           underscores (e.g.  PREFIX_THE_XENUM).
46
47       @ENUMSHORT@
48           The enum name with words uppercase and word-separated by
49           underscores, prefix stripped (e.g.  THE_XENUM).
50
51       @ENUMPREFIX@
52           The prefix of the enum name (e.g.  PREFIX).
53
54       @VALUENAME@
55           The enum value name currently being processed with words uppercase
56           and word-separated by underscores, this is the assumed literal
57           notation of enum values in the C sources (e.g.  PREFIX_THE_XVALUE).
58
59       @valuenick@
60           A nick name for the enum value currently being processed, this is
61           usually generated by stripping common prefix words of all the enum
62           values of the current enum, the words are lowercase and underscores
63           are substituted by a minus (e.g.  the-xvalue).
64
65       @valuenum@
66           The integer value for the enum value currently being processed. If
67           the evaluation fails then glib-mkenums will exit with an error
68           status, but this only happens if @valuenum@ appears in your value
69           production template. (Since: 2.26)
70
71       @type@
72           This is substituted either by "enum" or "flags", depending on
73           whether the enum value definitions contained bit-shift operators or
74           not (e.g.  flags).
75
76       @Type@
77           The same as @type@ with the first letter capitalized (e.g.  Flags).
78
79       @TYPE@
80           The same as @type@ with all letters uppercased (e.g.  FLAGS).
81
82       @filename@
83           The name of the input file currently being processed (e.g.  foo.h).
84
85       @basename@
86           The base name of the input file currently being processed (e.g.
87           foo.h). Typically you want to use @basename@ in place of @filename@
88           in your templates, to improve the reproducibility of the build.
89           (Since: 2.22)
90
91   Trigraph extensions
92       Some C comments are treated specially in the parsed enum definitions,
93       such comments start out with the trigraph sequence /*< and end with the
94       trigraph sequence >*/. Per enum definition, the options skip and flags
95       can be specified, to indicate this enum definition to be skipped, or
96       for it to be treated as a flags definition, or to specify the common
97       prefix to be stripped from all values to generate value nicknames,
98       respectively. The underscore_name option can be used to specify the
99       word separation used in the *_get_type() function. For instance, /*<
100       underscore_name=gnome_vfs_uri_hide_options >*/.
101
102       Per value definition, the options skip and nick are supported. The
103       former causes the value to be skipped, and the latter can be used to
104       specify the otherwise auto-generated nickname. Examples:
105
106           typedef enum /*< skip >*/
107           {
108             PREFIX_FOO
109           } PrefixThisEnumWillBeSkipped;
110           typedef enum /*< flags,prefix=PREFIX >*/
111           {
112             PREFIX_THE_ZEROTH_VALUE,    /*< skip >*/
113             PREFIX_THE_FIRST_VALUE,
114             PREFIX_THE_SECOND_VALUE,
115             PREFIX_THE_THIRD_VALUE,     /*< nick=the-last-value >*/
116           } PrefixTheFlagsEnum;
117

OPTIONS

119       --fhead TEXT
120           Emits TEXT prior to processing input files.
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 prepended to the
126           template's file-header section.
127
128       --fprod TEXT
129           Emits TEXT every time a new input file is being processed.
130
131           You can specify this option multiple times, and the TEXT will be
132           concatenated.
133
134           When used along with a template file, TEXT will be appended to the
135           template's file-production section.
136
137       --ftail TEXT
138           Emits TEXT after all input files have been processed.
139
140           You can specify this option multiple times, and the TEXT will be
141           concatenated.
142
143           When used along with a template file, TEXT will be appended to the
144           template's file-tail section.
145
146       --eprod TEXT
147           Emits TEXT every time an enum is encountered in the input files.
148
149       --vhead TEXT
150           Emits TEXT before iterating over the set of 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 prepended to the
156           template's value-header section.
157
158       --vprod TEXT
159           Emits TEXT for every value of an enum.
160
161           You can specify this option multiple times, and the TEXT will be
162           concatenated.
163
164           When used along with a template file, TEXT will be appended to the
165           template's value-production section.
166
167       --vtail TEXT
168           Emits TEXT after iterating over all values of an enum.
169
170           You can specify this option multiple times, and the TEXT will be
171           concatenated.
172
173           When used along with a template file, TEXT will be appended to the
174           template's value-tail section.
175
176       --comments TEXT
177           Template for auto-generated comments, the default (for C code
178           generations) is "/* @comment@ */".
179
180       --template FILE
181           Read templates from the given file. The templates are enclosed in
182           specially-formatted C comments:
183
184               /*** BEGIN section ***/
185               /*** END section ***/
186           section may be file-header, file-production, file-tail,
187           enumeration-production, value-header, value-production, value-tail
188           or comment.
189
190       --identifier-prefix PREFIX
191           Indicates what portion of the enum name should be interpreted as
192           the prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this
193           will be figured out automatically, but you may need to override the
194           default if your namespace is capitalized oddly.
195
196       --symbol-prefix PREFIX
197           Indicates what prefix should be used to correspond to the
198           identifier prefix in related C function names (eg, the "gtk" in
199           "gtk_direction_type_get_type". Equivalently, this is the lowercase
200           version of the prefix component of the enum value names (eg, the
201           "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
202           converted to lowercase.
203
204       --help
205           Print brief help and exit.
206
207       --version
208           Print version and exit.
209
210       --output=FILE
211           Write output to FILE instead of stdout.
212
213       @RSPFILE
214           When passed as the sole argument, read and parse the actual
215           arguments from RSPFILE. Useful on systems with a low command-line
216           length limit. For example, Windows has a limit of 8191 characters.
217

USING GLIB-MKENUMS WITH AUTOTOOLS

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

SEE ALSO

324       glib-genmarshal(1)
325
326
327
328GObject                                                        GLIB-MKENUMS(1)
Impressum