1GLIB-MKENUMS(1) User Commands GLIB-MKENUMS(1)
2
6 glib-mkenums - C language enum description generation utility
7
9 glib-mkenums [OPTION...] [FILE...]
10
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 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 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 typedef enum
29 {
30 PREFIX_THE_XVALUE = 1 << 3,
31 PREFIX_ANOTHER_VALUE = 1 << 4
32 } PrefixTheXEnum;
33 @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 @enum_name@
40 The enum name with words lowercase and word-separated by
41 underscores (e.g. prefix_the_xenum).
42 @ENUMNAME@
44 The enum name with words uppercase and word-separated by
45 underscores (e.g. PREFIX_THE_XENUM).
46 @ENUMSHORT@
48 The enum name with words uppercase and word-separated by
49 underscores, prefix stripped (e.g. THE_XENUM).
50 @ENUMPREFIX@
52 The prefix of the enum name (e.g. PREFIX).
53 @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 @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 @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 @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 @Type@
77 The same as @type@ with the first letter capitalized (e.g. Flags).
78 @TYPE@
80 The same as @type@ with all letters uppercased (e.g. FLAGS).
81 @filename@
83 The name of the input file currently being processed (e.g. foo.h).
84 @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 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 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 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
119 --fhead TEXT
120 Emits TEXT prior to processing input files.
121 You can specify this option multiple times, and the TEXT will be
123 concatenated.
124 When used along with a template file, TEXT will be prepended to the
126 template's file-header section.
127 --fprod TEXT
129 Emits TEXT every time a new input file is being processed.
130 You can specify this option multiple times, and the TEXT will be
132 concatenated.
133 When used along with a template file, TEXT will be appended to the
135 template's file-production section.
136 --ftail TEXT
138 Emits TEXT after all input files have been processed.
139 You can specify this option multiple times, and the TEXT will be
141 concatenated.
142 When used along with a template file, TEXT will be appended to the
144 template's file-tail section.
145 --eprod TEXT
147 Emits TEXT every time an enum is encountered in the input files.
148 --vhead TEXT
150 Emits TEXT before iterating over the set of values of an enum.
151 You can specify this option multiple times, and the TEXT will be
153 concatenated.
154 When used along with a template file, TEXT will be prepended to the
156 template's value-header section.
157 --vprod TEXT
159 Emits TEXT for every value of an enum.
160 You can specify this option multiple times, and the TEXT will be
162 concatenated.
163 When used along with a template file, TEXT will be appended to the
165 template's value-production section.
166 --vtail TEXT
168 Emits TEXT after iterating over all values of an enum.
169 You can specify this option multiple times, and the TEXT will be
171 concatenated.
172 When used along with a template file, TEXT will be appended to the
174 template's value-tail section.
175 --comments TEXT
177 Template for auto-generated comments, the default (for C code
178 generations) is "/* @comment@ */".
179 --template FILE
181 Read templates from the given file. The templates are enclosed in
182 specially-formatted C comments:
183 /*** 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 --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 --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 --help
205 Print brief help and exit.
206 --version
208 Print version and exit.
209 --output=FILE
211 Write output to FILE instead of stdout.
212 @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
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 PKG_PROG_PKG_CONFIG([0.28])
225 PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
227 In your Makefile.am file you will typically use rules like these:
229 # A list of headers to inspect
231 project_headers = \
232 project-foo.h \
233 project-bar.h \
234 project-baz.h
235 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 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 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 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 /*** BEGIN file-header ***/
259 #pragma once
260 /* Include the main project header */
262 #include "project.h"
263 G_BEGIN_DECLS
265 /*** END file-header ***/
266 /*** BEGIN file-production ***/
268 /* enumerations from "@filename@" */
270 /*** END file-production ***/
271 /*** 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 /*** BEGIN file-tail ***/
278 G_END_DECLS
279 /*** END file-tail ***/
280 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 /*** BEGIN file-header ***/
285 #include "config.h"
286 #include "enum-types.h"
287 /*** END file-header ***/
289 /*** BEGIN file-production ***/
291 /* enumerations from "@filename@" */
292 /*** END file-production ***/
293 /*** BEGIN value-header ***/
295 GType
296 @enum_name@_get_type (void)
297 {
298 static volatile gsize g_@type@_type_id__volatile;
299 if (g_once_init_enter (&g_define_type_id__volatile))
301 {
302 static const G@Type@Value values[] = {
303 /*** END value-header ***/
304 /*** BEGIN value-production ***/
306 { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
307 /*** END value-production ***/
308 /*** BEGIN value-tail ***/
310 { 0, NULL, NULL }
311 };
312 GType g_@type@_type_id =
314 g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
315 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
317 }
318 return g_@type@_type_id__volatile;
319 }
320 /*** END value-tail ***/
322
324 glib-genmarshal(1)
325GObject GLIB-MKENUMS(1)