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 >*/.
96 The following options can be specified per enum definition:
98 skip
100 Indicates this enum definition should be skipped.
101 flags
103 Indicates this enum should be treated as a flags definition.
104 underscore_name
106 Specifies the word separation used in the *_get_type() function.
107 For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.
108 since
110 Specifies the version tag that will be used to substitute the
111 @enumsince@ keyword in the template, useful when documenting
112 methods generated from the enums (e.g. Since: @enumsince@).
113 (Since: 2.66)
114 The following options can be specified per value definition:
116 skip
118 Indicates the value should be skipped.
119 nick
121 Specifies the otherwise auto-generated nickname.
122 Examples:
124 typedef enum /*< skip >*/
126 {
127 PREFIX_FOO
128 } PrefixThisEnumWillBeSkipped;
129 typedef enum /*< flags,prefix=PREFIX,since=1.0 >*/
130 {
131 PREFIX_THE_ZEROTH_VALUE, /*< skip >*/
132 PREFIX_THE_FIRST_VALUE,
133 PREFIX_THE_SECOND_VALUE,
134 PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/
135 } PrefixTheFlagsEnum;
136
138 --fhead TEXT
139 Emits TEXT prior to processing input files.
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 prepended to the
145 template's file-header section.
146 --fprod TEXT
148 Emits TEXT every time a new input file is being processed.
149 You can specify this option multiple times, and the TEXT will be
151 concatenated.
152 When used along with a template file, TEXT will be appended to the
154 template's file-production section.
155 --ftail TEXT
157 Emits TEXT after all input files have been processed.
158 You can specify this option multiple times, and the TEXT will be
160 concatenated.
161 When used along with a template file, TEXT will be appended to the
163 template's file-tail section.
164 --eprod TEXT
166 Emits TEXT every time an enum is encountered in the input files.
167 --vhead TEXT
169 Emits TEXT before iterating over the set of 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 prepended to the
175 template's value-header section.
176 --vprod TEXT
178 Emits TEXT for every value of an enum.
179 You can specify this option multiple times, and the TEXT will be
181 concatenated.
182 When used along with a template file, TEXT will be appended to the
184 template's value-production section.
185 --vtail TEXT
187 Emits TEXT after iterating over all values of an enum.
188 You can specify this option multiple times, and the TEXT will be
190 concatenated.
191 When used along with a template file, TEXT will be appended to the
193 template's value-tail section.
194 --comments TEXT
196 Template for auto-generated comments, the default (for C code
197 generations) is "/* @comment@ */".
198 --template FILE
200 Read templates from the given file. The templates are enclosed in
201 specially-formatted C comments:
202 /*** BEGIN section ***/
204 /*** END section ***/
205 section may be file-header, file-production, file-tail,
206 enumeration-production, value-header, value-production, value-tail
207 or comment.
208 --identifier-prefix PREFIX
210 Indicates what portion of the enum name should be interpreted as
211 the prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this
212 will be figured out automatically, but you may need to override the
213 default if your namespace is capitalized oddly.
214 --symbol-prefix PREFIX
216 Indicates what prefix should be used to correspond to the
217 identifier prefix in related C function names (eg, the "gtk" in
218 "gtk_direction_type_get_type". Equivalently, this is the lowercase
219 version of the prefix component of the enum value names (eg, the
220 "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
221 converted to lowercase.
222 --help
224 Print brief help and exit.
225 --version
227 Print version and exit.
228 --output=FILE
230 Write output to FILE instead of stdout.
231 @RSPFILE
233 When passed as the sole argument, read and parse the actual
234 arguments from RSPFILE. Useful on systems with a low command-line
235 length limit. For example, Windows has a limit of 8191 characters.
236
238 Instead of passing the various sections of the generated file to the
239 command line of glib-mkenums, it's strongly recommended to use a
240 template file, especially for generating C sources.
241 A C header template file will typically look like this:
243 /*** BEGIN file-header ***/
245 #pragma once
246 /* Include the main project header */
248 #include "project.h"
249 G_BEGIN_DECLS
251 /*** END file-header ***/
252 /*** BEGIN file-production ***/
254 /* enumerations from "@basename@" */
256 /*** END file-production ***/
257 /*** BEGIN value-header ***/
259 GType @enum_name@_get_type (void) G_GNUC_CONST;
260 #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
261 /*** END value-header ***/
262 /*** BEGIN file-tail ***/
264 G_END_DECLS
265 /*** END file-tail ***/
266 A C source template file will typically look like this:
268 /*** BEGIN file-header ***/
270 #include "config.h"
271 #include "enum-types.h"
272 /*** END file-header ***/
274 /*** BEGIN file-production ***/
276 /* enumerations from "@basename@" */
277 /*** END file-production ***/
278 /*** BEGIN value-header ***/
280 GType
281 @enum_name@_get_type (void)
282 {
283 static gsize static_g_@type@_type_id;
284 if (g_once_init_enter (&static_g_@type@_type_id))
286 {
287 static const G@Type@Value values[] = {
288 /*** END value-header ***/
289 /*** BEGIN value-production ***/
291 { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
292 /*** END value-production ***/
293 /*** BEGIN value-tail ***/
295 { 0, NULL, NULL }
296 };
297 GType g_@type@_type_id =
299 g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
300 g_once_init_leave (&static_g_@type@_type_id, g_@type@_type_id);
302 }
303 return static_g_@type@_type_id;
304 }
305 /*** END value-tail ***/
307 Template files are easier to modify and update, and can be used to
309 generate various types of outputs using the same command line or tools
310 during the build.
311
313 Meson supports generating enumeration types using glib-mkenums out of
314 the box in its "gnome" module.
315 In your meson.build file you will typically call the
317 gnome.mkenums_simple() method to generate idiomatic enumeration types
318 from a list of headers to inspect:
319 project_headers = [
321 'project-foo.h',
322 'project-bar.h',
323 'project-baz.h',
324 ]
325 gnome = import('gnome')
327 enum_files = gnome.mkenums_simple('enum-types',
328 sources: project_headers,
329 )
330 The enum_files variable will contain an array of two elements in the
332 following order:
333 • a build target for the source file
335 • a build target for the header file
337 You should use the returned objects to provide a dependency on every
339 other build target that references the source or header file; for
340 instance, if you are using the source to build a library:
341 mainlib = library('project',
343 sources: project_sources + enum_files,
344 ...
345 )
346 Additionally, if you are including the generated header file inside a
348 build target that depends on the library you just built, you must
349 ensure that the internal dependency includes the generated header as a
350 required source file:
351 mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
353 You should not include the generated source file as well, otherwise it
355 will be built separately for every target that depends on it, causing
356 build failures. To know more about why all this is required, please
357 refer to the corresponding Meson FAQ entry[1].
358 If you are generating C header and source files that require special
360 templates, you can use gnome.mkenums() to provide those headers, for
361 instance:
362 enum_files = gnome.mkenums('enum-types',
364 sources: project_headers,
365 h_template: 'enum-types.h.in',
366 c_template: 'enum-types.c.in',
367 install_header: true,
368 )
369 For more information, see the Meson documentation for
371 gnome.mkenums()[2].
372
374 In order to use glib-mkenums in your project when using Autotools as
375 the build system, you will first need to modify your configure.ac file
376 to ensure you find the appropriate command using pkg-config, similarly
377 as to how you discover the compiler and linker flags for GLib.
378 PKG_PROG_PKG_CONFIG([0.28])
380 PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
382 In your Makefile.am file you will typically use rules like these:
384 # A list of headers to inspect
386 project_headers = \
387 project-foo.h \
388 project-bar.h \
389 project-baz.h
390 enum-types.h: $(project_headers) enum-types.h.in
392 $(AM_V_GEN)$(GLIB_MKENUMS) \
393 --template=enum-types.h.in \
394 --output=$@ \
395 $(project_headers)
396 enum-types.c: $(project_headers) enum-types.c.in enum-types.h
398 $(AM_V_GEN)$(GLIB_MKENUMS) \
399 --template=enum-types.c.in \
400 --output=$@ \
401 $(project_headers)
402 # Build the enum types files before every other target
404 BUILT_SOURCES += enum-types.h enum-types.c
405 CLEANFILES += enum-types.h enum-types.c
406 EXTRA_DIST += enum-types.h.in enum-types.c.in
407 In the example above, we have a variable called project_headers where
409 we reference all header files we want to inspect for generating
410 enumeration GTypes. In the enum-types.h rule we use glib-mkenums with a
411 template called enum-types.h.in in order to generate the header file;
412 similarly, in the enum-types.c rule we use a template called
413 enum-types.c.in.
414
416 glib-genmarshal(1)
417
419 1. corresponding Meson FAQ entry
420 https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
421 2. Meson documentation for gnome.mkenums()
423 https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
424GObject GLIB-MKENUMS(1)