Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GLIB-MKENUMS(1)			 User Commands		       GLIB-MKENUMS(1)

NAME
       glib-mkenums - C	language enum description generation utility

SYNOPSIS
       glib-mkenums [OPTION...]	[FILE...]

DESCRIPTION
       glib-mkenums is a small utility that parses C code to extract enum
       definitions and produces	enum descriptions based	on text	templates
       specified by the	user. Typically, you can use this tool to generate
       enumeration types for the GType type system, for	#GObject properties
       and signal marshalling; additionally, you can use it to generate
       enumeration values of #GSettings	schemas.

       glib-mkenums takes a list of valid C code files as input. The options
       specified control the text that generated, substituting various
       keywords	enclosed in @ characters in the	templates.

   Production text substitutions
       Certain keywords	enclosed in @ characters will be substituted in	the
       emitted text. For the substitution examples of the keywords below, the
       following example enum definition is assumed:

       @EnumName@
	   The name of the enum	currently being	processed, enum	names are
	   assumed to be properly namespaced and to use	mixed capitalization
	   to separate words (e.g.  PrefixTheXEnum).

       @enum_name@
	   The enum name with words lowercase and word-separated by
	   underscores (e.g.  prefix_the_xenum).

       @ENUMNAME@
	   The enum name with words uppercase and word-separated by
	   underscores (e.g.  PREFIX_THE_XENUM).

       @ENUMSHORT@
	   The enum name with words uppercase and word-separated by
	   underscores,	prefix stripped	(e.g.  THE_XENUM).

       @ENUMPREFIX@
	   The prefix of the enum name (e.g.  PREFIX).

       @VALUENAME@
	   The enum value name currently being processed with words uppercase
	   and word-separated by underscores, this is the assumed literal
	   notation of enum values in the C sources (e.g.  PREFIX_THE_XVALUE).

       @valuenick@
	   A nick name for the enum value currently being processed, this is
	   usually generated by	stripping common prefix	words of all the enum
	   values of the current enum, the words are lowercase and underscores
	   are substituted by a	minus (e.g.  the-xvalue).

       @valuenum@
	   The integer value for the enum value	currently being	processed. If
	   the evaluation fails	then glib-mkenums will exit with an error
	   status, but this only happens if @valuenum@ appears in your value
	   production template.	(Since:	2.26)

       @type@
	   This	is substituted either by "enum"	or "flags", depending on
	   whether the enum value definitions contained	bit-shift operators or
	   not (e.g. flags).

       @Type@
	   The same as @type@ with the first letter capitalized	(e.g. Flags).

       @TYPE@
	   The same as @type@ with all letters uppercased (e.g.	FLAGS).

       @filename@
	   The name of the input file currently	being processed	(e.g. foo.h).

       @basename@
	   The base name of the	input file currently being processed (e.g.
	   foo.h). Typically you want to use @basename@	in place of @filename@
	   in your templates, to improve the reproducibility of	the build.
	   (Since: 2.22)

   Trigraph extensions
       Some C comments are treated specially in	the parsed enum	definitions,
       such comments start out with the	trigraph sequence /*< and end with the
       trigraph	sequence >*/. Per enum definition, the options "skip" and
       "flags" can be specified, to indicate this enum definition to be
       skipped,	or for it to be	treated	as a flags definition, or to specify
       the common prefix to be stripped	from all values	to generate value
       nicknames, respectively.	The "underscore_name" option can be used to
       specify the word	separation used	in the *_get_type() function. For
       instance, /*< underscore_name=gnome_vfs_uri_hide_options	>*/.

       Per value definition, the options "skip"	and "nick" are supported. The
       former causes the value to be skipped, and the latter can be used to
       specify the otherwise auto-generated nickname. Examples:

OPTIONS
       --fhead TEXT
	   Emits TEXT prior to processing input	files.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be prepended	to the
	   template's file-header section.

       --fprod TEXT
	   Emits TEXT every time a new input file is being processed.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be appended to the
	   template's file-production section.

       --ftail TEXT
	   Emits TEXT after all	input files have been processed.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be appended to the
	   template's file-tail	section.

       --eprod TEXT
	   Emits TEXT everytime	an enum	is encountered in the input files.

       --vhead TEXT
	   Emits TEXT before iterating over the	set of values of an enum.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be prepended	to the
	   template's value-header section.

       --vprod TEXT
	   Emits TEXT for every	value of an enum.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be appended to the
	   template's value-production section.

       --vtail TEXT
	   Emits TEXT after iterating over all values of an enum.

	   You can specify this	option multiple	times, and the TEXT will be
	   concatenated.

	   When	used along with	a template file, TEXT will be appended to the
	   template's value-tail section.

       --comments TEXT
	   Template for	auto-generated comments, the default (for C code
	   generations)	is "/* @comment@ */".

       --template FILE
	   Read	templates from the given file. The templates are enclosed in
	   specially-formatted C comments
	   where section may be	file-header, file-production, file-tail,
	   enumeration-production, value-header, value-production, value-tail
	   or comment.

       --identifier-prefix PREFIX
	   Indicates what portion of the enum name should be intepreted	as the
	   prefix (eg, the "Gtk" in "GtkDirectionType"). Normally this will be
	   figured out automatically, but you may need to override the default
	   if your namespace is	capitalized oddly.

       --symbol-prefix PREFIX
	   Indicates what prefix should	be used	to correspond to the
	   identifier prefix in	related	C function names (eg, the "gtk"	in
	   "gtk_direction_type_get_type". Equivalently,	this is	the lowercase
	   version of the prefix component of the enum value names (eg,	the
	   "GTK" in "GTK_DIR_UP". The default value is the identifier prefix,
	   converted to	lowercase.

       --help
	   Print brief help and	exit.

       --version
	   Print version and exit.

       --output=FILE
	   Write output	to FILE	instead	of stdout.

USING GLIB-MKENUMS WITH	AUTOTOOLS
       In order	to use glib-mkenums in your project when using Autotools as
       the build system, you will first	need to	modify your configure.ac file
       to ensure you find the appropriate command using	pkg-config, similarly
       as to how you discover the compiler and linker flags for	GLib.

	   PKG_PROG_PKG_CONFIG([0.28])

	   PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])

       In your Makefile.am file	you will typically use rules like these:

	   # A list of headers to inspect
	   project_headers = \
		   project-foo.h \
		   project-bar.h \
		   project-baz.h

	   enum-types.h: $(project_headers) enum-types.h.in
		   $(AM_V_GEN)$(GLIB_MKENUMS) \
			   --template=enum-types.h.in \
			   --output=$@ \
			   $(project_headers)

	   enum-types.c: $(project_headers) enum-types.c.in enum-types.h
		   $(AM_V_GEN)$(GLIB_MKENUMS) \
			   --template=enum-types.c.in \
			   --output=$@ \
			   $(project_headers)

	   BUILT_SOURCES += enum-types.h enum-types.c
	   CLEANFILES += enum-types.h enum-types.c
	   EXTRA_DIST += enum-types.h.in enum-types.c.in

       In the example above, we	have a variable	called project_headers where
       we reference all	header files we	want to	inspect	for generating
       enumeration GTypes. In the enum-types.h rule we use glib-mkenums	with a
       template	called enum-types.h.in in order	to generate the	header file; a
       header template file will typically look	like this:

	   /***	BEGIN file-header ***/
	   #pragma once

	   /* Include the main project header */
	   #include "project.h"

	   G_BEGIN_DECLS
	   /***	END file-header	***/

	   /***	BEGIN file-production ***/

	   /* enumerations from	"@filename@" */
	   /***	END file-production ***/

	   /***	BEGIN value-header ***/
	   GType @enum_name@_get_type (void) G_GNUC_CONST;
	   #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
	   /***	END value-header ***/

	   /***	BEGIN file-tail	***/
	   G_END_DECLS
	   /***	END file-tail ***/

       The enum-types.c	rule is	similar	to the rule for	the header file, but
       will use	a different enum-types.c.in template file, similar to this:

	   /***	BEGIN file-header ***/
	   #include "config.h"
	   #include "enum-types.h"

	   /***	END file-header	***/

	   /***	BEGIN file-production ***/
	   /* enumerations from	"@filename@" */
	   /***	END file-production ***/

	   /***	BEGIN value-header ***/
	   GType
	   @enum_name@_get_type	(void)
	   {
	     static volatile gsize g_@type@_type_id__volatile;

	     if	(g_once_init_enter (&g_define_type_id__volatile))
	       {
		 static	const G@Type@Value values[] = {
	   /***	END value-header ***/

	   /***	BEGIN value-production ***/
		       { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
	   /***	END value-production ***/

	   /***	BEGIN value-tail ***/
		       { 0, NULL, NULL }
		 };

		 GType g_@type@_type_id	=
		   g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);

		 g_once_init_leave (&g_@type@_type_id__volatile, g_@type@_type_id);
	       }
	     return g_@type@_type_id__volatile;
	   }

	   /***	END value-tail ***/

SEE ALSO
       glib-genmarshal(1)

GObject							       GLIB-MKENUMS(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USING GLIB-MKENUMS WITH AUTOTOOLS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=glib-mkenums&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help