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 Since version 2.74, GLib provides the G_DEFINE_ENUM_TYPE and
24 G_DEFINE_FLAGS_TYPE C pre-processor macros. These macros can be used to
25 define a GType for projects that have few, small enumeration types
26 without going through the complexities of generating code at build
27 time.
28 Production text substitutions
30 Certain keywords enclosed in @ characters will be substituted in the
31 emitted text. For the substitution examples of the keywords below, the
32 following example enum definition is assumed:
33 typedef enum
35 {
36 PREFIX_THE_XVALUE = 1 << 3,
37 PREFIX_ANOTHER_VALUE = 1 << 4
38 } PrefixTheXEnum;
39 @EnumName@>
41 The name of the enum currently being processed, enum names are
42 assumed to be properly namespaced and to use mixed capitalization
43 to separate words (e.g. PrefixTheXEnum).
44 @enum_name@
46 The enum name with words lowercase and word-separated by
47 underscores (e.g. prefix_the_xenum).
48 @ENUMNAME@
50 The enum name with words uppercase and word-separated by
51 underscores (e.g. PREFIX_THE_XENUM).
52 @ENUMSHORT@
54 The enum name with words uppercase and word-separated by
55 underscores, prefix stripped (e.g. THE_XENUM).
56 @ENUMPREFIX@
58 The prefix of the enum name (e.g. PREFIX).
59 @VALUENAME@
61 The enum value name currently being processed with words uppercase
62 and word-separated by underscores, this is the assumed literal
63 notation of enum values in the C sources (e.g. PREFIX_THE_XVALUE).
64 @valuenick@
66 A nick name for the enum value currently being processed, this is
67 usually generated by stripping common prefix words of all the enum
68 values of the current enum, the words are lowercase and underscores
69 are substituted by a minus (e.g. the-xvalue).
70 @valuenum@
72 The integer value for the enum value currently being processed. If
73 the evaluation fails then glib-mkenums will exit with an error
74 status, but this only happens if @valuenum@ appears in your value
75 production template. (Since: 2.26)
76 @type@
78 This is substituted either by "enum" or "flags", depending on
79 whether the enum value definitions contained bit-shift operators or
80 not (e.g. flags).
81 @Type@
83 The same as @type@ with the first letter capitalized (e.g. Flags).
84 @TYPE@
86 The same as @type@ with all letters uppercased (e.g. FLAGS).
87 @filename@
89 The full path of the input file currently being processed (e.g.
90 /build/environment/project/src/foo.h).
91 @basename@
93 The base name of the input file currently being processed (e.g.
94 foo.h). Typically you want to use @basename@ in place of @filename@
95 in your templates, to improve the reproducibility of the build.
96 (Since: 2.22)
97 Trigraph extensions
99 Some C comments are treated specially in the parsed enum definitions,
100 such comments start out with the trigraph sequence /*< and end with the
101 trigraph sequence >*/.
102 The following options can be specified per enum definition:
104 skip
106 Indicates this enum definition should be skipped.
107 flags
109 Indicates this enum should be treated as a flags definition.
110 underscore_name
112 Specifies the word separation used in the *_get_type() function.
113 For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.
114 since
116 Specifies the version tag that will be used to substitute the
117 @enumsince@ keyword in the template, useful when documenting
118 methods generated from the enums (e.g. Since: @enumsince@).
119 (Since: 2.66)
120 The following options can be specified per value definition:
122 skip
124 Indicates the value should be skipped.
125 nick
127 Specifies the otherwise auto-generated nickname.
128 Examples:
130 typedef enum /*< skip >*/
132 {
133 PREFIX_FOO
134 } PrefixThisEnumWillBeSkipped;
135 typedef enum /*< flags,prefix=PREFIX,since=1.0 >*/
136 {
137 PREFIX_THE_ZEROTH_VALUE, /*< skip >*/
138 PREFIX_THE_FIRST_VALUE,
139 PREFIX_THE_SECOND_VALUE,
140 PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/
141 } PrefixTheFlagsEnum;
142
144 --fhead TEXT
145 Emits TEXT prior to processing input files.
146 You can specify this option multiple times, and the TEXT will be
148 concatenated.
149 When used along with a template file, TEXT will be prepended to the
151 template's file-header section.
152 --fprod TEXT
154 Emits TEXT every time a new input file is being processed.
155 You can specify this option multiple times, and the TEXT will be
157 concatenated.
158 When used along with a template file, TEXT will be appended to the
160 template's file-production section.
161 --ftail TEXT
163 Emits TEXT after all input files have been processed.
164 You can specify this option multiple times, and the TEXT will be
166 concatenated.
167 When used along with a template file, TEXT will be appended to the
169 template's file-tail section.
170 --eprod TEXT
172 Emits TEXT every time an enum is encountered in the input files.
173 --vhead TEXT
175 Emits TEXT before iterating over the set of values of an enum.
176 You can specify this option multiple times, and the TEXT will be
178 concatenated.
179 When used along with a template file, TEXT will be prepended to the
181 template's value-header section.
182 --vprod TEXT
184 Emits TEXT for every value of an enum.
185 You can specify this option multiple times, and the TEXT will be
187 concatenated.
188 When used along with a template file, TEXT will be appended to the
190 template's value-production section.
191 --vtail TEXT
193 Emits TEXT after iterating over all values of an enum.
194 You can specify this option multiple times, and the TEXT will be
196 concatenated.
197 When used along with a template file, TEXT will be appended to the
199 template's value-tail section.
200 --comments TEXT
202 Template for auto-generated comments, the default (for C code
203 generations) is "/* @comment@ */".
204 --template FILE
206 Read templates from the given file. The templates are enclosed in
207 specially-formatted C comments:
208 /*** BEGIN section ***/
210 /*** END section ***/
211 section may be file-header, file-production, file-tail,
212 enumeration-production, value-header, value-production, value-tail
213 or comment.
214 --identifier-prefix PREFIX
216 Indicates what portion of the enum name should be interpreted as
217 the prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this
218 will be figured out automatically, but you may need to override the
219 default if your namespace is capitalized oddly.
220 --symbol-prefix PREFIX
222 Indicates what prefix should be used to correspond to the
223 identifier prefix in related C function names (eg, the "gtk" in
224 "gtk_direction_type_get_type". Equivalently, this is the lowercase
225 version of the prefix component of the enum value names (eg, the
226 "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
227 converted to lowercase.
228 --help
230 Print brief help and exit.
231 --version
233 Print version and exit.
234 --output=FILE
236 Write output to FILE instead of stdout.
237 @RSPFILE
239 When passed as the sole argument, read and parse the actual
240 arguments from RSPFILE. Useful on systems with a low command-line
241 length limit. For example, Windows has a limit of 8191 characters.
242
244 Instead of passing the various sections of the generated file to the
245 command line of glib-mkenums, it's strongly recommended to use a
246 template file, especially for generating C sources.
247 A C header template file will typically look like this:
249 /*** BEGIN file-header ***/
251 #pragma once
252 /* Include the main project header */
254 #include "project.h"
255 G_BEGIN_DECLS
257 /*** END file-header ***/
258 /*** BEGIN file-production ***/
260 /* enumerations from "@basename@" */
262 /*** END file-production ***/
263 /*** BEGIN value-header ***/
265 GType @enum_name@_get_type (void) G_GNUC_CONST;
266 #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
267 /*** END value-header ***/
268 /*** BEGIN file-tail ***/
270 G_END_DECLS
271 /*** END file-tail ***/
272 A C source template file will typically look like this:
274 /*** BEGIN file-header ***/
276 #include "config.h"
277 #include "enum-types.h"
278 /*** END file-header ***/
280 /*** BEGIN file-production ***/
282 /* enumerations from "@basename@" */
283 /*** END file-production ***/
284 /*** BEGIN value-header ***/
286 GType
287 @enum_name@_get_type (void)
288 {
289 static gsize static_g_@type@_type_id;
290 if (g_once_init_enter (&static_g_@type@_type_id))
292 {
293 static const G@Type@Value values[] = {
294 /*** END value-header ***/
295 /*** BEGIN value-production ***/
297 { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
298 /*** END value-production ***/
299 /*** BEGIN value-tail ***/
301 { 0, NULL, NULL }
302 };
303 GType g_@type@_type_id =
305 g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
306 g_once_init_leave (&static_g_@type@_type_id, g_@type@_type_id);
308 }
309 return static_g_@type@_type_id;
310 }
311 /*** END value-tail ***/
313 Template files are easier to modify and update, and can be used to
315 generate various types of outputs using the same command line or tools
316 during the build.
317
319 Meson supports generating enumeration types using glib-mkenums out of
320 the box in its "gnome" module.
321 In your meson.build file you will typically call the
323 gnome.mkenums_simple() method to generate idiomatic enumeration types
324 from a list of headers to inspect:
325 project_headers = [
327 'project-foo.h',
328 'project-bar.h',
329 'project-baz.h',
330 ]
331 gnome = import('gnome')
333 enum_files = gnome.mkenums_simple('enum-types',
334 sources: project_headers,
335 )
336 The enum_files variable will contain an array of two elements in the
338 following order:
339 • a build target for the source file
341 • a build target for the header file
343 You should use the returned objects to provide a dependency on every
345 other build target that references the source or header file; for
346 instance, if you are using the source to build a library:
347 mainlib = library('project',
349 sources: project_sources + enum_files,
350 ...
351 )
352 Additionally, if you are including the generated header file inside a
354 build target that depends on the library you just built, you must
355 ensure that the internal dependency includes the generated header as a
356 required source file:
357 mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
359 You should not include the generated source file as well, otherwise it
361 will be built separately for every target that depends on it, causing
362 build failures. To know more about why all this is required, please
363 refer to the corresponding Meson FAQ entry[1].
364 If you are generating C header and source files that require special
366 templates, you can use gnome.mkenums() to provide those headers, for
367 instance:
368 enum_files = gnome.mkenums('enum-types',
370 sources: project_headers,
371 h_template: 'enum-types.h.in',
372 c_template: 'enum-types.c.in',
373 install_header: true,
374 )
375 For more information, see the Meson documentation for
377 gnome.mkenums()[2].
378
380 In order to use glib-mkenums in your project when using Autotools as
381 the build system, you will first need to modify your configure.ac file
382 to ensure you find the appropriate command using pkg-config, similarly
383 as to how you discover the compiler and linker flags for GLib.
384 PKG_PROG_PKG_CONFIG([0.28])
386 PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
388 In your Makefile.am file you will typically use rules like these:
390 # A list of headers to inspect
392 project_headers = \
393 project-foo.h \
394 project-bar.h \
395 project-baz.h
396 enum-types.h: $(project_headers) enum-types.h.in
398 $(AM_V_GEN)$(GLIB_MKENUMS) \
399 --template=enum-types.h.in \
400 --output=$@ \
401 $(project_headers)
402 enum-types.c: $(project_headers) enum-types.c.in enum-types.h
404 $(AM_V_GEN)$(GLIB_MKENUMS) \
405 --template=enum-types.c.in \
406 --output=$@ \
407 $(project_headers)
408 # Build the enum types files before every other target
410 BUILT_SOURCES += enum-types.h enum-types.c
411 CLEANFILES += enum-types.h enum-types.c
412 EXTRA_DIST += enum-types.h.in enum-types.c.in
413 In the example above, we have a variable called project_headers where
415 we reference all header files we want to inspect for generating
416 enumeration GTypes. In the enum-types.h rule we use glib-mkenums with a
417 template called enum-types.h.in in order to generate the header file;
418 similarly, in the enum-types.c rule we use a template called
419 enum-types.c.in.
420
422 glib-genmarshal(1)
423
425 1. corresponding Meson FAQ entry
426 https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
427 2. Meson documentation for gnome.mkenums()
429 https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
430GObject GLIB-MKENUMS(1)