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 full path of the input file currently being processed (e.g.
84           /build/environment/project/src/foo.h).
85
86       @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
92   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
97       The following options can be specified per enum definition:
98
99       skip
100           Indicates this enum definition should be skipped.
101
102       flags
103           Indicates this enum should be treated as a flags definition.
104
105       underscore_name
106           Specifies the word separation used in the *_get_type() function.
107           For instance, /*< underscore_name=gnome_vfs_uri_hide_options >*/.
108
109       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
115       The following options can be specified per value definition:
116
117       skip
118           Indicates the value should be skipped.
119
120       nick
121           Specifies the otherwise auto-generated nickname.
122
123       Examples:
124
125           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

OPTIONS

138       --fhead TEXT
139           Emits TEXT prior to processing input files.
140
141           You can specify this option multiple times, and the TEXT will be
142           concatenated.
143
144           When used along with a template file, TEXT will be prepended to the
145           template's file-header section.
146
147       --fprod TEXT
148           Emits TEXT every time a new input file is being processed.
149
150           You can specify this option multiple times, and the TEXT will be
151           concatenated.
152
153           When used along with a template file, TEXT will be appended to the
154           template's file-production section.
155
156       --ftail TEXT
157           Emits TEXT after all input files have been processed.
158
159           You can specify this option multiple times, and the TEXT will be
160           concatenated.
161
162           When used along with a template file, TEXT will be appended to the
163           template's file-tail section.
164
165       --eprod TEXT
166           Emits TEXT every time an enum is encountered in the input files.
167
168       --vhead TEXT
169           Emits TEXT before iterating over the set of values of an enum.
170
171           You can specify this option multiple times, and the TEXT will be
172           concatenated.
173
174           When used along with a template file, TEXT will be prepended to the
175           template's value-header section.
176
177       --vprod TEXT
178           Emits TEXT for every value of an enum.
179
180           You can specify this option multiple times, and the TEXT will be
181           concatenated.
182
183           When used along with a template file, TEXT will be appended to the
184           template's value-production section.
185
186       --vtail TEXT
187           Emits TEXT after iterating over all values of an enum.
188
189           You can specify this option multiple times, and the TEXT will be
190           concatenated.
191
192           When used along with a template file, TEXT will be appended to the
193           template's value-tail section.
194
195       --comments TEXT
196           Template for auto-generated comments, the default (for C code
197           generations) is "/* @comment@ */".
198
199       --template FILE
200           Read templates from the given file. The templates are enclosed in
201           specially-formatted C comments:
202
203               /*** 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
209       --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
215       --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
223       --help
224           Print brief help and exit.
225
226       --version
227           Print version and exit.
228
229       --output=FILE
230           Write output to FILE instead of stdout.
231
232       @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

USING TEMPLATES

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
242       A C header template file will typically look like this:
243
244           /*** BEGIN file-header ***/
245           #pragma once
246
247           /* Include the main project header */
248           #include "project.h"
249
250           G_BEGIN_DECLS
251           /*** END file-header ***/
252
253           /*** BEGIN file-production ***/
254
255           /* enumerations from "@basename@" */
256           /*** END file-production ***/
257
258           /*** 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
263           /*** BEGIN file-tail ***/
264           G_END_DECLS
265           /*** END file-tail ***/
266
267       A C source template file will typically look like this:
268
269           /*** BEGIN file-header ***/
270           #include "config.h"
271           #include "enum-types.h"
272
273           /*** END file-header ***/
274
275           /*** BEGIN file-production ***/
276           /* enumerations from "@basename@" */
277           /*** END file-production ***/
278
279           /*** BEGIN value-header ***/
280           GType
281           @enum_name@_get_type (void)
282           {
283             static volatile gsize g_@type@_type_id__volatile;
284
285             if (g_once_init_enter (&g_define_type_id__volatile))
286               {
287                 static const G@Type@Value values[] = {
288           /*** END value-header ***/
289
290           /*** BEGIN value-production ***/
291                       { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
292           /*** END value-production ***/
293
294           /*** BEGIN value-tail ***/
295                       { 0, NULL, NULL }
296                 };
297
298                 GType g_@type@_type_id =
299                   g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
300
301                 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
302               }
303             return g_@type@_type_id__volatile;
304           }
305
306           /*** END value-tail ***/
307
308       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

USING GLIB-MKENUMS WITH MESON

313       Meson supports generating enumeration types using glib-mkenums out of
314       the box in its "gnome" module.
315
316       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
320           project_headers = [
321             'project-foo.h',
322             'project-bar.h',
323             'project-baz.h',
324           ]
325
326           gnome = import('gnome')
327           enum_files = gnome.mkenums_simple('enum-types',
328             sources: project_headers,
329           )
330
331       The enum_files variable will contain an array of two elements in the
332       following order:
333
334       ·   a build target for the source file
335
336       ·   a build target for the header file
337
338       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
342           mainlib = library('project',
343             sources: project_sources + enum_files,
344             ...
345           )
346
347       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
352           mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
353
354       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
359       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
363           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
370       For more information, see the Meson documentation for
371       gnome.mkenums()[2].
372

USING GLIB-MKENUMS WITH AUTOTOOLS

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
379           PKG_PROG_PKG_CONFIG([0.28])
380
381           PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
382
383       In your Makefile.am file you will typically use rules like these:
384
385           # A list of headers to inspect
386           project_headers = \
387                   project-foo.h \
388                   project-bar.h \
389                   project-baz.h
390
391           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
397           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
403           # 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
408       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

SEE ALSO

416       glib-genmarshal(1)
417

NOTES

419        1. corresponding Meson FAQ entry
420           https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers
421
422        2. Meson documentation for gnome.mkenums()
423           https://mesonbuild.com/Gnome-module.html#gnomegenmarshal
424
425
426
427GObject                                                        GLIB-MKENUMS(1)
Impressum