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 full path of the input file currently being processed (e.g.
84 /build/environment/project/src/foo.h).
85 @basename@
87 The base name of the input file currently being processed (e.g.
88 foo.h). Typically you want to use @basename@ in place of @filename@
89 in your templates, to improve the reproducibility of the build.
90 (Since: 2.22)
91 Trigraph extensions
93 Some C comments are treated specially in the parsed enum definitions,
94 such comments start out with the trigraph sequence /*< and end with the
95 trigraph sequence >*/. Per enum definition, the options skip and flags
96 can be specified, to indicate this enum definition to be skipped, or
97 for it to be treated as a flags definition, or to specify the common
98 prefix to be stripped from all values to generate value nicknames,
99 respectively. The underscore_name option can be used to specify the
100 word separation used in the *_get_type() function. For instance, /*<
101 underscore_name=gnome_vfs_uri_hide_options >*/.
102 Per value definition, the options skip and nick are supported. The
104 former causes the value to be skipped, and the latter can be used to
105 specify the otherwise auto-generated nickname. Examples:
106 typedef enum /*< skip >*/
108 {
109 PREFIX_FOO
110 } PrefixThisEnumWillBeSkipped;
111 typedef enum /*< flags,prefix=PREFIX >*/
112 {
113 PREFIX_THE_ZEROTH_VALUE, /*< skip >*/
114 PREFIX_THE_FIRST_VALUE,
115 PREFIX_THE_SECOND_VALUE,
116 PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/
117 } PrefixTheFlagsEnum;
118
120 --fhead TEXT
121 Emits TEXT prior to processing input files.
122 You can specify this option multiple times, and the TEXT will be
124 concatenated.
125 When used along with a template file, TEXT will be prepended to the
127 template's file-header section.
128 --fprod TEXT
130 Emits TEXT every time a new input file is being processed.
131 You can specify this option multiple times, and the TEXT will be
133 concatenated.
134 When used along with a template file, TEXT will be appended to the
136 template's file-production section.
137 --ftail TEXT
139 Emits TEXT after all input files have been processed.
140 You can specify this option multiple times, and the TEXT will be
142 concatenated.
143 When used along with a template file, TEXT will be appended to the
145 template's file-tail section.
146 --eprod TEXT
148 Emits TEXT every time an enum is encountered in the input files.
149 --vhead TEXT
151 Emits TEXT before iterating over the set of values of an enum.
152 You can specify this option multiple times, and the TEXT will be
154 concatenated.
155 When used along with a template file, TEXT will be prepended to the
157 template's value-header section.
158 --vprod TEXT
160 Emits TEXT for every value of an enum.
161 You can specify this option multiple times, and the TEXT will be
163 concatenated.
164 When used along with a template file, TEXT will be appended to the
166 template's value-production section.
167 --vtail TEXT
169 Emits TEXT after iterating over all values of an enum.
170 You can specify this option multiple times, and the TEXT will be
172 concatenated.
173 When used along with a template file, TEXT will be appended to the
175 template's value-tail section.
176 --comments TEXT
178 Template for auto-generated comments, the default (for C code
179 generations) is "/* @comment@ */".
180 --template FILE
182 Read templates from the given file. The templates are enclosed in
183 specially-formatted C comments:
184 /*** BEGIN section ***/
186 /*** END section ***/
187 section may be file-header, file-production, file-tail,
188 enumeration-production, value-header, value-production, value-tail
189 or comment.
190 --identifier-prefix PREFIX
192 Indicates what portion of the enum name should be interpreted as
193 the prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this
194 will be figured out automatically, but you may need to override the
195 default if your namespace is capitalized oddly.
196 --symbol-prefix PREFIX
198 Indicates what prefix should be used to correspond to the
199 identifier prefix in related C function names (eg, the "gtk" in
200 "gtk_direction_type_get_type". Equivalently, this is the lowercase
201 version of the prefix component of the enum value names (eg, the
202 "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
203 converted to lowercase.
204 --help
206 Print brief help and exit.
207 --version
209 Print version and exit.
210 --output=FILE
212 Write output to FILE instead of stdout.
213 @RSPFILE
215 When passed as the sole argument, read and parse the actual
216 arguments from RSPFILE. Useful on systems with a low command-line
217 length limit. For example, Windows has a limit of 8191 characters.
218
220 Instead of passing the various sections of the generated file to the
221 command line of glib-mkenums, it's strongly recommended to use a
222 template file, especially for generating C sources.
223 A C header template file will typically look like this:
225 /*** BEGIN file-header ***/
227 #pragma once
228 /* Include the main project header */
230 #include "project.h"
231 G_BEGIN_DECLS
233 /*** END file-header ***/
234 /*** BEGIN file-production ***/
236 /* enumerations from "@basename@" */
238 /*** END file-production ***/
239 /*** BEGIN value-header ***/
241 GType @enum_name@_get_type (void) G_GNUC_CONST;
242 #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
243 /*** END value-header ***/
244 /*** BEGIN file-tail ***/
246 G_END_DECLS
247 /*** END file-tail ***/
248 A C source template file will typically look like this:
250 /*** BEGIN file-header ***/
252 #include "config.h"
253 #include "enum-types.h"
254 /*** END file-header ***/
256 /*** BEGIN file-production ***/
258 /* enumerations from "@basename@" */
259 /*** END file-production ***/
260 /*** BEGIN value-header ***/
262 GType
263 @enum_name@_get_type (void)
264 {
265 static volatile gsize g_@type@_type_id__volatile;
266 if (g_once_init_enter (&g_define_type_id__volatile))
268 {
269 static const G@Type@Value values[] = {
270 /*** END value-header ***/
271 /*** BEGIN value-production ***/
273 { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
274 /*** END value-production ***/
275 /*** BEGIN value-tail ***/
277 { 0, NULL, NULL }
278 };
279 GType g_@type@_type_id =
281 g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
282 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
284 }
285 return g_@type@_type_id__volatile;
286 }
287 /*** END value-tail ***/
289 Template files are easier to modify and update, and can be used to
291 generate various types of outputs using the same command line or tools
292 during the build.
293
295 Meson supports generating enumeration types using glib-mkenums out of
296 the box in its "gnome" module.
297 In your meson.build file you will typically call the
299 gnome.mkenums_simple() method to generate idiomatic enumeration types
300 from a list of headers to inspect:
301 project_headers = [
303 'project-foo.h',
304 'project-bar.h',
305 'project-baz.h',
306 ]
307 gnome = import('gnome')
309 enum_files = gnome.mkenums_simple('enum-types',
310 sources: project_headers,
311 )
312 The enum_files variable will contain an array of two elements in the
314 following order:
315 · a build target for the source file
317 · a build target for the header file
319 You should use the returned objects to provide a dependency on every
321 other build target that references the source or header file; for
322 instance, if you are using the source to build a library:
323 mainlib = library('project',
325 sources: project_sources + enum_files,
326 ...
327 )
328 Additionally, if you are including the generated header file inside a
330 build target that depends on the library you just built, you must
331 ensure that the internal dependency includes the generated header as a
332 required source file:
333 mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
335 You should not include the generated source file as well, otherwise it
337 will be built separately for every target that depends on it, causing
338 build failures. To know more about why all this is required, please
339 refer to the corresponding Meson FAQ entry[1].
340 If you are generating C header and source files that require special
342 templates, you can use gnome.mkenums() to provide those headers, for
343 instance:
344 enum_files = gnome.mkenums('enum-types',
346 sources: project_headers,
347 h_template: 'enum-types.h.in',
348 c_template: 'enum-types.c.in',
349 install_header: true,
350 )
351 For more information, see the Meson documentation for
353 gnome.mkenums()[2].
354
356 In order to use glib-mkenums in your project when using Autotools as
357 the build system, you will first need to modify your configure.ac file
358 to ensure you find the appropriate command using pkg-config, similarly
359 as to how you discover the compiler and linker flags for GLib.
360 PKG_PROG_PKG_CONFIG([0.28])
362 PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
364 In your Makefile.am file you will typically use rules like these:
366 # A list of headers to inspect
368 project_headers = \
369 project-foo.h \
370 project-bar.h \
371 project-baz.h
372 enum-types.h: $(project_headers) enum-types.h.in
374 $(AM_V_GEN)$(GLIB_MKENUMS) \
375 --template=enum-types.h.in \
376 --output=$@ \
377 $(project_headers)
378 enum-types.c: $(project_headers) enum-types.c.in enum-types.h
380 $(AM_V_GEN)$(GLIB_MKENUMS) \
381 --template=enum-types.c.in \
382 --output=$@ \
383 $(project_headers)
384 # Build the enum types files before every other target
386 BUILT_SOURCES += enum-types.h enum-types.c
387 CLEANFILES += enum-types.h enum-types.c
388 EXTRA_DIST += enum-types.h.in enum-types.c.in
389 In the example above, we have a variable called project_headers where
391 we reference all header files we want to inspect for generating
392 enumeration GTypes. In the enum-types.h rule we use glib-mkenums with a
393 template called enum-types.h.in in order to generate the header file;
394 similarly, in the enum-types.c rule we use a template called
395 enum-types.c.in.
396
398 glib-genmarshal(1)
399
401 1. corresponding Meson FAQ entry
402 https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
403 2. Meson documentation for gnome.mkenums()
405 https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
406GObject GLIB-MKENUMS(1)