luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2026-07-23 08:19:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Port the man pages from DocBook to reStructuredText

Browse Source 
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.

This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall
2023-12-20 14:04:11 +00:00
parent 385641572d
commit 031e65808d
37 changed files with 3524 additions and 5326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/gobject/glib-genmarshal.rst
+390
View File
@@ -0,0 +1,390 @@
.. _glib-genmarshal(1):
.. meta::
:copyright: Copyright 2003 Matthias Clasen
:copyright: Copyright 2005, 2012, 2013, 2016 Red Hat, Inc.
:copyright: Copyright 2010 Christian Persch
:copyright: Copyright 2017, 2019, 2020 Emmanuele Bassi
:copyright: Copyright 2020 Centricular
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2003 Matthias Clasen
SPDX-FileCopyrightText: 2005, 2012, 2013, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2010 Christian Persch
SPDX-FileCopyrightText: 2017, 2019, 2020 Emmanuele Bassi
SPDX-FileCopyrightText: 2020 Centricular
SPDX-License-Identifier: LGPL-2.1-or-later
===============
glib-genmarshal
===============
------------------------------------------------------
C code marshaller generation utility for GLib closures
------------------------------------------------------
SYNOPSIS
--------
| **glib-genmarshal** [OPTION…] [FILE…]
DESCRIPTION
-----------
``glib-genmarshal`` is a small utility that generates C code marshallers for
callback functions of the GClosure mechanism in the GObject sublibrary of GLib.
The marshaller functions have a standard signature, they get passed in the
invoking closure, an array of value structures holding the callback function
parameters and a value structure for the return value of the callback. The
marshaller is then responsible to call the respective C code function of the
closure with all the parameters on the stack and to collect its return value.
``glib-genmarshal`` takes a list of marshallers to generate as input. The
marshaller list is either read from files passed as additional arguments
on the command line; or from standard input, by using ``-`` as the input file.
MARSHALLER LIST FORMAT
^^^^^^^^^^^^^^^^^^^^^^
The marshaller lists are processed line by line, a line can contain a comment in
the form of::
# this is a comment
or a marshaller specification of the form::
RTYPE:PTYPE
RTYPE:PTYPE,PTYPE
RTYPE:PTYPE,PTYPE,PTYPE
…
The ``RTYPE`` part specifies the callback’s return type and the ``PTYPE``
instances right of the colon specify the callback’s parameter list, except for
the first and the last arguments which are always pointers.
PARAMETER TYPES
^^^^^^^^^^^^^^^
Currently, the following types are supported:
``VOID``
Indicates no return type, or no extra parameters. If ``VOID`` is used as the
parameter list, no additional parameters may be present.
``BOOLEAN``
For boolean types (``gboolean``).
``CHAR``
For signed char types (``gchar``).
``UCHAR``
For unsigned char types (``guchar``).
``INT``
For signed integer types (``gint``).
``UINT``
For unsigned integer types (``guint``).
``LONG``
For signed long integer types (``glong``).
``ULONG``
For unsigned long integer types (``gulong``).
``INT64``
For signed 64-bit integer types (``gint64``).
``UINT64``
For unsigned 64-bit integer types (``guint64``).
``ENUM``
For enumeration types (``gint``).
``FLAGS``
For flag enumeration types (``guint``).
``FLOAT``
For single-precision float types (``gfloat``).
``DOUBLE``
For double-precision float types (``gdouble``).
``STRING``
For string types (``gchar*``).
``BOXED``
For boxed (anonymous but reference counted) types (``GBoxed*``).
``PARAM``
For ``GParamSpec`` or derived types (``GParamSpec*``).
``POINTER``
For anonymous pointer types (``gpointer``).
``OBJECT``
For ``GObject`` or derived types (``GObject*``).
``VARIANT``
For ``GVariant`` types (``GVariant*``).
``NONE``
Deprecated alias for ``VOID``.
``BOOL``
Deprecated alias for ``BOOLEAN``.
OPTIONS
-------
``--header``
Generate header file contents of the marshallers. This option is mutually
exclusive with the ``--body`` option.
``--body``
Generate C code file contents of the marshallers. This option is mutually
exclusive with the ``--header`` option.
``--prefix <PREFIX>``
Specify marshaller prefix. The default prefix is ``g_cclosure_user_marshal``.
``--skip-source``
Skip source location remarks in generated comments.
``--stdinc``
Use the standard marshallers of the GObject library, and include
``glib-object.h`` in generated header files. This option is mutually exclusive
with the ``--nostdinc`` option.
``--nostdinc``
Do not use the standard marshallers of the GObject library, and skip the
``glib-object.h`` include directive in generated header files.
This option is mutually exclusive with the ``--stdinc`` option.
``--internal``
Mark generated functions as internal, using ``G_GNUC_INTERNAL``.
``-valist-marshallers``
Generate ``valist`` marshallers, for use with
``g_signal_set_va_marshaller()``.
``-v``, ``--version``
Print version information and exit.
``--g-fatal-warnings``
Make warnings fatal. That is, exit immediately once a warning occurs.
``-h``, ``--help``
Print brief help and exit.
``--output <FILE>``
Write output to ``FILE`` instead of the standard output.
``--prototypes``
Generate function prototypes before the function definition in the C source
file, in order to avoid a ``missing-prototypes`` compiler warning. This option
is only useful when using the ``--body`` option.
``--pragma-once``
Use the ``once`` pragma instead of an old style header guard
when generating the C header file. This option is only useful when using the
``--header`` option.
``--include-header <HEADER>``
Adds a ``#include`` directive for the given file in the C source file. This
option is only useful when using the ``--body`` option.
``-D <SYMBOL>[=<VALUE>]``
Adds a ``#define`` C pre-processor directive for ``SYMBOL`` and its given
``VALUE``, or ``"1"`` if the value is unset. You can use this option multiple
times; if you do, all the symbols will be defined in the same order given on
the command line, before the symbols undefined using the ``-U`` option. This
option is only useful when using the ``--body`` option.
``-U <SYMBOL>``
Adds a ``#undef`` C pre-processor directive to undefine the given ``SYMBOL``.
You can use this option multiple times; if you do, all the symbols will be
undefined in the same order given on the command line, after the symbols
defined using the ``-D`` option. This option is only useful when using the
``--body`` option.
``--quiet``
Minimizes the output of ``glib-genmarshal``, by printing only warnings and
errors. This option is mutually exclusive with the ``--verbose`` option.
``--verbose``
Increases the verbosity of ``glib-genmarshal``, by printing debugging
information. This option is mutually exclusive with the ``--quiet`` option.
USING GLIB-GENMARSHAL WITH MESON
--------------------------------
Meson supports generating closure marshallers using ``glib-genmarshal`` out of
the box in its ``gnome`` module.
In your ``meson.build`` file you will typically call the ``gnome.genmarshal()``
method with the source list of marshallers to generate::
gnome = import('gnome')
marshal_files = gnome.genmarshal('marshal',
sources: 'marshal.list',
internal: true,
)
The ``marshal_files`` variable will contain an array of two elements in the
following order:
* a build target for the source file
* a build target for the header file
You should use the returned objects to provide a dependency on every other
build target that references the source or header file; for instance, if you
are using the source to build a library::
mainlib = library('project',
sources: project_sources + marshal_files,
…
)
Additionally, if you are including the generated header file inside a build
target that depends on the library you just built, you must ensure that the
internal dependency includes the generated header as a required source file::
mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
You should not include the generated source file as well, otherwise it will
be built separately for every target that depends on it, causing build
failures. To know more about why all this is required, please refer to the
`corresponding Meson FAQ entry <https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers>`_.
For more information on how to use the method, see the
`Meson documentation <https://mesonbuild.com/Gnome-module.html#gnomegenmarshal>`_
for ``gnome.genmarshal()``.
USING GLIB-GENMARSHAL WITH AUTOTOOLS
------------------------------------
In order to use ``glib-genmarshal`` 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_GENMARSHAL], [glib-2.0], [glib_genmarshal])
In your ``Makefile.am`` file you will typically need very simple rules to
generate the C files needed for the build::
marshal.h: marshal.list
$(AM_V_GEN)$(GLIB_GENMARSHAL) \
--header \
--output=$@ \
$<
marshal.c: marshal.list marshal.h
$(AM_V_GEN)$(GLIB_GENMARSHAL) \
--include-header=marshal.h \
--body \
--output=$@ \
$<
BUILT_SOURCES += marshal.h marshal.c
CLEANFILES += marshal.h marshal.c
EXTRA_DIST += marshal.list
In the example above, the first rule generates the header file and depends on
a ``marshal.list`` file in order to regenerate the result in case the
marshallers list is updated. The second rule generates the source file for the
same ``marshal.list``, and includes the file generated by the header rule.
EXAMPLE
-------
To generate marshallers for the following callback functions::
void foo (gpointer data1,
gpointer data2);
void bar (gpointer data1,
gint param1,
gpointer data2);
gfloat baz (gpointer data1,
gboolean param1,
guchar param2,
gpointer data2);
The ``marshaller.list`` file has to look like this::
VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR
and you call ``glib-genmarshal`` like this::
glib-genmarshal --header marshaller.list > marshaller.h
glib-genmarshal --body marshaller.list > marshaller.c
The generated marshallers have the arguments encoded in their function name.
For this particular list, they are::
g_cclosure_user_marshal_VOID__VOID(...),
g_cclosure_user_marshal_VOID__INT(...),
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
They can be used directly for GClosures or be passed in as the
``GSignalCMarshaller c_marshaller`` argument upon creation of signals::
GClosure *cc_foo, *cc_bar, *cc_baz;
cc_foo = g_cclosure_new (NULL, foo, NULL);
g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
cc_bar = g_cclosure_new (NULL, bar, NULL);
g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
cc_baz = g_cclosure_new (NULL, baz, NULL);
g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
SEE ALSO
--------
`glib-mkenums(1) <man:glib-mkenums(1)>`_
docs/reference/gobject/glib-genmarshal.xml
-579
View File
@@ -1,579 +0,0 @@
<refentry id="glib-genmarshal" lang="en">
<refentryinfo>
<title>glib-genmarshal</title>
<productname>GObject</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Emmanuele</firstname>
<surname>Bassi</surname>
</author>
<author>
<contrib>Original developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-genmarshal</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-genmarshal</refname>
<refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-genmarshal</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt" rep="repeat">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-genmarshal</command> is a small utility that generates C code
marshallers for callback functions of the GClosure mechanism in the GObject
sublibrary of GLib. The marshaller functions have a standard signature,
they get passed in the invoking closure, an array of value structures holding
the callback function parameters and a value structure for the return value
of the callback. The marshaller is then responsible to call the respective C
code function of the closure with all the parameters on the stack and to
collect its return value.
</para>
<para><command>glib-genmarshal</command> takes a list of marshallers to generate as
input. The marshaller list is either read from files passed as additional arguments
on the command line; or from standard input, by using <literal>-</literal> as the
input file.
</para>
<refsect2><title>Marshaller list format</title>
<para>
The marshaller lists are processed line by line, a line can contain a
comment in the form of
<informalexample><programlisting>
# this is a comment
</programlisting></informalexample>
or a marshaller specification of the form
<programlisting>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
</programlisting>
</para>
<para>
The <replaceable>RTYPE</replaceable> part specifies the callback's return
type and the <replaceable>PTYPE</replaceable>s right to the colon specify
the callback's parameter list, except for the first and the last arguments
which are always pointers.
</para>
</refsect2>
<refsect2><title>Parameter types</title>
<para>
Currently, the following types are supported:
<variablelist>
<varlistentry>
<term><replaceable>VOID</replaceable></term>
<listitem><para>
indicates no return type, or no extra parameters.
If <replaceable>VOID</replaceable> is used as the parameter list, no
additional parameters may be present.
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>BOOLEAN</replaceable></term>
<listitem><para>
for boolean types (gboolean)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>CHAR</replaceable></term>
<listitem><para>
for signed char types (gchar)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>UCHAR</replaceable></term>
<listitem><para>
for unsigned char types (guchar)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>INT</replaceable></term>
<listitem><para>
for signed integer types (gint)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>UINT</replaceable></term>
<listitem><para>
for unsigned integer types (guint)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>LONG</replaceable></term>
<listitem><para>
for signed long integer types (glong)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>ULONG</replaceable></term>
<listitem><para>
for unsigned long integer types (gulong)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>INT64</replaceable></term>
<listitem><para>
for signed 64bit integer types (gint64)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>UINT64</replaceable></term>
<listitem><para>
for unsigned 64bit integer types (guint64)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>ENUM</replaceable></term>
<listitem><para>
for enumeration types (gint)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>FLAGS</replaceable></term>
<listitem><para>
for flag enumeration types (guint)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>FLOAT</replaceable></term>
<listitem><para>
for single-precision float types (gfloat)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>DOUBLE</replaceable></term>
<listitem><para>
for double-precision float types (gdouble)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>STRING</replaceable></term>
<listitem><para>
for string types (gchar*)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>BOXED</replaceable></term>
<listitem><para>
for boxed (anonymous but reference counted) types (GBoxed*)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>PARAM</replaceable></term>
<listitem><para>
for GParamSpec or derived types (GParamSpec*)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>POINTER</replaceable></term>
<listitem><para>
for anonymous pointer types (gpointer)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>OBJECT</replaceable></term>
<listitem><para>
for GObject or derived types (GObject*)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>VARIANT</replaceable></term>
<listitem><para>
for GVariant types (GVariant*)
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>NONE</replaceable></term>
<listitem><para>
deprecated alias for <replaceable>VOID</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>BOOL</replaceable></term>
<listitem><para>
deprecated alias for <replaceable>BOOLEAN</replaceable>
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--header</option></term>
<listitem><para>
Generate header file contents of the marshallers. This option is mutually
exclusive with the <option>--body</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--body</option></term>
<listitem><para>
Generate C code file contents of the marshallers. This option is mutually
exclusive with the <option>--header</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
<listitem><para>
Specify marshaller prefix. The default prefix is <literal>`g_cclosure_user_marshal'</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-source</option></term>
<listitem><para>
Skip source location remarks in generated comments.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--stdinc</option></term>
<listitem><para>
Use the standard marshallers of the GObject library, and include
<filename>glib-object.h</filename> in generated header files. This
option is mutually exclusive with the <option>--nostdinc</option>
option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--nostdinc</option></term>
<listitem><para>
Do not use the standard marshallers of the GObject library, and skip
<filename>glib-object.h</filename> include directive in generated header files.
This option is mutually exclusive with the <option>--stdinc</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--internal</option></term>
<listitem><para>
Mark generated functions as internal, using <literal>G_GNUC_INTERNAL</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--valist-marshallers</option></term>
<listitem><para>
Generate valist marshallers, for use with <function>g_signal_set_va_marshaller()</function>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
Print version information.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--g-fatal-warnings</option></term>
<listitem><para>
Make warnings fatal, that is, exit immediately once a warning occurs.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print brief help and exit.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
Print version and exit.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--output=FILE</option></term>
<listitem><para>
Write output to <replaceable>FILE</replaceable> instead of the standard output.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--prototypes</option></term>
<listitem><para>
Generate function prototypes before the function definition in the C source
file, in order to avoid a <literal>missing-prototypes</literal> compiler
warning. This option is only useful when using the <option>--body</option>
option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pragma-once</option></term>
<listitem><para>
Use the <literal>once</literal> pragma instead of an old style header guard
when generating the C header file. This option is only useful when using the
<option>--header</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--include-header=<replaceable>HEADER</replaceable></option></term>
<listitem><para>
Adds a <literal>#include</literal> directive for the given file in the C
source file. This option is only useful when using the <option>--body</option>
option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-D <replaceable>SYMBOL[=VALUE]</replaceable></option></term>
<listitem><para>
Adds a <literal>#define</literal> C pre-processor directive for
<replaceable>SYMBOL</replaceable> and its given <replaceable>VALUE</replaceable>,
or "1" if the value is unset. You can use this option multiple times; if you do,
all the symbols will be defined in the same order given on the command line, before
the symbols undefined using the <option>-U</option> option. This option is only
useful when using the <option>--body</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-U <replaceable>SYMBOL</replaceable></option></term>
<listitem><para>
Adds a <literal>#undef</literal> C pre-processor directive to undefine the
given <replaceable>SYMBOL</replaceable>. You can use this option multiple times;
if you do, all the symbols will be undefined in the same order given on the
command line, after the symbols defined using the <option>-D</option> option.
This option is only useful when using the <option>--body</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--quiet</option></term>
<listitem><para>
Minimizes the output of <command>glib-genmarshal</command>, by printing only
warnings and errors. This option is mutually exclusive with the
<option>--verbose</option> option.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem><para>
Increases the verbosity of <command>glib-genmarshal</command>, by printing
debugging information. This option is mutually exclusive with the
<option>--quiet</option> option.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Using <command>glib-genmarshal</command> with Meson</title>
<para>
Meson supports generating closure marshallers using <command>glib-genmarshal</command>
out of the box in its "gnome" module.
</para>
<para>
In your <filename>meson.build</filename> file you will typically call the
<literal>gnome.genmarshal()</literal> method with the source list of marshallers
to generate:
</para>
<informalexample><programlisting>
gnome = import('gnome')
marshal_files = gnome.genmarshal('marshal',
sources: 'marshal.list',
internal: true,
)
</programlisting></informalexample>
<para>
The <literal>marshal_files</literal> variable will contain an array of two elements
in the following order:
</para>
<itemizedlist>
<listitem><para>a build target for the source file</para></listitem>
<listitem><para>a build target for the header file</para></listitem>
</itemizedlist>
<para>
You should use the returned objects to provide a dependency on every other
build target that references the source or header file; for instance, if you
are using the source to build a library:
</para>
<informalexample><programlisting>
mainlib = library('project',
sources: project_sources + marshal_files,
...
)
</programlisting></informalexample>
<para>
Additionally, if you are including the generated header file inside a build
target that depends on the library you just built, you must ensure that the
internal dependency includes the generated header as a required source file:
</para>
<informalexample><programlisting>
mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
</programlisting></informalexample>
<para>
You should not include the generated source file as well, otherwise it will
be built separately for every target that depends on it, causing build
failures. To know more about why all this is required, please refer to the
<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
corresponding Meson FAQ entry</ulink>.
</para>
<para>
For more information on how to use the method, see the
<ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
documentation for <literal>gnome.genmarshal()</literal></ulink>.
</para>
</refsect1>
<refsect1><title>Using <command>glib-genmarshal</command> with Autotools</title>
<para>
In order to use <command>glib-genmarshal</command> in your project when using
Autotools as the build system, you will first need to modify your
<filename>configure.ac</filename> file to ensure you find the appropriate
command using <command>pkg-config</command>, similarly as to how you discover
the compiler and linker flags for GLib.
</para>
<informalexample><programlisting>
PKG_PROG_PKG_CONFIG([0.28])
PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
</programlisting></informalexample>
<para>
In your <filename>Makefile.am</filename> file you will typically need very
simple rules to generate the C files needed for the build.
</para>
<informalexample><programlisting>
marshal.h: marshal.list
$(AM_V_GEN)$(GLIB_GENMARSHAL) \
--header \
--output=$@ \
$&lt;
marshal.c: marshal.list marshal.h
$(AM_V_GEN)$(GLIB_GENMARSHAL) \
--include-header=marshal.h \
--body \
--output=$@ \
$&lt;
BUILT_SOURCES += marshal.h marshal.c
CLEANFILES += marshal.h marshal.c
EXTRA_DIST += marshal.list
</programlisting></informalexample>
<para>
In the example above, the first rule generates the header file and depends on
a <filename>marshal.list</filename> file in order to regenerate the result in
case the marshallers list is updated. The second rule generates the source file
for the same <filename>marshal.list</filename>, and includes the file generated
by the header rule.
</para>
</refsect1>
<refsect1><title>Example</title>
<para>
To generate marshallers for the following callback functions:
</para>
<informalexample><programlisting>
void foo (gpointer data1,
gpointer data2);
void bar (gpointer data1,
gint param1,
gpointer data2);
gfloat baz (gpointer data1,
gboolean param1,
guchar param2,
gpointer data2);
</programlisting></informalexample>
<para>
The <filename>marshaller.list</filename> file has to look like this:
</para>
<programlisting>
VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR
</programlisting>
<para>
and you call glib-genmarshal like this:
</para>
<programlisting>
glib-genmarshal --header marshaller.list > marshaller.h
glib-genmarshal --body marshaller.list > marshaller.c
</programlisting>
<para>
The generated marshallers have the arguments encoded in their function name.
For this particular list, they are
</para>
<programlisting>
g_cclosure_user_marshal_VOID__VOID(...),
g_cclosure_user_marshal_VOID__INT(...),
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
</programlisting>
<para>
They can be used directly for GClosures or be passed in as the
GSignalCMarshaller c_marshaller; argument upon creation of signals:
</para>
<informalexample><programlisting>
GClosure *cc_foo, *cc_bar, *cc_baz;
cc_foo = g_cclosure_new (NULL, foo, NULL);
g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
cc_bar = g_cclosure_new (NULL, bar, NULL);
g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
cc_baz = g_cclosure_new (NULL, baz, NULL);
g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
</programlisting></informalexample>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>glib-mkenums</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/gobject/glib-mkenums.rst
+491
View File
@@ -0,0 +1,491 @@
.. _glib-mkenums(1):
.. meta::
:copyright: Copyright 2003 Matthias Clasen
:copyright: Copyright 2009 Christian Persch
:copyright: Copyright 2010 Allison Karlitskaya
:copyright: Copyright 2012, 2013, 2016 Red Hat, Inc.
:copyright: Copyright 2017, 2019, 2022 Emmanuele Bassi
:copyright: Copyright 2018, 2020 Centricular
:copyright: Copyright 2020 Aleksander Morgado
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2003 Matthias Clasen
SPDX-FileCopyrightText: 2009 Christian Persch
SPDX-FileCopyrightText: 2010 Allison Karlitskaya
SPDX-FileCopyrightText: 2012, 2013, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2017, 2019, 2022 Emmanuele Bassi
SPDX-FileCopyrightText: 2018, 2020 Centricular
SPDX-FileCopyrightText: 2020 Aleksander Morgado
SPDX-License-Identifier: LGPL-2.1-or-later
============
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.
Since version 2.74, GLib provides the ``G_DEFINE_ENUM_TYPE`` and
``G_DEFINE_FLAGS_TYPE`` C pre-processor macros. These macros can be used to
define a GType for projects that have few, small enumeration types without going
through the complexities of generating code at build time.
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::
typedef enum
{
PREFIX_THE_XVALUE = 1 << 3,
PREFIX_ANOTHER_VALUE = 1 << 4
} PrefixTheXEnum;
``@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 (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 full path of the input file currently being processed
(e.g. ``/build/environment/project/src/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 ``>*/``.
The following options can be specified per enum definition:
``skip``
Indicates this enum definition should be skipped.
``flags``
Indicates this enum should be treated as a flags definition.
``underscore_name``
Specifies the word separation used in the ``*_get_type()``
function. For instance,
``/*< underscore_name=gnome_vfs_uri_hide_options >*/``.
``since``
Specifies the version tag that will be used to substitute the ``@enumsince@``
keyword in the template, useful when documenting methods generated from the
enums (e.g. ``Since: @enumsince@``). (Since: 2.66)
The following options can be specified per value definition:
``skip``
Indicates the value should be skipped.
``nick``
Specifies the otherwise auto-generated nickname.
Examples::
typedef enum /*< skip >*/
{
PREFIX_FOO
} PrefixThisEnumWillBeSkipped;
typedef enum /*< flags,prefix=PREFIX,since=1.0 >*/
{
PREFIX_THE_ZEROTH_VALUE, /*< skip >*/
PREFIX_THE_FIRST_VALUE,
PREFIX_THE_SECOND_VALUE,
PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/
} PrefixTheFlagsEnum;
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`` every time 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::
/*** BEGIN section ***/
/*** END section ***/
``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 interpreted as the prefix
(e.g. 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 (e.g. the ``gtk`` in
``gtk_direction_type_get_type``). Equivalently, this is the lowercase version
of the prefix component of the enum value names (e.g. 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.
``@RSPFILE``
When passed as the sole argument, read and parse the actual arguments from
``RSPFILE``. Useful on systems with a low command-line length limit. For
example, Windows has a limit of 8191 characters.
USING TEMPLATES
---------------
Instead of passing the various sections of the generated file to the command
line of ``glib-mkenums``, it’s strongly recommended to use a template file,
especially for generating C sources.
A C 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 "@basename@" */
/*** 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 ***/
A C source template file will typically look like this::
/*** BEGIN file-header ***/
#include "config.h"
#include "enum-types.h"
/*** END file-header ***/
/*** BEGIN file-production ***/
/* enumerations from "@basename@" */
/*** END file-production ***/
/*** BEGIN value-header ***/
GType
@enum_name@_get_type (void)
{
static GType static_g_@type@_type_id = 0;
if (g_once_init_enter_pointer (&static_g_@type@_type_id))
{
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_pointer (&static_g_@type@_type_id, g_@type@_type_id);
}
return static_g_@type@_type_id;
}
/*** END value-tail ***/
Template files are easier to modify and update, and can be used to generate
various types of outputs using the same command line or tools during the build.
USING GLIB-MKENUMS WITH MESON
-----------------------------
Meson supports generating enumeration types using ``glib-mkenums`` out of the
box in its ``gnome`` module.
In your ``meson.build`` file you will typically call the
``gnome.mkenums_simple()`` method to generate idiomatic enumeration types from a
list of headers to inspect::
project_headers = [
'project-foo.h',
'project-bar.h',
'project-baz.h',
]
gnome = import('gnome')
enum_files = gnome.mkenums_simple('enum-types',
sources: project_headers,
)
The ``enum_files`` variable will contain an array of two elements
in the following order:
1. a build target for the source file
2. a build target for the header file
You should use the returned objects to provide a dependency on every other
build target that references the source or header file; for instance, if you
are using the source to build a library::
mainlib = library('project',
sources: project_sources + enum_files,
…
)
Additionally, if you are including the generated header file inside a build
target that depends on the library you just built, you must ensure that the
internal dependency includes the generated header as a required source file::
mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
You should not include the generated source file as well, otherwise it will
be built separately for every target that depends on it, causing build
failures. To know more about why all this is required, please refer to the
`corresponding Meson FAQ entry <https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers>`_.
If you are generating C header and source files that require special templates,
you can use ``gnome.mkenums()`` to provide those headers, for instance::
enum_files = gnome.mkenums('enum-types',
sources: project_headers,
h_template: 'enum-types.h.in',
c_template: 'enum-types.c.in',
install_header: true,
)
For more information, see the
`Meson documentation <https://mesonbuild.com/Gnome-module.html#gnomegenmarshal>`_
for ``gnome.mkenums()``.
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)
# Build the enum types files before every other target
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; similarly, in the
``enum-types.c`` rule we use a template called ``enum-types.c.in``.
SEE ALSO
--------
`glib-genmarshal(1) <man:glib-genmarshal(1)>`_
docs/reference/gobject/glib-mkenums.xml
-659
View File
@@ -1,659 +0,0 @@
<refentry id="glib-mkenums" lang="en">
<refentryinfo>
<title>gdbus</title>
<productname>GObject</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Owen</firstname>
<surname>Taylor</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-mkenums</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-mkenums</refname>
<refpurpose>C language enum description generation utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-mkenums</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt" rep="repeat">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-mkenums</command> 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.
</para>
<para><command>glib-mkenums</command> takes a list of valid C code files as
input. The options specified control the text that generated, substituting various
keywords enclosed in <literal>@</literal> characters in the templates.
</para>
<para>Since version 2.74, GLib provides the <literal>G_DEFINE_ENUM_TYPE</literal>
and <literal>G_DEFINE_FLAGS_TYPE</literal> C pre-processor macros. These macros
can be used to define a GType for projects that have few, small enumeration
types without going through the complexities of generating code at build
time.</para>
<refsect2><title>Production text substitutions</title>
<para>
Certain keywords enclosed in <literal>@</literal> characters will be substituted in the
emitted text. For the substitution examples of the keywords below,
the following example enum definition is assumed:
</para>
<informalexample><programlisting>
typedef enum
{
PREFIX_THE_XVALUE = 1 &lt;&lt; 3,
PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
} PrefixTheXEnum;
</programlisting></informalexample>
<variablelist>
<varlistentry>
<term><literal>@EnumName@</literal></term>
<listitem><para>
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. <literal>PrefixTheXEnum</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@enum_name@</literal></term>
<listitem><para>
The enum name with words lowercase and word-separated by underscores
(e.g. <literal>prefix_the_xenum</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@ENUMNAME@</literal></term>
<listitem><para>
The enum name with words uppercase and word-separated by underscores
(e.g. <literal>PREFIX_THE_XENUM</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@ENUMSHORT@</literal></term>
<listitem><para>
The enum name with words uppercase and word-separated by underscores,
prefix stripped (e.g. <literal>THE_XENUM</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@ENUMPREFIX@</literal></term>
<listitem><para>
The prefix of the enum name (e.g. <literal>PREFIX</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@VALUENAME@</literal></term>
<listitem><para>
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. <literal>PREFIX_THE_XVALUE</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@valuenick@</literal></term>
<listitem><para>
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. <literal>the-xvalue</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@valuenum@</literal></term>
<listitem><para>
The integer value for the enum value currently being processed. If the
evaluation fails then <command>glib-mkenums</command> will exit with an
error status, but this only happens if <literal>@valuenum@</literal>
appears in your value production template. (Since: 2.26)
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@type@</literal></term>
<listitem><para>
This is substituted either by "enum" or "flags", depending on whether the
enum value definitions contained bit-shift operators or not (e.g. <literal>flags</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@Type@</literal></term>
<listitem><para>
The same as <literal>@type@</literal> with the first letter capitalized (e.g. <literal>Flags</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@TYPE@</literal></term>
<listitem><para>
The same as <literal>@type@</literal> with all letters uppercased (e.g. <literal>FLAGS</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@filename@</literal></term>
<listitem><para>
The full path of the input file currently being processed (e.g. <literal>/build/environment/project/src/foo.h</literal>).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>@basename@</literal></term>
<listitem><para>
The base name of the input file currently being processed (e.g. <literal>foo.h</literal>).
Typically you want to use <literal>@basename@</literal> in place of <literal>@filename@</literal>
in your templates, to improve the reproducibility of the build. (Since: 2.22)
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Trigraph extensions</title>
<para>
Some C comments are treated specially in the parsed enum definitions,
such comments start out with the trigraph sequence <literal>/*&lt;</literal>
and end with the trigraph sequence <literal>&gt;*/</literal>.
</para>
<para>The following options can be specified per enum definition:</para>
<variablelist>
<varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates this enum definition should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>flags</literal></term>
<listitem><para>
Indicates this enum should be treated as a flags definition.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>underscore_name</literal></term>
<listitem><para>
Specifies the word separation used in the <function>*_get_type()</function>
function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>since</literal></term>
<listitem><para>
Specifies the version tag that will be used to substitute the <literal>@enumsince@</literal>
keyword in the template, useful when documenting methods generated from the enums
(e.g. <literal>Since: @enumsince@</literal>). (Since: 2.66)
</para></listitem>
</varlistentry>
</variablelist>
<para>The following options can be specified per value definition:</para>
<variablelist>
<varlistentry>
<term><literal>skip</literal></term>
<listitem><para>
Indicates the value should be skipped.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>nick</literal></term>
<listitem><para>
Specifies the otherwise auto-generated nickname.
</para></listitem>
</varlistentry>
</variablelist>
<para>Examples:</para>
<informalexample><programlisting>
typedef enum /*&lt; skip &gt;*/
{
PREFIX_FOO
} PrefixThisEnumWillBeSkipped;
typedef enum /*&lt; flags,prefix=PREFIX,since=1.0 &gt;*/
{
PREFIX_THE_ZEROTH_VALUE, /*&lt; skip &gt;*/
PREFIX_THE_FIRST_VALUE,
PREFIX_THE_SECOND_VALUE,
PREFIX_THE_THIRD_VALUE, /*&lt; nick=the-last-value &gt;*/
} PrefixTheFlagsEnum;
</programlisting></informalexample>
</refsect2>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--fhead</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> prior to processing input files.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be prepended to the template's <literal>file-header</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--fprod</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> every time a new input file
is being processed.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be appended to the template's <literal>file-production</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--ftail</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> after all input files have been
processed.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be appended to the template's <literal>file-tail</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--eprod</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> every time an enum is encountered
in the input files.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--vhead</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> before iterating over the set of
values of an enum.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be prepended to the template's <literal>value-header</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--vprod</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> for every value of an enum.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be appended to the template's <literal>value-production</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--vtail</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Emits <replaceable>TEXT</replaceable> after iterating over all values
of an enum.
</para>
<para>
You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
will be concatenated.
</para>
<para>
When used along with a template file, <replaceable>TEXT</replaceable>
will be appended to the template's <literal>value-tail</literal> section.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--comments</option> <replaceable>TEXT</replaceable></term>
<listitem><para>
Template for auto-generated comments, the default (for C code generations) is
<literal>"/* @comment@ */"</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--template</option> <replaceable>FILE</replaceable></term>
<listitem><para>
Read templates from the given file. The templates are enclosed in
specially-formatted C comments:
</para>
<informalexample><programlisting>
/*** BEGIN section ***/
/*** END section ***/
</programlisting></informalexample>
<para>
<replaceable>section</replaceable> may be <literal>file-header</literal>,
<literal>file-production</literal>, <literal>file-tail</literal>,
<literal>enumeration-production</literal>, <literal>value-header</literal>,
<literal>value-production</literal>, <literal>value-tail</literal> or
<literal>comment</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term>
<listitem><para>
Indicates what portion of the enum name should be interpreted as the
prefix (eg, the "<literal>Gtk</literal>" in
"<literal>GtkDirectionType</literal>"). Normally this will be figured
out automatically, but you may need to override the default if your
namespace is capitalized oddly.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term>
<listitem><para>
Indicates what prefix should be used to correspond to the identifier
prefix in related C function names (eg, the "<literal>gtk</literal>"
in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
this is the lowercase version of the prefix component of the enum
value names (eg, the "<literal>GTK</literal>" in
"<literal>GTK_DIR_UP</literal>". The default value is the identifier
prefix, converted to lowercase.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>
Print brief help and exit.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print version and exit.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--output=FILE</option></term>
<listitem><para>
Write output to FILE instead of stdout.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>@RSPFILE</option></term>
<listitem><para>
When passed as the sole argument, read and parse the actual arguments from
<literal>RSPFILE</literal>. Useful on systems with a low command-line length
limit. For example, Windows has a limit of 8191 characters.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Using templates</title>
<para>
Instead of passing the various sections of the generated file to the command
line of <command>glib-mkenums</command>, it's strongly recommended to use a
template file, especially for generating C sources.
</para>
<para>
A C header template file will typically look like this:
</para>
<informalexample><programlisting>
/*** BEGIN file-header ***/
#pragma once
/* Include the main project header */
#include "project.h"
G_BEGIN_DECLS
/*** END file-header ***/
/*** BEGIN file-production ***/
/* enumerations from "@basename@" */
/*** 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 ***/
</programlisting></informalexample>
<para>
A C source template file will typically look like this:
</para>
<informalexample><programlisting>
/*** BEGIN file-header ***/
#include "config.h"
#include "enum-types.h"
/*** END file-header ***/
/*** BEGIN file-production ***/
/* enumerations from "@basename@" */
/*** END file-production ***/
/*** BEGIN value-header ***/
GType
@enum_name@_get_type (void)
{
static gsize static_g_@type@_type_id;
if (g_once_init_enter (&amp;static_g_@type@_type_id))
{
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 (&amp;static_g_@type@_type_id, g_@type@_type_id);
}
return static_g_@type@_type_id;
}
/*** END value-tail ***/
</programlisting></informalexample>
<para>
Template files are easier to modify and update, and can be used
to generate various types of outputs using the same command line
or tools during the build.
</para>
</refsect1>
<refsect1><title>Using glib-mkenums with Meson</title>
<para>
Meson supports generating enumeration types using <command>glib-mkenums</command>
out of the box in its "gnome" module.
</para>
<para>
In your <filename>meson.build</filename> file you will typically call the
<literal>gnome.mkenums_simple()</literal> method to generate idiomatic enumeration
types from a list of headers to inspect:
</para>
<informalexample><programlisting>
project_headers = [
'project-foo.h',
'project-bar.h',
'project-baz.h',
]
gnome = import('gnome')
enum_files = gnome.mkenums_simple('enum-types',
sources: project_headers,
)
</programlisting></informalexample>
<para>
The <literal>enum_files</literal> variable will contain an array of two elements
in the following order:
</para>
<itemizedlist>
<listitem><para>a build target for the source file</para></listitem>
<listitem><para>a build target for the header file</para></listitem>
</itemizedlist>
<para>
You should use the returned objects to provide a dependency on every other
build target that references the source or header file; for instance, if you
are using the source to build a library:
</para>
<informalexample><programlisting>
mainlib = library('project',
sources: project_sources + enum_files,
...
)
</programlisting></informalexample>
<para>
Additionally, if you are including the generated header file inside a build
target that depends on the library you just built, you must ensure that the
internal dependency includes the generated header as a required source file:
</para>
<informalexample><programlisting>
mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
</programlisting></informalexample>
<para>
You should not include the generated source file as well, otherwise it will
be built separately for every target that depends on it, causing build
failures. To know more about why all this is required, please refer to the
<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
corresponding Meson FAQ entry</ulink>.
</para>
<para>
If you are generating C header and source files that require special
templates, you can use <literal>gnome.mkenums()</literal> to provide those
headers, for instance:
</para>
<informalexample><programlisting>
enum_files = gnome.mkenums('enum-types',
sources: project_headers,
h_template: 'enum-types.h.in',
c_template: 'enum-types.c.in',
install_header: true,
)
</programlisting></informalexample>
<para>
For more information, see the <ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
documentation for <literal>gnome.mkenums()</literal></ulink>.
</para>
</refsect1>
<refsect1><title>Using glib-mkenums with Autotools</title>
<para>
In order to use <command>glib-mkenums</command> in your project when using
Autotools as the build system, you will first need to modify your
<filename>configure.ac</filename> file to ensure you find the appropriate
command using <command>pkg-config</command>, similarly as to how you discover
the compiler and linker flags for GLib.
</para>
<informalexample><programlisting>
PKG_PROG_PKG_CONFIG([0.28])
PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
</programlisting></informalexample>
<para>
In your <filename>Makefile.am</filename> file you will typically use rules
like these:
</para>
<informalexample><programlisting>
# 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)
# Build the enum types files before every other target
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
</programlisting></informalexample>
<para>
In the example above, we have a variable called <literal>project_headers</literal>
where we reference all header files we want to inspect for generating enumeration
GTypes. In the <filename>enum-types.h</filename> rule we use <command>glib-mkenums</command>
with a template called <filename>enum-types.h.in</filename> in order to generate the
header file; similarly, in the <filename>enum-types.c</filename> rule we use a
template called <filename>enum-types.c.in</filename>.
</para>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>glib-genmarshal</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
docs/reference/gobject/gobject-query.rst
+74
View File
@@ -0,0 +1,74 @@
.. _gobject-query(1):
.. meta::
:copyright: Copyright 2003 Matthias Clasen
:copyright: Copyright 2012 Red Hat, Inc.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2003 Matthias Clasen
SPDX-FileCopyrightText: 2012 Red Hat, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
=============
gobject-query
=============
-----------------------
display a tree of types
-----------------------
SYNOPSIS
--------
| **gobject-query** froots [*OPTION*…]
| **gobject-query** tree [*OPTION*…]
DESCRIPTION
-----------
``gobject-query`` is a small utility that draws a tree of types.
It takes a mandatory argument that specifies whether it should iterate over the
fundamental types or print a type tree.
COMMANDS
--------
``froots``
Iterate over fundamental roots.
``tree``
Print type tree.
OPTIONS
-------
``-r <TYPE>``
Specify the root type.
``-n``
Don’t descend type tree.
``-b <STRING>``
Specify indent string.
``-i <STRING>``
Specify incremental indent string.
``-s <NUMBER>``
Specify line spacing.
``-h``, ``--help``
Print brief help and exit.
``-v``, ``--version``
Print version and exit.
docs/reference/gobject/gobject-query.xml
-123
View File
@@ -1,123 +0,0 @@
<refentry id="gobject-query" lang="en">
<refentryinfo>
<title>gobject-query</title>
<productname>GObject</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gobject-query</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gobject-query</refname>
<refpurpose>display a tree of types</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gobject-query</command>
<arg choice="plain">froots</arg>
<arg choice="opt" rep="repeat">OPTION</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gobject-query</command>
<arg choice="plain">tree</arg>
<arg choice="opt" rep="repeat">OPTION</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gobject-query</command> is a small utility that draws a tree of
types.
</para>
<para>
<command>gobject-query</command> takes a mandatory argument that specifies
whether it should iterate over the fundamental types or print a type tree.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>froots</option></term>
<listitem><para>
iterate over fundamental roots
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>tree</option></term>
<listitem><para>
print type tree
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-r</option> <replaceable>TYPE</replaceable></term>
<listitem><para>
specify the root type
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<listitem><para>
don't descend type tree
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option> <replaceable>STRING</replaceable></term>
<listitem><para>
specify indent string
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option> <replaceable>STRING</replaceable></term>
<listitem><para>
specify incremental indent string
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option> <replaceable>NUMBER</replaceable></term>
<listitem><para>
specify line spacing
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print brief help and exit.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
Print version and exit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
docs/reference/gobject/meson.build
+8 -3
View File
@@ -1,10 +1,15 @@
if get_option('man')
if get_option('man-pages').enabled()
manpages = ['glib-mkenums', 'glib-genmarshal', 'gobject-query']
foreach page : manpages
custom_target(page + '-man',
input: page + '.xml',
input: page + '.rst',
output: page + '.1',
command: xsltproc_command,
command: [
rst2man,
rst2man_flags,
'@INPUT@',
],
capture: true,
install: true,
install_dir: man1_dir,
install_tag: 'doc',