luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 22:16:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '3037-man-rst2man' into 'main'

Browse Source 
docs: Port the man pages from DocBook to reStructuredText

Closes #3037

See merge request GNOME/glib!3775
This commit is contained in:
Philip Withnall 2023-12-21 17:04:33 +00:00
commit 4c23a17752
38 changed files with 3526 additions and 5327 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.gitlab-ci.yml
View File

@ -11,7 +11,7 @@ cache:
- _ccache/
variables:
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v25"
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v26"
COVERITY_IMAGE: "registry.gitlab.gnome.org/gnome/glib/coverity:v7"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v19"
ALPINE_IMAGE: "registry.gitlab.gnome.org/gnome/glib/alpine:v3"
@ -130,7 +130,7 @@ fedora-x86_64:
-Dinstalled_tests=true
-Ddocumentation=true
-Dintrospection=enabled
-Dman=true
-Dman-pages=enabled
_build
- meson compile -C _build
- mkdir -p _coverage
@ -753,7 +753,7 @@ dist-job:
- git submodule update --init
- for m in $(git submodule foreach -q 'echo $path'); do git config --global --add safe.directory "${PWD}/${m}"; done
- meson subprojects download
- meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Ddocumentation=true -Dman=true _build
- meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Ddocumentation=true -Dman-pages=enabled _build
- meson dist -C _build
- tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/glib glib
- tar -c -J -f "gmodule-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gmodule gmodule

1
.gitlab-ci/fedora.Dockerfile
View File

@ -49,6 +49,7 @@ RUN dnf -y update \
ninja-build \
pcre2-devel \
"python3-dbusmock >= 0.18.3-2" \
python3-docutils \
python3-packaging \
python3-pip \
python3-pygments \

195
docs/reference/gio/gapplication.rst Normal file
View File

@ -0,0 +1,195 @@
.. _gapplication(1):
.. meta::
:copyright: Copyright 2013 Allison Karlitskaya
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2013 Allison Karlitskaya
SPDX-License-Identifier: LGPL-2.1-or-later
============
gapplication
============
--------------------------
D-Bus application launcher
--------------------------
SYNOPSIS
--------
| **gapplication** help [COMMAND]
| **gapplication** version
| **gapplication** list-apps
| **gapplication** launch <APP-ID>
| **gapplication** launch <APP-ID> [FILE…]
| **gapplication** list-actions <APP-ID>
| **gapplication** action <APP-ID> <ACTION> [PARAMETER]
DESCRIPTION
-----------
``gapplication`` is a commandline implementation of the client-side of the
``org.freedesktop.Application`` interface as specified by the freedesktop.org
Desktop Entry Specification.
``gapplication`` can be used to start applications that have ``DBusActivatable``
set to ``true`` in their ``.desktop`` files and can be used to send messages to
already-running instances of other applications.
It is possible for applications to refer to ``gapplication`` in the ``Exec``
line of their ``.desktop`` file to maintain backwards compatibility with
implementations that do not directly support ``DBusActivatable``.
``gapplication`` ships as part of GLib.
COMMANDS
--------
``help [COMMAND]``
Displays a short synopsis of the available commands or provides detailed help
on a specific command.
``version``
Prints the GLib version whence ``gapplication`` came.
``list-apps``
Prints a list of all application IDs that are known to support D-Bus
activation. This list is generated by scanning ``.desktop`` files as per the
current ``XDG_DATA_DIRS``.
``launch <APP-ID> [FILE…]``
Launches an application.
The first parameter is the application ID in the familiar ‘reverse DNS’ style
(e.g. ``org.gnome.app``) without the ``.desktop`` suffix.
Optionally, if additional parameters are given, they are treated as the names
of files to open and may be filenames or URIs. If no files are given then the
application is simply activated.
``list-actions <APP-ID>``
List the actions declared in the application’s ``.desktop`` file. The
parameter is the application ID, as above.
``action <APP-ID> <ACTION> [PARAMETER]``
Invokes the named action (in the same way as would occur when activating an
action specified in the ``.desktop`` file).
The application ID (as above) is the first parameter. The action name
follows.
Optionally, following the action name can be one parameter, in GVariant
format, given as a single argument. Make sure to use sufficient quoting.
EXAMPLES
--------
From the commandline
^^^^^^^^^^^^^^^^^^^^
Launching an application::
gapplication launch org.example.fooview
Opening a file with an application::
gapplication launch org.example.fooview ~/file.foo
Opening many files with an application::
gapplication launch org.example.fooview ~/foos/*.foo
Invoking an action on an application::
gapplication action org.example.fooview create
Invoking an action on an application, with an action::
gapplication action org.example.fooview show-item '"item_id_828739"'
From the ``Exec`` lines of a ``.desktop`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The commandline interface of ``gapplication`` was designed so that it could be
used directly from the ``Exec`` line of a ``.desktop`` file.
You might want to do this to allow for backwards compatibility with
implementations of the specification that do not understand how to do D-Bus
activation, without having to install a separate utility program.
Consider the following example::
[Desktop Entry]
Version=1.1
Type=Application
Name=Foo Viewer
DBusActivatable=true
MimeType=image/x-foo;
Exec=gapplication launch org.example.fooview %F
Actions=gallery;create;
[Desktop Action gallery]
Name=Browse Gallery
Exec=gapplication action org.example.fooview gallery
[Desktop Action create]
Name=Create a new Foo!
Exec=gapplication action org.example.fooview create
From a script
^^^^^^^^^^^^^
If installing an application that supports D-Bus activation you may still want
to put a file in ``/usr/bin`` so that your program can be started from a
terminal.
It is possible for this file to be a shell script. The script can handle
arguments such as ``--help`` and ``--version`` directly. It can also parse
other command line arguments and convert them to uses of ``gapplication`` to
activate the application, open files, or invoke actions.
Here is a simplified example, as may be installed in ``/usr/bin/fooview``::
#!/bin/sh
case "$1" in
--help)
echo "see ‘man fooview’ for more information"
;;
--version)
echo "fooview 1.2"
;;
--gallery)
gapplication action org.example.fooview gallery
;;
--create)
gapplication action org.example.fooview create
;;
-*)
echo "unrecognised commandline argument"
exit 1
;;
*)
gapplication launch org.example.fooview "$@"
;;
esac
SEE ALSO
--------
`Desktop Entry Specification <https://specifications.freedesktop.org/desktop-entry-spec/latest/>`_,
`gdbus(1) <man:gdbus(1)>`_,
`xdg-open(1) <man:xdg-open(1)>`_,
`desktop-file-validate(1) <man:desktop-file-validate(1)>`_

352
docs/reference/gio/gapplication.xml
View File

@ -1,352 +0,0 @@
<refentry id="gapplication-tool" lang="en">
<refentryinfo>
<title>gapplication</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gapplication</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gapplication</refname>
<refpurpose>D-Bus application launcher</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-apps</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-actions</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">action</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gapplication</command> is a commandline implementation of the client-side of the
<interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
Desktop Entry Specification.
</para>
<para>
<command>gapplication</command> can be used to start applications that have
<varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
files and can be used to send messages to already-running instances of other applications.
</para>
<para>
It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
with implementations that do not directly support <varname>DBusActivatable</varname>.
</para>
<para>
<command>gapplication</command> ships as part of <application>GLib</application>.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<refsect2>
<title>Global commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>
Displays a short synopsis of the available commands or provides detailed help on a specific
command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>
Prints the GLib version whence <command>gapplication</command> came.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-apps</command>
</term>
<listitem>
<para>
Prints a list of all application IDs that are known to support D-Bus activation. This list is
generated by scanning <filename class='extension'>.desktop</filename> files as per the current
<envar>XDG_DATA_DIRS</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>launch</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</term>
<listitem>
<para>
Launches an application.
</para>
<para>
The first parameter is the application ID in the familiar "reverse DNS" style (eg:
'<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
suffix.
</para>
<para>
Optionally, if additional parameters are given, they are treated as the names of files to open and
may be filenames or URIs. If no files are given then the application is simply activated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-actions</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</term>
<listitem>
<para>
List the actions declared in the application's <filename class='extension'>.desktop</filename>
file. The parameter is the application ID, as above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>action</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</term>
<listitem>
<para>
Invokes the named action (in the same way as would occur when activating an action specified in
the <filename class='extension'>.desktop</filename> file).
</para>
<para>
The application ID (as above) is the first parameter. The action name follows.
</para>
<para>
Optionally, following the action name can be one parameter, in GVariant format, given as a single
argument. Make sure to use sufficient quoting.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect2>
<title>From the commandline</title>
<para>
Launching an application:
</para>
<programlisting>
gapplication launch org.example.fooview
</programlisting>
<para>
Opening a file with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/file.foo
</programlisting>
<para>
Opening many files with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/foos/*.foo
</programlisting>
<para>
Invoking an action on an application:
</para>
<programlisting>
gapplication action org.example.fooview create
</programlisting>
<para>
Invoking an action on an application, with an action:
</para>
<programlisting>
gapplication action org.example.fooview show-item '"item_id_828739"'
</programlisting>
</refsect2>
<refsect2>
<title>
From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
</title>
<para>
The commandline interface of <command>gapplication</command> was designed so that it could be used
directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
file.
</para>
<para>
You might want to do this to allow for backwards compatibility with implementations of the specification
that do not understand how to do D-Bus activation, without having to install a separate utility program.
</para>
<para>
Consider the following example:
</para>
<programlisting>
[Desktop Entry]
Version=1.1
Type=Application
Name=Foo Viewer
DBusActivatable=true
MimeType=image/x-foo;
Exec=gapplication launch org.example.fooview %F
Actions=gallery;create;
[Desktop Action gallery]
Name=Browse Gallery
Exec=gapplication action org.example.fooview gallery
[Desktop Action create]
Name=Create a new Foo!
Exec=gapplication action org.example.fooview create
</programlisting>
</refsect2>
<refsect2>
<title>From a script</title>
<para>
If installing an application that supports D-Bus activation you may still want to put a file in
<filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
</para>
<para>
It is possible for this file to be a shell script. The script can handle arguments such as --help and
--version directly. It can also parse other command line arguments and convert them to uses of
<command>gapplication</command> to activate the application, open files, or invoke actions.
</para>
<para>
Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
</para>
<programlisting>
#!/bin/sh
case "$1" in
--help)
echo "see 'man fooview' for more information"
;;
--version)
echo "fooview 1.2"
;;
--gallery)
gapplication action org.example.fooview gallery
;;
--create)
gapplication action org.example.fooview create
;;
-*)
echo "unrecognised commandline argument"
exit 1
;;
*)
gapplication launch org.example.fooview "$@"
;;
esac
</programlisting>
</refsect2>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
<citerefentry>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>xdg-open</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>desktop-file-validate</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

805
docs/reference/gio/gdbus-codegen.rst Normal file
View File

@ -0,0 +1,805 @@
.. _gdbus-codegen(1):
.. meta::
:copyright: Copyright 2011, 2013, 2016 Red Hat, Inc.
:copyright: Copyright 2013, 2022 Emmanuele Bassi
:copyright: Copyright 2017 Patrick Griffis
:copyright: Copyright 2018 Iñigo Martínez
:copyright: Copyright 2018, 2019 Endless Mobile, Inc.
:copyright: Copyright 2020 Endless OS Foundation, LLC
:copyright: Copyright 2020 Chun-wei Fan
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2011, 2013, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2013, 2022 Emmanuele Bassi
SPDX-FileCopyrightText: 2017 Patrick Griffis
SPDX-FileCopyrightText: 2018 Iñigo Martínez
SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
SPDX-FileCopyrightText: 2020 Chun-wei Fan
SPDX-License-Identifier: LGPL-2.1-or-later
=============
gdbus-codegen
=============
--------------------------------------
D-Bus code and documentation generator
--------------------------------------
SYNOPSIS
--------
| **gdbus-codegen**
| [--help]
| [--interface-prefix *org.project.Prefix*]
| [--header | --body | --interface-info-header | --interface-info-body | --generate-c-code *OUTFILES*]
| [--c-namespace *YourProject*]
| [--c-generate-object-manager]
| [--c-generate-autocleanup none|objects|all]
| [--output-directory *OUTDIR* | --output *OUTFILE*]
| [--generate-docbook *OUTFILES*]
| [--generate-rst *OUTFILES*]
| [--pragma-once]
| [--xml-files *FILE*]
| [--symbol-decorator *DECORATOR* [--symbol-decorator-header *HEADER*] [--symbol-decorator-define *DEFINE*]]
| [--annotate *ELEMENT* *KEY* *VALUE*]…
| [--glib-min-required *VERSION*]
| [--glib-max-allowed *VERSION*]
| *FILE*…
DESCRIPTION
-----------
``gdbus-codegen`` is used to generate code and/or documentation for one or more
D-Bus interfaces.
``gdbus-codegen`` reads
`D-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
from files passed as additional arguments on the command line and generates
output files. It currently supports generating C source code (via ``--body``) or
header (via ``--header``) and DocBook XML (via ``--generate-docbook``).
Alternatively, more restricted C source code and headers can be generated, which
just contain the interface information (as ``GDBusInterfaceInfo`` structures)
using ``--interface-info-body`` and ``--interface-info-header``.
GENERATING C CODE
-----------------
When generating C code, a ``GInterface`` derived type is generated for each
D-Bus interface. Additionally, for every generated type, ``FooBar``, two
concrete instantiatable types, ``FooBarProxy`` and ``FooBarSkeleton``,
implementing said interface are also generated. The former is derived from
``GDBusProxy`` and intended for use on the client side while the latter is
derived from the ``GDBusInterfaceSkeleton`` type making it easy to export on a
``GDBusConnection`` either directly or via a ``GDBusObjectManagerServer``
instance.
For C code generation either ``--body`` that generates source code, ``--header``
that generates headers, ``--interface-info-body`` that generates interface
information source code, or ``--interface-info-header`` that generates interface
information headers, can be used. These options must be used along with
``--output``, which is used to specify the file to output to.
Both files can be generated at the same time by using ``--generate-c-code``, but
this option is deprecated. In this case ``--output`` cannot be used due to the
generation of multiple files. Instead pass ``--output-directory`` to specify the
directory to put the output files in. By default the current directory will be
used.
The name of each generated C type is derived from the D-Bus interface name
stripped with the prefix given with ``--interface-prefix`` and with the dots
removed and initial characters capitalized. For example, for the D-Bus
interface ``com.acme.Coyote`` the name used is ``ComAcmeCoyote``. For the D-Bus
interface ``org.project.Bar.Frobnicator`` with ``--interface-prefix`` set to
``org.project.``, the name used is ``BarFrobnicator``.
For methods, signals and properties, if not specified, the name defaults to the
name of the method, signal or property.
Two forms of the name are used — the CamelCase form and the lower-case form. The
CamelCase form is used for the ``GType`` and struct name, while lower-case form
is used in function names. The lower-case form is calculated by converting from
CamelCase to lower-case and inserting underscores at word boundaries (using
certain heuristics).
If the value given by the ``org.gtk.GDBus.C.Name`` annotation or the
``--c-namespace`` option contains an underscore (sometimes called *Ugly_Case*),
then the camel-case name is derived by removing all underscores, and the
lower-case name is derived by lower-casing the string. This is useful in some
situations where abbreviations are used. For example, if the annotation is used
on the interface ``net.MyCorp.MyApp.iSCSITarget`` with the value
``iSCSI_Target`` the CamelCase form is ``iSCSITarget`` while the lower-case form
is ``iscsi_target``. If the annotation is used on the method ``EjectTheiPod``
with the value ``Eject_The_iPod``, the lower-case form is ``eject_the_ipod``.
GENERATING DOCBOOK DOCUMENTATION
--------------------------------
Each generated DocBook XML file (see the ``--generate-docbook`` option for
details) is a ``RefEntry`` article describing the D-Bus interface. (See the
`DocBook documentation <https://tdg.docbook.org/tdg/4.5/refentry.html>`_.)
GENERATING RESTRUCTUREDTEXT DOCUMENTATION
-----------------------------------------
Each generated reStructuredText file (see the ``--generate-rst`` option for
details) is a plain text
`reStructuredText <https://docutils.sourceforge.io/rst.html>`_ document
describing the D-Bus interface.
OPTIONS
-------
The following options are supported:
``-h``, ``--help``
Show help and exit.
``--xml-files`` *FILE*
This option is deprecated; use positional arguments instead. The D-Bus
introspection XML file.
``--interface-prefix`` *org.project.Prefix.*
A prefix to strip from all D-Bus interface names when
calculating the type name for the C binding and the DocBook ``sortas``
`attribute <https://tdg.docbook.org/tdg/4.5/primary.html>`_.
``--generate-docbook`` *OUTFILES*
Generate DocBook Documentation for each D-Bus interface and put it in
``OUTFILES-NAME.xml`` where ``NAME`` is a placeholder for the interface
name, e.g. ``net.Corp.FooBar`` and so on.
Pass ``--output-directory`` to specify the directory to put the output files
in. By default the current directory will be used.
``--generate-rst`` *OUTFILES*
Generate reStructuredText Documentation for each D-Bus interface and put it in
``OUTFILES-NAME.rst`` where ``NAME`` is a placeholder for the interface
name, e.g. ``net.Corp.FooBar`` and so on.
Pass ``--output-directory`` to specify the directory to put the output files
in. By default the current directory will be used.
``--generate-c-code`` *OUTFILES*
Generate C code for all D-Bus interfaces and put it in ``OUTFILES.c`` and
``OUTFILES.h`` including any sub-directories. If you want the files to be
output in a different location use ``--output-directory`` as ``OUTFILES.h``
including sub-directories will be referenced from ``OUTFILES.c``.
The full paths would then be
``$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}``.
``--c-namespace`` *YourProject*
The namespace to use for generated C code. This is expected to be in
`CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
above).
``--pragma-once``
If this option is passed, the
`#pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_ preprocessor
directive is used instead of include guards.
``--c-generate-object-manager``
If this option is passed, suitable ``GDBusObject``, ``GDBusObjectProxy``,
``GDBusObjectSkeleton`` and ``GDBusObjectManagerClient`` subclasses are
generated.
``--c-generate-autocleanup`` none|objects|all
This option influences what types autocleanup functions are
generated for. ``none`` means to not generate any autocleanup functions.
``objects`` means to generate them for object types, and ``all`` means to
generate them for object types and interfaces. The default is ``objects``
due to a corner case in backwards compatibility with a few projects,
but you should likely switch your project to use ``all``.
This option was added in GLib 2.50.
``--output-directory`` *OUTDIR*
Directory to output generated source to. Equivalent to changing directory
before generation.
This option cannot be used with ``--body``, ``--header``,
``--interface-info-body`` or ``--interface-info-header``; and ``--output``
must be used.
``--header``
If this option is passed, it will generate the header code and write it to the
disk by using the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with ``--header`` and ``--body`` options,
because these options are used to generate only one file.
``--body``
If this option is passed, it will generate the source code and write it to the
disk by using the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with ``--header`` and ``--body`` options,
because these options are used to generate only one file.
``--interface-info-header``
If this option is passed, it will generate the header code for the
``GDBusInterfaceInfo`` structures only and will write it to the disk by using
the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with the ``--interface-info-header`` and
``--interface-info-body`` options, because these options are used to generate
only one file.
``--interface-info-body``
If this option is passed, it will generate the source code for the
``GDBusInterfaceInfo`` structures only and will write it to the disk by using
the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with the ``--interface-info-header`` and
``--interface-info-body`` options, because these options are used to generate
only one file.
``--symbol-decorator`` *DECORATOR*
If a ``DECORATOR`` is passed in with this option, all the generated function
prototypes in the generated header will be marked with ``DECORATOR``. This can
be used, for instance, to export symbols from code generated with
``gdbus-codegen``.
This option was added in GLib 2.66.
``--symbol-decorator-header`` *HEADER*
If a ``HEADER`` is passed in with this option, the generated header will put a
``#include HEADER`` before the rest of the items, except for the inclusion
guards or ``#pragma once`` (if ``--pragma-once`` is used). This is used if
using another header file is needed for the decorator passed in via
``--symbol-decorator`` to be defined.
This option was added in GLib 2.66.
This option can only be used if ``--symbol-decorator`` is used.
``--symbol-decorator-define`` *DEFINE*
If a ``DEFINE`` is passed in with this option, the generated source will add a
``#define DEFINE`` before the rest of the items. This is used if a particular
macro is needed to ensure the decorator passed in via ``--symbol-decorator``
uses the correct definition when the generated source is being compiled.
This option was added in GLib 2.66.
This option can only be used if ``--symbol-decorator`` is used.
``--output`` *OUTFILE*
The full path where the header (``--header``, ``--interface-info-header``) or
the source code (``--body``, ``--interface-info-body``) will be written, using
the path and filename provided by ``--output``. The full path could be
something like ``$($OUTFILE).{c,h}``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
is not allowed along with ``--output``, because the latter is used to generate
only one file.
``--annotate`` *ELEMENT* *KEY* *VALUE*
Used to inject D-Bus annotations into the given XML files. It can be used with
interfaces, methods, signals, properties and arguments in the following way::
gdbus-codegen --c-namespace MyApp \
--generate-c-code myapp-generated \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.Name MyFrobnicator \
--annotate "org.project.InterfaceName:Property" \
bar bat \
--annotate "org.project.InterfaceName.Method()" \
org.freedesktop.DBus.Deprecated true \
--annotate "org.project.InterfaceName.Method()[arg_name]" \
snake hiss \
--annotate "org.project.InterfaceName::Signal" \
cat meow \
--annotate "org.project.InterfaceName::Signal[arg_name]" \
dog wuff \
myapp-dbus-interfaces.xml
Any UTF-8 string can be used for *KEY* and *VALUE*.
``--glib-min-required`` *VERSION*
Specifies the minimum version of GLib which the code generated by
``gdbus-codegen`` can depend on. This may be used to make
backwards-incompatible changes in the output or behaviour of ``gdbus-codegen``
in future, which users may opt in to by increasing the value they pass for
``--glib-min-required``. If this option is not passed, the output from
``gdbus-codegen`` is guaranteed to be compatible with all versions of GLib
from 2.30 upwards, as that is when ``gdbus-codegen`` was first released.
Note that some version parameters introduce incompatible changes: all callers
of the generated code might need to be updated, and if the generated code is
part of a library’s API or ABI, then increasing the version parameter can
result in an API or ABI break.
The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
are integers. ``MINOR`` and ``MICRO`` are optional. The version number may not
be smaller than ``2.30``.
If the version number is ``2.64`` or greater, the generated code will
have the following features:
1. If a method has ``h`` (file descriptor) parameter(s), a ``GUnixFDList``
parameter will exist in the generated code for it (whereas previously the
annotation ``org.gtk.GDBus.C.UnixFD`` was required), and
2. Method call functions will have two additional arguments to allow the user
to specify ``GDBusCallFlags`` and a timeout value, as is possible when
using ``g_dbus_proxy_call()``.
``--glib-max-allowed`` *VERSION*
Specifies the maximum version of GLib which the code generated by
``gdbus-codegen`` can depend on. This may be used to ensure that code
generated by ``gdbus-codegen`` is compilable with specific older versions of
GLib that your software has to support.
The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
are integers. ``MINOR`` and ``MICRO`` are optional. The version number must be
greater than or equal to that passed to ``--glib-min-required``.
It defaults to the version of GLib which provides this ``gdbus-codegen``.
SUPPORTED D-BUS ANNOTATIONS
---------------------------
The following D-Bus annotations are supported by ``gdbus-codegen``:
``org.freedesktop.DBus.Deprecated``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify that the element is deprecated if its value
is ``true``. Note that this annotation is defined in the
`D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
and can only assume the values ``true`` and ``false``. In particular, you
cannot specify the version that the element was deprecated in nor any helpful
deprecation message. Such information should be added to the element
documentation instead.
When generating C code, this annotation is used to add ``G_GNUC_DEPRECATED``
to generated functions for the element.
When generating DocBook XML, a deprecation warning will appear along the
documentation for the element.
``org.gtk.GDBus.Since``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify the version (any free-form string but
compared using a version-aware sort function) the element appeared in.
When generating C code, this field is used to ensure
function pointer order for preserving ABI/API, see ‘STABILITY GUARANTEES’.
When generating DocBook XML, the value of this tag appears in the
documentation.
``org.gtk.GDBus.DocString``
A string with DocBook content for documentation. This annotation can
be used on ``<interface>``, ``<method>``, ``<signal>``, ``<property>`` and
``<arg>`` elements.
``org.gtk.GDBus.DocString.Short``
A string with DocBook content for short/brief documentation. This annotation
can only be used on ``<interface>`` elements.
``org.gtk.GDBus.C.Name``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify the name to use when generating C code. The
value is expected to be in
`CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
above).
``org.gtk.GDBus.C.ForceGVariant``
If set to a non-empty string, a ``GVariant`` instance will be used instead of
the natural C type. This annotation can be used on any ``<arg>`` and
``<property>`` element.
``org.gtk.GDBus.C.UnixFD``
If set to a non-empty string, the generated code will include parameters to
exchange file descriptors using the ``GUnixFDList`` type. This annotation can
be used on ``<method>`` elements.
As an easier alternative to using the ``org.gtk.GDBus.DocString`` annotation,
note that parser used by ``gdbus-codegen`` parses XML comments in a way similar
to `gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_::
<!--
net.Corp.Bar:
@short_description: A short description
A <emphasis>longer</emphasis> description.
This is a new paragraph.
-->
<interface name="net.corp.Bar">
<!--
FooMethod:
@greeting: The docs for greeting parameter.
@response: The docs for response parameter.
The docs for the actual method.
-->
<method name="FooMethod">
<arg name="greeting" direction="in" type="s"/>
<arg name="response" direction="out" type="s"/>
</method>
<!--
BarSignal:
@blah: The docs for blah parameter.
@boo: The docs for boo parameter.
@since: 2.30
The docs for the actual signal.
-->
<signal name="BarSignal">
<arg name="blah" type="s"/>
<arg name="boo" type="s"/>
</signal>
<!-- BazProperty: The docs for the property. -->
<property name="BazProperty" type="s" access="read"/>
</interface>
Note that ``@since`` can be used in any inline documentation bit (e.g. for
interfaces, methods, signals and properties) to set the ``org.gtk.GDBus.Since``
annotation. For the ``org.gtk.GDBus.DocString`` annotation (and inline
comments), note that substrings of the form ``#net.Corp.Bar``,
``net.Corp.Bar.FooMethod()``, ``#net.Corp.Bar::BarSignal`` and
``#net.Corp.InlineDocs:BazProperty`` are all expanded to links to the respective
interface, method, signal and property. Additionally, substrings starting with
``@`` and ``%`` characters are rendered as
`parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>`_ and
`constant <https://tdg.docbook.org/tdg/4.5/constant.html>`_ respectively.
If both XML comments and ``org.gtk.GDBus.DocString`` or
``org.gtk.GDBus.DocString.Short`` annotations are present, the latter wins.
EXAMPLE
-------
Consider the following D-Bus Introspection XML::
<node>
<interface name="net.Corp.MyApp.Frobber">
<method name="HelloWorld">
<arg name="greeting" direction="in" type="s"/>
<arg name="response" direction="out" type="s"/>
</method>
<signal name="Notification">
<arg name="icon_blob" type="ay"/>
<arg name="height" type="i"/>
<arg name="messages" type="as"/>
</signal>
<property name="Verbose" type="b" access="readwrite"/>
</interface>
</node>
If ``gdbus-codegen`` is used on this file like this::
gdbus-codegen --generate-c-code myapp-generated \
--c-namespace MyApp \
--interface-prefix net.corp.MyApp. \
net.Corp.MyApp.Frobber.xml
two files called ``myapp-generated.[ch]`` are generated. The files provide an
abstract ``GTypeInterface`` derived type called ``MyAppFrobber`` as well as two
instantiatable types with the same name but suffixed with ``Proxy`` and
``Skeleton``. The generated file, roughly, contains the following facilities::
/* GType macros for the three generated types */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
typedef struct
{
GTypeInterface parent_iface;
/* Signal handler for the ::notification signal */
void (*notification) (MyAppFrobber *proxy,
GVariant *icon_blob,
gint height,
const gchar* const *messages);
/* Signal handler for the ::handle-hello-world signal */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *invocation,
const gchar *greeting);
} MyAppFrobberIface;
/* Asynchronously calls HelloWorld() */
void
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
const gchar *greeting,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gp ointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
gchar **out_response,
GAsyncResult *res,
GError **error);
/* Synchronously calls HelloWorld(). Blocks calling thread. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
const gchar *greeting,
gchar **out_response,
GCancellable *cancellable,
GError **error);
/* Completes handling the HelloWorld() method call */
void
my_app_frobber_complete_hello_world (MyAppFrobber *object,
GDBusMethodInvocation *invocation,
const gchar *response);
/* Emits the ::notification signal / Notification() D-Bus signal */
void
my_app_frobber_emit_notification (MyAppFrobber *object,
GVariant *icon_blob,
gint height,
const gchar* const *messages);
/* Gets the :verbose GObject property / Verbose D-Bus property.
* Does no blocking I/O.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
/* Sets the :verbose GObject property / Verbose D-Bus property.
* Does no blocking I/O.
*/
void my_app_frobber_set_verbose (MyAppFrobber *object,
gboolean value);
/* Gets the interface info */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);
/* Creates a new skeleton object, ready to be exported */
MyAppFrobber *my_app_frobber_skeleton_new (void);
/* Client-side proxy constructors.
*
* Additionally, _new_for_bus(), _new_for_bus_finish() and
* _new_for_bus_sync() proxy constructors are also generated.
*/
void
my_app_frobber_proxy_new (GDBusConnection *connection,
GDBusProxyFlags flags,
const gchar *name,
const gchar *object_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **error);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *connection,
GDBusProxyFlags flags,
const gchar *name,
const gchar *object_path,
GCancellable *cancellable,
GError **error);
Thus, for every D-Bus method, there will be three C functions for calling the
method, one ``GObject`` signal for handling an incoming call and one C function
for completing an incoming call. For every D-Bus signal, there’s one ``GObject``
signal and one C function for emitting it. For every D-Bus property, two C
functions are generated (one setter, one getter) and one ``GObject`` property.
The following table summarizes the generated facilities and where they are
applicable:
.. table::
:widths: auto
==================== ========================================================= =================================================================================================================
Symbol type Client Server
==================== ========================================================= =================================================================================================================
Types Use ``MyAppFrobberProxy``. Any type implementing the ``MyAppFrobber`` interface.
Methods Use ``m_a_f_hello_world()`` to call. Receive via the ``handle_hello_world()`` signal handler. Complete the call with ``m_a_f_complete_hello_world()``.
Signals Connect to the ``::notification`` signal. Use ``m_a_f_emit_notification()`` to emit signal.
Properties (Reading) Use ``m_a_f_get_verbose()`` or the ``:verbose`` property. Implement the ``get_property()`` vfunc of ``GObject``.
Properties (writing) Use ``m_a_f_set_verbose()`` or the ``:verbose`` property. Implement the ``set_property()`` vfunc of ``GObject``.
==================== ========================================================= =================================================================================================================
Client-side usage
^^^^^^^^^^^^^^^^^
You can use the generated proxy type with the generated constructors::
MyAppFrobber *proxy;
GError *error;
error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* bus name */
"/net/Corp/MyApp/SomeFrobber", /* object */
NULL, /* GCancellable* */
&error);
/* do stuff with proxy */
g_object_unref (proxy);
Instead of using the generic ``GDBusProxy`` facilities, one can use the
generated methods such as ``my_app_frobber_call_hello_world()`` to invoke
the ``net.Corp.MyApp.Frobber.HelloWorld()`` D-Bus method, connect to the
``::notification`` ``GObject`` signal to receive the
``net.Corp.MyApp.Frobber::Notification`` D-Bus signal and get/set the
``net.Corp.MyApp.Frobber:Verbose`` D-Bus Property using either the ``GObject``
property ``:verbose`` or the ``my_app_get_verbose()`` and
``my_app_set_verbose()`` methods. Use the standard ``GObject::notify`` signal to
listen to property changes.
Note that all property access is via the ``GDBusProxy`` property cache so no I/O
is ever done when reading properties. Also note that setting a property will
cause the ``org.freedesktop.DBus.Properties.Set`` method
(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
to be called on the remote object. This call, however, is asynchronous so
setting a property won’t block. Further, the change is delayed and no error
checking is possible.
Server-side usage
^^^^^^^^^^^^^^^^^
The generated ``MyAppFrobber`` interface is designed so it is easy to implement
it in a ``GObject`` subclass. For example, to handle ``HelloWorld()`` method
invocations, set the vfunc for ``handle_hello_hello_world()`` in the
``MyAppFrobberIface`` structure. Similarly, to handle the
``net.Corp.MyApp.Frobber:Verbose`` property override the ``:verbose``
``GObject`` property from the subclass. To emit a signal, use e.g.
``my_app_emit_signal()`` or ``g_signal_emit_by_name()``.
Instead of subclassing, it is often easier to use the generated
``MyAppFrobberSkeleton`` subclass. To handle incoming method calls, use
``g_signal_connect()`` with the ``::handle-*`` signals and instead of
overriding the ``get_property()`` and ``set_property()`` vfuncs from
``GObject``, use ``g_object_get()`` and ``g_object_set()`` or the generated
property getters and setters (the generated class has an internal property bag
implementation).
For example::
static gboolean
on_handle_hello_world (MyAppFrobber *interface,
GDBusMethodInvocation *invocation,
const gchar *greeting,
gpointer user_data)
{
if (g_strcmp0 (greeting, "Boo") != 0)
{
gchar *response;
response = g_strdup_printf ("Word! You said ‘%s’.", greeting);
my_app_complete_hello_world (interface, invocation, response);
g_free (response);
}
else
{
g_dbus_method_invocation_return_error (invocation,
MY_APP_ERROR,
MY_APP_ERROR_NO_WHINING,
"Hey, %s, there will be no whining!",
g_dbus_method_invocation_get_sender (invocation));
}
return TRUE;
}
[…]
interface = my_app_frobber_skeleton_new ();
my_app_frobber_set_verbose (interface, TRUE);
g_signal_connect (interface,
"handle-hello-world",
G_CALLBACK (on_handle_hello_world),
some_user_data);
[…]
error = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
connection,
"/path/of/dbus_object",
&error))
{
/* handle error */
}
To facilitate atomic changesets (multiple properties changing at the same time),
``GObject::notify`` signals are queued up when received. The queue is drained in
an idle handler (which is called from the thread-default main loop of the thread
where the skeleton object was constructed) and will cause emissions of the
``org.freedesktop.DBus.Properties::PropertiesChanged``
(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
signal with all the properties that have changed. Use
``g_dbus_interface_skeleton_flush()`` or ``g_dbus_object_skeleton_flush()`` to
empty the queue immediately. Use ``g_object_freeze_notify()`` and
``g_object_thaw_notify()`` for atomic changesets if on a different thread.
C TYPE MAPPING
--------------
Scalar types (type strings ``b``, ``y``, ``n``, ``q``, ``i``, ``u``, ``x``,
``t`` and ``d``), strings (type strings ``s``, ``ay``, ``o`` and ``g``) and
arrays of strings (type strings ``as``, ``ao`` and ``aay``) are mapped to the
natural types, e.g. ``gboolean``, ``gdouble``, ``gint``, ``gchar*``, ``gchar**``
and so on. Everything else is mapped to the ``GVariant`` type.
This automatic mapping can be turned off by using the annotation
``org.gtk.GDBus.C.ForceGVariant`` — if used then a ``GVariant`` is always
exchanged instead of the corresponding native C type. This annotation may be
convenient to use when using bytestrings (type string ``ay``) for data that
could have embedded nul bytes.
STABILITY GUARANTEES
--------------------
The generated C functions are guaranteed to not change their ABI. That is, if a
method, signal or property does not change its signature in the introspection
XML, the generated C functions will not change their C ABI either. The ABI of
the generated instance and class structures will be preserved as well.
The ABI of the generated ``GType`` instances will be preserved only if the
``org.gtk.GDBus.Since`` annotation is used judiciously — this is because the
VTable for the ``GInterface`` relies on function pointers for signal handlers.
Specifically, if a D-Bus method, property or signal or is added to a D-Bus
interface, then ABI of the generated ``GInterface`` type is preserved if, and
only if, each added method, property signal is annotated with the
``org.gtk.GDBus.Since`` annotation using a greater version number than previous
versions.
The generated C code currently happens to be annotated with
`gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_ and
`GObject Introspection <https://gi.readthedocs.io/en/latest/>`_ comments and
annotations. The layout and contents might change in the future so no guarantees
about e.g. ``SECTION`` usage etc. are given.
While the generated DocBook for D-Bus interfaces isn’t expected to change, no
guarantees are given at this point.
It is important to note that the generated code should not be checked into
version control systems, nor it should be included in distributed source
archives.
BUGS
----
Please send bug reports to either the distribution bug tracker or the
`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
SEE ALSO
--------
`gdbus(1) <man:gdbus(1)>`_

1193
docs/reference/gio/gdbus-codegen.xml
View File

File diff suppressed because it is too large Load Diff

278
docs/reference/gio/gdbus.rst Normal file
View File

@ -0,0 +1,278 @@
.. _gdbus(1):
.. meta::
:copyright: Copyright 2010, 2011, 2012, 2020 Red Hat, Inc.
:copyright: Copyright 2015 Collabora, Ltd.
:copyright: Copyright 2021 Endless OS Foundation, LLC
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2012, 2020 Red Hat, Inc.
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2021 Endless OS Foundation, LLC
SPDX-License-Identifier: LGPL-2.1-or-later
=====
gdbus
=====
-----------------------------------
Tool for working with D-Bus objects
-----------------------------------
SYNOPSIS
--------
| **gdbus** introspect [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* [--xml] [--recurse] [--only-properties]
| **gdbus** monitor [--system | --session | --address *address*] --dest *bus_name* [--object-path */path/to/object*]
| **gdbus** call [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* --method *org.project.InterfaceName.MethodName* [--timeout *seconds* | --interactive] [*ARG*…]
| **gdbus** emit [--system | --session | --address *address*] --object-path */path/to/object* --signal *org.project.InterfaceName.SignalName* [--dest *unique_bus_name*] [*ARG*…]
| **gdbus** wait [--system | --session | --address *address*] --activate *bus_name* [--timeout *seconds*] *bus_name*
| **gdbus** help
DESCRIPTION
-----------
``gdbus`` is a simple tool for working with D-Bus objects.
COMMANDS
--------
``introspect``
Prints out interfaces and property values for a remote object. For this to
work, the owner of the object needs to implement the
``org.freedesktop.DBus.Introspectable`` interface. If the ``--xml`` option is
used, the returned introspection XML is printed, otherwise a parsed pretty
representation is printed. The ``--recurse`` option can be used to introspect
children (and their children and so on) and the ``--only-properties`` option
can be used to only print the interfaces with properties.
``monitor``
Monitors one or all objects owned by the owner of ``bus_name``.
``call``
Invokes a method on a remote object. Each argument to pass to the method must
be specified as a serialized ``GVariant`` except that strings do not need
explicit quotes. The return values are printed out as serialized ``GVariant``
values.
``emit``
Emits a signal. Each argument to include in the signal must be specified as a
serialized ``GVariant`` except that strings do not need explicit quotes.
``wait``
Waits until ``bus_name`` is owned by some process on the bus. If the
``--activate`` is specified, that bus name will be auto-started first. It may
be the same as the bus name being waited for, or different.
``help``
Prints help and exits.
BASH COMPLETION
---------------
``gdbus`` ships with a bash completion script to complete commands,
destinations, bus names, object paths and interface/method names.
EXAMPLES
--------
This shows how to introspect an object — note that the value of each property is
displayed::
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
The ``--recurse`` and ``--only-properties`` options can be useful when wanting
to inspect all objects owned by a particular process::
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
In a similar fashion, the ``introspect`` command can be used to learn details
about the ``Notify`` method::
[…]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[…]
With this information, it’s easy to use the ``call`` command to display a
notification::
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here’s the body of the notification" \
[] \
{} \
5000
(uint32 12,)
Call a method with file handle argument::
$ gdbus call --session \
--dest org.example.foo \
--object-path /org/example/foo \
--method SendFDs \
1 \
10 \
10<file.foo
Monitoring all objects on a service::
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
Monitoring a single object on a service::
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
Emitting a signal::
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
Emitting a signal to a specific process::
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
Waiting for a well-known name to be owned on the bus; this will *not* auto-start
the service::
$ gdbus wait --session org.bar.SomeName
Auto-starting then waiting for a well-known name to be owned on the bus::
$ gdbus wait --session --activate org.bar.SomeName
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where ``SomeName`` is not
directly activatable::
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
Waiting for a well-known name and giving up after 30 seconds. By default, the
timeout is disabled; or set ``--timeout`` to ``0`` to disable it::
$ gdbus wait --session --timeout 30 org.bar.SomeName
BUGS
----
Please send bug reports to either the distribution bug tracker or the
`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
SEE ALSO
--------
`dbus-send(1) <man:dbus-send(1)>`_

429
docs/reference/gio/gdbus.xml
View File

@ -1,429 +0,0 @@
<refentry id="gdbus" lang="en">
<refentryinfo>
<title>gdbus</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<email>zeuthen@gmail.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gdbus</refname>
<refpurpose>Tool for working with D-Bus objects</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">introspect</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<group>
<arg choice="plain">--xml</arg>
</group>
<group>
<arg choice="plain">--recurse</arg>
</group>
<group>
<arg choice="plain">--only-properties</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">monitor</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">call</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
<arg choice="plain">--interactive</arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">emit</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
<group>
<arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">wait</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
</group>
<arg choice="plain"><replaceable>bus_name</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gdbus</command> is a simple tool for working with D-Bus objects.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term><option>introspect</option></term>
<listitem><para>
Prints out interfaces and property values for a remote object.
For this to work, the owner of the object needs to implement the
<literal>org.freedesktop.DBus.Introspectable</literal> interface.
If the <option>--xml</option> option is used, the returned
introspection XML is printed, otherwise a parsed pretty
representation is printed.
The <option>--recurse</option> option can be used to
introspect children (and their children and so on) and the
<option>--only-properties</option> option can be used to
only print the interfaces with properties.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors one or all objects owned by the owner of
<replaceable>bus_name</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>call</option></term>
<listitem><para>
Invokes a method on a remote object. Each argument to pass to the
method must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes. The return values are printed out as
serialized <link linkend="GVariant"><type>GVariant</type></link>
values.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>emit</option></term>
<listitem><para>
Emits a signal. Each argument to include in the signal must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>wait</option></term>
<listitem><para>
Waits until <replaceable>bus_name</replaceable> is owned by some
process on the bus. If the <option>--activate</option> is specified,
that bus name will be auto-started first. It may be the same as the
bus name being waited for, or different.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Bash Completion</title>
<para>
<command>gdbus</command> ships with a bash completion script to
complete commands, destinations, bus names, object paths and
interface/method names.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
This shows how to introspect an object - note that the value of each
property is displayed:
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
</programlisting>
<para>
The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
</para>
<programlisting>
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
</programlisting>
<para>
In a similar fashion, the <option>introspect</option> command can be
used to learn details about the <literal>Notify</literal> method:
</para>
<programlisting>
[...]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[...]
</programlisting>
<para>
With this information, it's easy to use the <option>call</option>
command to display a notification
</para>
<programlisting>
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here's the body of the notification" \
[] \
{} \
5000
(uint32 12,)
</programlisting>
<para>
Call a method with file handle argument:
</para>
<programlisting>
$ gdbus call --session \
--dest org.example.foo \
--object-path /org/example/foo \
--method SendFDs \
1 \
10 \
10&lt;file.foo
</programlisting>
<para>
Monitoring all objects on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
</programlisting>
<para>
Monitoring a single object on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
</programlisting>
<para>
Emitting a signal:
</para>
<programlisting>
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
</programlisting>
<para>
Emitting a signal to a specific process:
</para>
<programlisting>
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
</programlisting>
<para>
Waiting for a well-known name to be owned on the bus; this will
<emphasis>not</emphasis> auto-start the service:
</para>
<programlisting>
$ gdbus wait --session org.bar.SomeName
</programlisting>
<para>
Auto-starting then waiting for a well-known name to be owned on the bus:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.SomeName
</programlisting>
<para>
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where
<replaceable>SomeName</replaceable> is not directly activatable:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</programlisting>
<para>
Waiting for a well-known name and giving up after 30 seconds. By default,
the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
</para>
<programlisting>
$ gdbus wait --session --timeout 30 org.bar.SomeName
</programlisting>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

31
docs/reference/gio/gio-querymodules.rst Normal file
View File

@ -0,0 +1,31 @@
.. _gio-querymodules(1):
.. meta::
:copyright: Copyright 2010, 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: 2010, 2012 Red Hat, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
================
gio-querymodules
================
-------------------------
GIO module cache creation
-------------------------
SYNOPSIS
--------
| **gio-querymodules** *DIRECTORY*…
DESCRIPTION
-----------
``gio-querymodules`` creates a ``giomodule.cache`` file in the listed
directories. This file lists the implemented extension points for each module
that has been found. It is used by GIO at runtime to avoid opening all modules
just to find out which extension points they are implementing.
GIO modules are usually installed in the ``gio/modules`` subdirectory of libdir.

45
docs/reference/gio/gio-querymodules.xml
View File

@ -1,45 +0,0 @@
<refentry id="gio-querymodules" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio-querymodules</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio-querymodules</refname>
<refpurpose>GIO module cache creation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio-querymodules</command>
<arg choice="req" rep="repeat">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gio-querymodules</command> creates a
<filename>giomodule.cache</filename> file in the listed directories.
This file lists the implemented extension points for each module
that has been found. It is used by GIO at runtime to avoid opening
all modules just to find out which extension points they are implementing.
</para>
<para>
GIO modules are usually installed in the <filename>gio/modules</filename>
subdirectory of libdir.
</para>
</refsect1>
</refentry>

528
docs/reference/gio/gio.rst Normal file
View File

@ -0,0 +1,528 @@
.. _gio(1):
.. meta::
:copyright: Copyright 2015, 2019, 2020 Red Hat, Inc.
:copyright: Copyright 2018, 2019 Endless Mobile, Inc.
:copyright: Copyright 2018 segfault
:copyright: Copyright 2020 Frederic Martinsons
:copyright: Copyright 2022 Marco Trevisan
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2015, 2019, 2020 Red Hat, Inc.
SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2018 segfault
SPDX-FileCopyrightText: 2020 Frederic Martinsons
SPDX-FileCopyrightText: 2022 Marco Trevisan
SPDX-License-Identifier: LGPL-2.1-or-later
===
gio
===
--------------------
GIO commandline tool
--------------------
SYNOPSIS
--------
| **gio** help [*COMMAND*]
| **gio** version
| **gio** cat *LOCATION*…
| **gio** copy [*OPTION*…] *SOURCE*… *DESTINATION*
| **gio** info [*OPTION*…] *LOCATION*…
| **gio** launch *DESKTOP-FILE* [*FILE-ARG*…]
| **gio** list [*OPTION*…] [*LOCATION*…]
| **gio** mime *MIME-TYPE* [*HANDLER*]
| **gio** mkdir [*OPTION*…] *LOCATION*…
| **gio** monitor [*OPTION*…] [*LOCATION*…]
| **gio** mount [*OPTION*…] [*LOCATION*…]
| **gio** move [*OPTION*…] *SOURCE*… *DESTINATION*
| **gio** open *LOCATION*…
| **gio** rename *LOCATION* *NAME*
| **gio** remove [*OPTION*…] *LOCATION*…
| **gio** save [*OPTION*…] *DESTINATION*
| **gio** set [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
| **gio** trash [*OPTION*…] [*LOCATION*…]
| **gio** tree [*OPTION*…] [*LOCATION*…]
DESCRIPTION
-----------
``gio`` is a utility that makes many of the GIO features available from the
commandline. In doing so, it provides commands that are similar to traditional
utilities, but let you use GIO locations instead of local files: for example you
can use something like ``smb://server/resource/file.txt`` as a location.
Plain filenames which contain a colon will be interpreted as URIs with an
unknown protocol. To avoid this, prefix them with a path such as ``./``, or with
the ``file:`` protocol.
COMMANDS
--------
``help`` *COMMAND*
Displays a short synopsis of the available commands or provides detailed help
on a specific command.
``version``
Prints the GLib version to which ``gio`` belongs.
``cat`` *LOCATION*…
Concatenates the given files and prints them to the standard output.
The ``cat`` command works just like the traditional ``cat`` utility.
Mote: just pipe through ``cat`` if you need its formatting options like
``-n``, ``-T`` or other.
``copy`` [*OPTION*…] *SOURCE*… *DESTINATION*
Copies one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
source is specified, the destination must be a directory.
The ``copy`` command is similar to the traditional ``cp`` utility.
**Options**
``-T``, ``--no-target-directory``
Don’t copy into ``DESTINATION`` even if it is a directory.
``-p``, ``--progress``
Show progress.
``-i``, ``--interactive``
Prompt for confirmation before overwriting files.
``--preserve``
Preserve all attributes of copied files.
``-b``, ``--backup``
Create backups of existing destination files.
``-P``, ``--no-dereference``
Never follow symbolic links.
``--default-permissions``
Use the default permissions of the current process for the destination file,
rather than copying the permissions of the source file.
``info`` [*OPTION*…] *LOCATION*…
Shows information about the given locations.
The ``info`` command is similar to the traditional ``ls`` utility.
**Options**
``-w``, ``--query-writable``
List writable attributes.
``-f``, ``--filesystem``
Show information about the filesystem that the given locations reside on.
``-a``, ``--attributes=<ATTRIBUTES>``
The attributes to get.
Attributes can be specified with their GIO name, e.g. ``standard::icon``,
or just by namespace, e.g. ``unix``, or by ``*``, which matches all
attributes. Several attributes or groups of attributes can be specified,
separated by commas.
By default, all attributes are listed.
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``launch`` *DESKTOP-FILE* [*FILE-ARG*…]
Launch a desktop file from any location given.
The ``launch`` command extends the behavior of the ``open`` command by
allowing any desktop file to be launched, not only those registered as file
handlers.
``list`` [*OPTION*…] [*LOCATION*…]
Lists the contents of the given locations. If no location is given, the
contents of the current directory are shown.
The ``list`` command is similar to the traditional ``ls`` utility.
**Options**
``-a``, ``--attributes=<ATTRIBUTES>``
The attributes to get.
Attributes can be specified with their GIO name, e.g. ``standard::icon``, or
just by namespace, e.g. ``unix``, or by ``*``, which matches all attributes.
Several attributes or groups of attributes can be specified, separated by
commas.
By default, all attributes are listed.
``-h``, ``--hidden``
Show hidden files.
``-l``, ``--long``
Use a long listing format.
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``-d``, ``--print-display-names``
Print display names.
``-u``, ``--print-uris``
Print full URIs.
``mime`` *MIME-TYPE* [*HANDLER*]
If no handler is given, the ``mime`` command lists the registered and
recommended applications for the MIME type. If a handler is given, it is set
as the default handler for the MIME type.
Handlers must be specified by their desktop file name, including the
extension. Example: ``org.gnome.gedit.desktop``.
``mkdir`` [*OPTION*…] *LOCATION*…
Creates directories.
The ``mkdir`` command is similar to the traditional ``mkdir`` utility.
**Options**
``-p``, ``--parent``
Create parent directories when necessary.
``monitor`` [*OPTION*…] [*LOCATION*…]
Monitors files or directories for changes, such as creation deletion, content
and attribute changes, and mount and unmount operations affecting the
monitored locations.
The ``monitor`` command uses the GIO file monitoring APIs to do its job. GIO
has different implementations for different platforms. The most common
implementation on Linux uses inotify.
**Options**
``-d``, ``--dir=<LOCATION>``
Monitor the given location as a directory. Normally, the file type is used
to determine whether to monitor as a file or as a directory.
``-f``, ``--file=<LOCATION>``
Monitor the given location as a file. Normally, the file type is used to
determine whether to monitor as a file or as a directory.
``-D``, ``--direct=<LOCATION>``
Monitor the file directly. This allows changes made via hardlinks to be
captured.
``-s``, ``--silent=<LOCATION>``
Monitor the file directly, but don’t report changes.
``-n``, ``--no-moves``
Report moves and renames as simple deleted/created events.
``-m``, ``--mounts``
Watch for mount events.
``mount`` [*OPTION*…] [*LOCATION*…]
Provides commandline access to various aspects of GIO’s mounting
functionality.
Mounting refers to the traditional concept of arranging multiple file systems
and devices in a single tree, rooted at ``/``. Classical mounting happens in
the kernel and is controlled by the mount utility. GIO expands this concept by
introducing mount daemons that can make file systems available to GIO
applications without kernel involvement.
GIO mounts can require authentication, and the ``mount`` command may ask for
user IDs, passwords, and so on, when required.
**Options**
``-m``, ``--mountable``
Mount as mountable.
``-d``, ``--device=<ID>``
Mount volume with device file, or other identifier.
``-u``, ``--unmount``
Unmount the location.
``-e``, ``--eject``
Eject the location.
``-t``, ``--stop=<DEVICE>``
Stop drive with device file.
``-s``, ``--unmount-scheme=<SCHEME>``
Unmount all mounts with the given scheme.
``-f``, ``--force``
Ignore outstanding file operations when unmounting or ejecting.
``-a``, ``--anonymous``
Use an anonymous user when authenticating.
``-l``, ``--list``
List all GIO mounts.
``-o``, ``--monitor``
Monitor mount-related events.
``-i``, ``--detail``
Show extra information.
``--tcrypt-pim``
The numeric PIM when unlocking a VeraCrypt volume.
``--tcrypt-hidden``
Mount a TCRYPT hidden volume.
``--tcrypt-system``
Mount a TCRYPT system volume.
``move`` [*OPTION*…] *SOURCE*… *DESTINATION*
Moves one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
source is specified, the destination must be a directory.
The ``move`` command is similar to the traditional ``mv`` utility.
**Options**
``-T``, ``--no-target-directory``
Don’t copy into ``DESTINATION`` even if it is a directory.
``-p``, ``--progress``
Show progress.
``-i``, ``--interactive``
Prompt for confirmation before overwriting files.
``-b``, ``--backup``
Create backups of existing destination files.
``-C``, ``--no-copy-fallback``
Don’t use copy and delete fallback.
``open`` *LOCATION*…
Opens files with the default application that is registered to handle files of
this type.
GIO obtains this information from the shared-mime-info database, with per-user
overrides stored in ``$XDG_DATA_HOME/applications/mimeapps.list``.
The ``mime`` command can be used to change the default handler for a MIME
type.
Environment variables will not be set on the application, as it may be an
existing process which is activated to handle the new file.
``rename`` *LOCATION* *NAME*
Renames a file.
The ``rename`` command is similar to the traditional ``rename`` utility.
``remove`` [*OPTION*…] *LOCATION*…
Deletes each given file.
This command removes files irreversibly. If you want a reversible way to
remove files, see the ``trash`` command.
Note that not all URI schemes that are supported by GIO may allow deletion of
files.
The ``remove`` command is similar to the traditional ``rm`` utility.
**Options**
``-f``, ``--force``
Ignore non-existent and non-deletable files.
``save`` [*OPTION*…] *DESTINATION*
Reads from standard input and saves the data to the given location.
This is similar to just redirecting output to a file using traditional shell
syntax, but the ``save`` command allows saving to location that GIO can write
to.
**Options**
``-b``, ``--backup``
Back up existing destination files.
``-c``, ``--create``
Only create the destination if it doesn’t exist yet.
``-a``, ``--append``
Append to the end of the file.
``-p``, ``--private``
When creating, restrict access to the current user.
``-u``, ``--unlink``
When replacing, replace as if the destination did not exist.
``-v``, ``--print-etag``
Print the new ETag in the end.
``-e``, ``--etag=<ETAG>``
The ETag of the file that is overwritten.
``set`` [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
Sets a file attribute on a file.
File attributes can be specified with their GIO name, e.g ``standard::icon``.
Note that not all GIO file attributes are writable. Use the
``--query-writable`` option of the ``info`` command to list writable file
attributes.
If the ``TYPE`` is unset, ``VALUE`` does not have to be specified. If the
``TYPE`` is ``stringv``, multiple values can be given.
**Options**
``-t``, ``--type=<TYPE>``
Specifies the type of the attribute. Supported types are ``string``,
``stringv``, ``bytestring``, ``boolean``, ``uint32``, ``int32``, ``uint64``,
``int64`` and ``unset``.
If the type is not specified, ``string`` is assumed.
``-d``, ``--delete``
Unsets an attribute (same as setting its type to ``unset``).
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``trash`` [*OPTION*…] [*LOCATION*…]
Sends files or directories to the ‘Trashcan’ or restore them from ‘Trashcan’.
This can be a different folder depending on where the file is located, and not
all file systems support this concept. In the common case that the file lives
inside a user’s home directory, the trash folder is ``$XDG_DATA_HOME/Trash``.
Note that moving files to the trash does not free up space on the file system
until the ‘Trashcan’ is emptied. If you are interested in deleting a file
irreversibly, see the ``remove`` command.
Inspecting and emptying the ‘Trashcan’ is normally supported by graphical file
managers such as Nautilus, but you can also see the trash with the command:
``gio trash --list`` or ``gio list trash://``.
**Options**
``-f``, ``--force``
Ignore non-existent and non-deletable files.
``--empty``
Empty the trash.
``--list``
List files in the trash with their original locations.
``--restore``
Restore a file from trash to its original location. A URI beginning with
``trash://`` is expected here. If the original directory doesn’t exist, it
will be recreated.
``tree`` [*OPTION*…] [*LOCATION*…]
Lists the contents of the given locations recursively, in a tree-like format.
If no location is given, it defaults to the current directory.
The ``tree`` command is similar to the traditional ``tree`` utility.
**Options**
``-h``, ``--hidden``
Show hidden files.
``-l``, ``--follow-symlinks``
Follow symbolic links.
EXIT STATUS
-----------
On success, ``0`` is returned, a non-zero failure code otherwise.
SEE ALSO
--------
`cat(1) <man:cat(1)>`_, `cp(1) <man:cp(1)>`_, `ls(1) <man:ls(1)>`_,
`mkdir(1) <man:mkdir(1)>`_, `mv(1) <man:mv(1)>`_, `rm(1) <man:rm(1)>`_,
`tree(1) <man:tree(1)>`_

809
docs/reference/gio/gio.xml
View File

@ -1,809 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="gio">
<refentryinfo>
<title>gio</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
<email>mclasen@redhat.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio</refname>
<refpurpose>GIO commandline tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">cat</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">copy</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">info</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">list</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mime</arg>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mkdir</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">monitor</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mount</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">move</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">open</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">rename</arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">remove</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">save</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">set</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">trash</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">tree</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>gio</command> is a utility that makes many of the GIO
features available from the commandline. In doing so, it provides
commands that are similar to traditional utilities, but let you
use GIO locations instead of local files: for example you can use
something like <filename>smb://server/resource/file.txt</filename>
as a location.</para>
<para>Plain filenames which contain a colon will be interpreted as URIs
with an unknown protocol. To avoid this, prefix them with a path such as
<filename>./</filename>, or with the <literal>file:</literal> protocol.</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>Displays a short synopsis of the available commands or provides
detailed help on a specific command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>Prints the GLib version to which <command>gio</command>
belongs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>cat</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Concatenates the given files and prints them to the standard
output.</para>
<para>The <command>cat</command> command works just like the traditional <command>cat</command> utility.</para>
<para>Note: just pipe through <command>cat</command> if you need its formatting options
like <option>-n</option>, <option>-T</option> or other.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>copy</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Copies one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>copy</command> command is similar to the traditional <command>cp</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-T</option>, <option>--no-target-directory</option></term>
<listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--progress</option></term>
<listitem><para>Show progress.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--interactive</option></term>
<listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--preserve</option></term>
<listitem><para>Preserve all attributes of copied files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Create backups of existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option>, <option>--no-dereference</option></term>
<listitem><para>Never follow symbolic links.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--default-permissions</option></term>
<listitem><para>Use the default permissions of the current process for the destination file, rather than copying the permissions of the source file.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>info</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Shows information about the given locations.</para>
<para>The <command>info</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-w</option>, <option>--query-writable</option></term>
<listitem><para>List writable attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--filesystem</option></term>
<listitem><para>Show information about the filesystem that the given
locations reside on.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>launch</command>
<arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
</term>
<listitem>
<para>Launch a desktop file from any location given.</para>
<para>The <command>launch</command> command extends the behavior of the <command>open</command> command by allowing
any desktop file to be launched, not only those registered as file handlers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations. If no location is
given, the contents of the current directory are shown.</para>
<para>The <command>list</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--long</option></term>
<listitem><para>Use a long listing format.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--print-display-names</option></term>
<listitem><para>Print display names.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--print-uris</option></term>
<listitem><para>Print full URIs.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mime</command>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</term>
<listitem>
<para>If no handler is given, the <command>mime</command> command lists the
registered and recommended applications for the mimetype.
If a handler is given, it is set as the default handler for
the mimetype.</para>
<para>Handlers must be specified by their desktop file name,
including the extension. Example: <literal>org.gnome.gedit.desktop</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mkdir</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Creates directories.</para>
<para>The <command>mkdir</command> command is similar to the traditional <command>mkdir</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-p</option>, <option>--parent</option></term>
<listitem><para>Create parent directories when necessary.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>monitor</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Monitors files or directories for changes, such as creation
deletion, content and attribute changes, and mount and unmount
operations affecting the monitored locations.</para>
<para>The <command>monitor</command> command uses the GIO file monitoring APIs to do
its job. GIO has different implementations for different platforms.
The most common implementation on Linux uses inotify.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-d</option>, <option>--dir=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a directory. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--file=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a file. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option>, <option>--direct=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly. This allows changes made via hardlinks to be captured.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--silent=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly, but don’t report changes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--no-moves</option></term>
<listitem><para>Report moves and renames as simple deleted/created events.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option>, <option>--mounts</option></term>
<listitem><para>Watch for mount events.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mount</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Provides commandline access to various aspects of GIO’s mounting
functionality.</para>
<para>Mounting refers to the traditional concept of arranging multiple
file systems and devices in a single tree, rooted at <filename>/</filename>. Classical
mounting happens in the kernel and is controlled by the mount utility.
GIO expands this concept by introducing mount daemons that can make
file systems available to GIO applications without kernel
involvement.</para>
<para>GIO mounts can require authentication, and the <command>mount</command> command
may ask for user IDs, passwords, and so on, when required.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-m</option>, <option>--mountable</option></term>
<listitem><para>Mount as mountable.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--device=<replaceable>ID</replaceable></option></term>
<listitem><para>Mount volume with device file, or other identifier.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unmount</option></term>
<listitem><para>Unmount the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--eject</option></term>
<listitem><para>Eject the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>, <option>--stop=<replaceable>DEVICE</replaceable></option></term>
<listitem><para>Stop drive with device file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--unmount-scheme=<replaceable>SCHEME</replaceable></option></term>
<listitem><para>Unmount all mounts with the given scheme.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore outstanding file operations when unmounting or ejecting.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--anonymous</option></term>
<listitem><para>Use an anonymous user when authenticating.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--list</option></term>
<listitem><para>List all GIO mounts.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option>, <option>--monitor</option></term>
<listitem><para>Monitor mount-related events.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--detail</option></term>
<listitem><para>Show extra information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-pim</option></term>
<listitem><para>The numeric PIM when unlocking a VeraCrypt volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-hidden</option></term>
<listitem><para>Mount a TCRYPT hidden volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-system</option></term>
<listitem><para>Mount a TCRYPT system volume.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>move</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Moves one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>move</command> command is similar to the traditional <command>mv</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-T</option>, <option>--no-target-directory</option></term>
<listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--progress</option></term>
<listitem><para>Show progress.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--interactive</option></term>
<listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Create backups of existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-C</option>, <option>--no-copy-fallback</option></term>
<listitem><para>Don’t use copy and delete fallback.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>open</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Opens files with the default application that is registered
to handle files of this type.</para>
<para>GIO obtains this information from the shared-mime-info
database, with per-user overrides stored in
<filename><envar>$XDG_DATA_HOME</envar>/applications/mimeapps.list</filename>.</para>
<para>The <command>mime</command> command can be used to change the default handler for
a mimetype.</para>
<para>Environment variables will not be set on the application, as it
may be an existing process which is activated to handle the new file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>rename</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</term>
<listitem>
<para>Renames a file.</para>
<para>The <command>rename</command> command is similar to the traditional <command>rename</command> utility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>remove</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Deletes each given file.</para>
<para>This command removes files irreversibly. If you want a reversible
way to remove files, see the <command>trash</command> command.</para>
<para>Note that not all URI schemes that are supported by GIO may
allow deletion of files.</para>
<para>The <command>remove</command> command is similar to the traditional <command>rm</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>save</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Reads from standard input and saves the data to the given
location.</para>
<para>This is similar to just redirecting output to a file using
traditional shell syntax, but the <command>save</command> command allows saving to
location that GIO can write to.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Back up existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--create</option></term>
<listitem><para>Only create the destination if it doesn’t exist yet.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--append</option></term>
<listitem><para>Append to the end of the file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--private</option></term>
<listitem><para>When creating, restrict access to the current user.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unlink</option></term>
<listitem><para>When replacing, replace as if the destination did not exist.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--print-etag</option></term>
<listitem><para>Print the new ETag in the end.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--etag=<replaceable>ETAG</replaceable></option></term>
<listitem><para>The ETag of the file that is overwritten.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>set</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</term>
<listitem>
<para>Sets a file attribute on a file.</para>
<para>File attributes can be specified with their GIO name, e.g
<literal>standard::icon</literal>. Note that not all GIO file attributes are writable.
Use the <option>--query-writable</option> option of the <command>info</command> command to list
writable file attributes.</para>
<para>If the <replaceable>TYPE</replaceable> is unset,
<replaceable>VALUE</replaceable> does not have to be specified.
If the <replaceable>TYPE</replaceable> is <literal>stringv</literal>, multiple values can be given.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-t</option>, <option>--type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>Specifies the type of the attribute. Supported
types are <literal>string</literal>, <literal>stringv</literal>,
<literal>bytestring</literal>, <literal>boolean</literal>,
<literal>uint32</literal>, <literal>int32</literal>,
<literal>uint64</literal>, <literal>int64</literal> and <literal>unset</literal>.</para>
<para>If the type is not specified, <literal>string</literal> is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--delete</option></term>
<listitem><para>Unsets an attribute (same as setting it's type to <literal>unset</literal>).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>trash</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Sends files or directories to the ‘Trashcan’ or restore them from
‘Trashcan’. This can be a different folder depending on where the file
is located, and not all file systems support this concept. In the common
case that the file lives inside a user’s home directory, the trash folder is
<filename><envar>$XDG_DATA_HOME</envar>/Trash</filename>.</para>
<para>Note that moving files to the trash does not free up space on
the file system until the ‘Trashcan’ is emptied. If you are interested
in deleting a file irreversibly, see the <command>remove</command> command.</para>
<para>Inspecting and emptying the ‘Trashcan’ is normally supported by
graphical file managers such as Nautilus, but you can also see the
trash with the command: <command>gio trash --list</command> or
<command>gio list trash://</command>.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--empty</option></term>
<listitem><para>Empty the trash.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list</option></term>
<listitem><para>List files in the trash with their original locations</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--restore</option></term>
<listitem><para>Restore a file from trash to its original location. A URI beginning
with <literal>trash://</literal> is expected here. If the original
directory doesn't exist, it will be recreated.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>tree</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations recursively, in a
tree-like format. If no location is given, it defaults to the current
directory.</para>
<para>The <command>tree</command> command is similar to the traditional <command>tree</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--follow-symlinks</option></term>
<listitem><para>Follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>cat</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>cp</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>ls</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mkdir</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mv</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rm</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>tree</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>

181
docs/reference/gio/glib-compile-resources.rst Normal file
View File

@ -0,0 +1,181 @@
.. _glib-compile-resources(1):
.. meta::
:copyright: Copyright 2012, 2016 Red Hat, Inc.
:copyright: Copyright 2012 Christian Persch
:copyright: Copyright 2016 Sam Thursfield
:copyright: Copyright 2016 Patrick Griffis
:copyright: Copyright 2018 Ninja-Koala
:copyright: Copyright 2018, 2021 Emmanuele Bassi
:copyright: Copyright 2020 Endless OS Foundation, LLC
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2012, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2012 Christian Persch
SPDX-FileCopyrightText: 2016 Sam Thursfield
SPDX-FileCopyrightText: 2016 Patrick Griffis
SPDX-FileCopyrightText: 2018 Ninja-Koala
SPDX-FileCopyrightText: 2018, 2021 Emmanuele Bassi
SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
SPDX-License-Identifier: LGPL-2.1-or-later
======================
glib-compile-resources
======================
----------------------
GLib resource compiler
----------------------
SYNOPSIS
--------
| **glib-compile-resources** [*OPTION*…] *FILE*
DESCRIPTION
-----------
``glib-compile-resources`` reads the resource description from ``FILE`` and the
files that it references and creates a binary resource bundle that is suitable
for use with the ``GResource`` API. The resulting bundle is then written out
as-is, or as C source for linking into an application.
The XML resource files normally have the filename extension ``.gresource.xml``.
For a detailed description of the XML file format, see the
``GResource`` `documentation <https://docs.gtk.org/gio/struct.Resource.html>`_.
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``--version``
Print program version and exit.
``--target <TARGET>``
Store the compiled resources in the file ``TARGET``. If not specified a
filename based on the ``FILE`` basename is used.
``--sourcedir <DIRECTORY>``
The files referenced in ``FILE`` are loaded from this directory. If not
specified, the current directory is used.
``--generate``
Write the output file in the format selected for by its filename extension:
``.c``
C source
``.h``
C header
``.gresource``
resource bundle
``--generate-source``
Instead of a writing the resource bundle in binary form, create a C source
file that contains the resource bundle. This can then be compiled into an
application for easy access.
``--generate-header``
Generate a header file for use with C code generated by ``--generate-source``.
``--generate-dependencies``
Prints the list of files that the resource bundle references to standard
output. This can be used to track dependencies in the build system. For
example, the following make rule would mark ``test.gresource`` as depending on
all the files that ``test.gresource.xml`` includes, so that it is
automatically rebuilt if any of them change::
test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
Note that this may or may not be portable to non-GNU ``make``.
Also see ``--dependency-file``.
``--c-name``
Specify the prefix used for the C identifiers in the code generated by
``--generate-source`` and ``--generate-header``.
``--manual-register``
By default, code generated by ``--generate-source`` uses automatic
initialization of the resource. This works on most systems by using the
compiler support for constructors. However, some (uncommon) compilers may not
support this, you can then specify ``--manual-register``,
which will generate custom register and unregister functions that your code
can manually call at initialization and uninitialization time.
``--internal``
By default, code generated by ``--generate-source`` declares all
initialization functions as ``extern``. So they are exported unless this is
prevented by a link script or other means. Since libraries usually want to
use the functions only internally it can be more useful to declare them as
``G_GNUC_INTERNAL`` which is what ``--internal`` does.
``--external-data``
By default, code generated by ``--generate-source`` embeds the resource data
as a string literal. When ``--external-data`` is given, the data is only
declared in the generated C file, and the data has to be linked externally.
``--dependency-file <FILE>``
Write dependencies in the same style as ``gcc -M -MF`` to the given file. If
``FILE`` is ``-``, the dependencies are written to the standard output. Unlike
``--generate-dependencies``, this option can be combined with other
``--generate`` options to generate dependencies as a side-effect of generating
sources.
``--generate-phony-targets``
When creating a dependency file with ``--dependency-file`` include phony
targets in the same style as ``gcc -MP``. This would typically be used with
``make``.
``--compiler <NAME>``
Generate code that is going to target the given compiler ``NAME``. The current
two compiler modes are ``gcc``, for all GCC-compatible toolchains; and
``msvc``, for the Microsoft Visual C Compiler. If this option isn’t set, then
the default will be taken from the ``CC`` environment variable.
ENVIRONMENT
-----------
``XMLLINT``
The full path to the ``xmllint`` executable. This is used to preprocess
resources with the ``xml-stripblanks`` preprocessing option. If this
environment variable is not set, ``xmllint`` is searched for in the ``PATH``.
``GDK_PIXBUF_PIXDATA``
Deprecated since gdk-pixbuf 2.32, as ``GResource`` supports embedding
modern image formats without conversion.
The full path to the ``gdk-pixbuf-pixdata`` executable. This is used to
preprocess resources with the ``to-pixdata`` preprocessing option. If this
environment variable is not set, ``gdk-pixbuf-pixdata`` is searched for in the
``PATH``.
``JSON_GLIB_FORMAT``
The full path to the ``json-glib-format`` executable. This is used to
preprocess resources with the ``json-stripblanks`` preprocessing option. If
this environment variable is not set, ``json-glib-format`` is searched for in
the ``PATH``.

254
docs/reference/gio/glib-compile-resources.xml
View File

@ -1,254 +0,0 @@
<refentry id="glib-compile-resources" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-resources</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-resources</refname>
<refpurpose>GLib resource compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-resources</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-resources</command> reads the resource description from
<replaceable>FILE</replaceable> and the files that it references
and creates a binary resource bundle that is suitable for use with the
<link linkend="GResource"><type>GResource</type></link> API.
The resulting bundle is then written out as-is, or as C source for linking into
an application.
</para>
<para>
The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GResource"><type>GResource</type></link> documentation.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--target=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store the compiled resources in the file <replaceable>TARGET</replaceable>.
If not specified a filename based on the <replaceable>FILE</replaceable>
basename is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
<listitem><para>
The files referenced in <replaceable>FILE</replaceable> are loaded from
this directory. If not specified, the current directory is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate</option></term>
<listitem><para>
Write the output file in the format selected for by its filename extension:
<variablelist>
<varlistentry>
<term><literal>.c</literal></term>
<listitem><para>C source</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.h</literal></term>
<listitem><para>C header</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.gresource</literal></term>
<listitem><para>resource bundle</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-source</option></term>
<listitem><para>
Instead of a writing the resource bundle in binary form create a C source file
that contains the resource bundle. This can then be compiled into an
application for easy access.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-header</option></term>
<listitem><para>
Generate a header file for use with C code generated by
<option>--generate-source</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-dependencies</option></term>
<listitem><para>
Prints the list of files that the resource bundle references to standard output.
This can be used to track dependencies in the build system. For example, the
following make rule would mark <replaceable>test.gresource</replaceable> as
depending on all the files that <replaceable>test.gresource.xml</replaceable>
includes, so that is is automatically rebuilt if any of them change:
<programlisting>
test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
</programlisting>
Note that this may or may not be portable to non-GNU <command>make</command>.
</para>
<para>
Also see <option>--dependency-file</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--c-name</option></term>
<listitem><para>
Specify the prefix used for the C identifiers in the code generated by
<option>--generate-source</option> and <option>--generate-header</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--manual-register</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> uses automatic
initialization of the resource. This works on most systems by using the
compiler support for constructors. However, some (uncommon) compilers may not
support this, you can then specify <option>--manual-register</option>,
which will generate custom register and unregister functions that your code
can manually call at initialization and uninitialization time.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--internal</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> declares all
initialization functions as <type>extern</type>. So they are exported
unless this is prevented by a link script or other means. Since libraries
usually want to use the functions only internally it can be more useful to
declare them as
<link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
which is what <option>--internal</option> does.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--external-data</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> embeds the
resource data as a string literal. When <option>--external-data</option>
is given, the data is only declared in the generated C file, and the data
has to be linked externally.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
<listitem><para>
Write dependencies in the same style as gcc -M -MF to the given file.
If <option>FILE</option> is -, the dependencies are written to the standard
output. Unlike <option>--generate-dependencies</option>, this option can be
combined with other <option>--generate</option> options to generate dependencies
as a side-effect of generating sources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-phony-targets</option></term>
<listitem><para>
When creating a dependency file with <option>--dependency-file</option>
include phony targets in the same style as gcc -MP. This would typically
be used with <literal>make</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--compiler=<replaceable>NAME</replaceable></option></term>
<listitem><para>
Generate code that is going to target the given compiler <replaceable>NAME</replaceable>.
The current two compiler modes are "gcc", for all GCC-compatible toolchains; and "msvc",
for the Microsoft Visual C Compiler. If this option isn't set, then the default will be
taken from the <envar>CC</envar> environment variable.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>XMLLINT</envar></term>
<listitem><para>
The full path to the <command>xmllint</command> executable. This is used to
preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>xmllint</command> is
searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>GDK_PIXBUF_PIXDATA</envar></term>
<listitem><para>
Deprecated since gdk-pixbuf 2.32, as <type>GResource</type> supports embedding
modern image formats without conversion.
</para><para>
The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>JSON_GLIB_FORMAT</envar></term>
<listitem><para>
The full path to the <command>json-glib-format</command> executable. This is used
to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>json-glib-format</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

83
docs/reference/gio/glib-compile-schemas.rst Normal file
View File

@ -0,0 +1,83 @@
.. _glib-compile-schemas(1):
.. meta::
:copyright: Copyright 2010, 2011, 2012, 2015 Red Hat, Inc.
:copyright: Copyright 2012 Allison Karlitskaya
:copyright: Copyright 2016 Sam Thursfield
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2012, 2015 Red Hat, Inc.
SPDX-FileCopyrightText: 2012 Allison Karlitskaya
SPDX-FileCopyrightText: 2016 Sam Thursfield
SPDX-License-Identifier: LGPL-2.1-or-later
====================
glib-compile-schemas
====================
-------------------------
GSettings schema compiler
-------------------------
SYNOPSIS
--------
| **glib-compile-schemas** [*OPTION*…] *DIRECTORY*
DESCRIPTION
-----------
``glib-compile-schemas`` compiles all the GSettings XML schema files in
``DIRECTORY`` into a binary file with the name ``gschemas.compiled`` that can be
used by ``GSettings``. The XML schema files must have the filename extension
``.gschema.xml``. For a detailed description of the XML file format, see the
``GSettings`` documentation.
At runtime, GSettings looks for schemas in the ``glib-2.0/schemas``
subdirectories of all directories specified in the ``XDG_DATA_DIRS`` environment
variable. The usual location to install schema files is
``/usr/share/glib-2.0/schemas``.
In addition to schema files, ``glib-compile-schemas`` reads ‘vendor override’
files, which are key files that can override default values for keys in
the schemas. The group names in the key files are the schema ID, and the
values are written in serialized GVariant form.
Vendor override files must have the filename extension
``.gschema.override``.
By convention, vendor override files begin with ``nn_`` where ``nn`` is a number
from 00 to 99. Higher numbered files have higher priority (e.g. if the same
override is made in a file numbered 10 and then again in a file numbered 20, the
override from 20 will take precedence).
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``--version``
Print program version and exit.
``--targetdir <TARGET>``
Store ``gschemas.compiled`` in the ``TARGET`` directory instead of
``DIRECTORY``.
``--strict``
Abort on any errors in schemas. Without this option, faulty schema files are
simply omitted from the resulting compiled schema.
``--dry-run``
Don’t write ``gschemas.compiled``. This option can be used to check
``.gschema.xml`` sources for errors.
``--allow-any-name``
Do not enforce restrictions on key names. Note that this option is purely
to facility the transition from GConf, and will be removed at some time
in the future.

118
docs/reference/gio/glib-compile-schemas.xml
View File

@ -1,118 +0,0 @@
<refentry id="glib-compile-schemas" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-schemas</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-schemas</refname>
<refpurpose>GSettings schema compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-schemas</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-schemas</command> compiles all the GSettings XML
schema files in <replaceable>DIRECTORY</replaceable> into a binary file
with the name <filename>gschemas.compiled</filename> that can be used
by <link linkend="GSettings"><type>GSettings</type></link>. The XML schema
files must have the filename extension <filename>.gschema.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GSettings"><type>GSettings</type></link> documentation.
</para>
<para>
At runtime, GSettings looks for schemas in the
<filename>glib-2.0/schemas</filename> subdirectories of all directories
specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
usual location to install schema files is
<filename>/usr/share/glib-2.0/schemas</filename>.
</para>
<para>
In addition to schema files, glib-compile-schemas reads 'vendor override'
files, which are key files that can override default values for keys in
the schemas. The group names in the key files are the schema id, and the
values are written in serialized GVariant form.
Vendor override files must have the filename extension
<filename>.gschema.override</filename>.
</para>
<para>
By convention, vendor override files begin with <filename>nn_</filename>
where <filename>nn</filename> is a number from 00 to 99. Higher
numbered files have higher priority (eg: if the same override is made in
a file numbered 10 and then again in a file numbered 20, the override
from 20 will take precedence).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--targetdir=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store <filename>gschemas.compiled</filename> in the <replaceable>TARGET</replaceable> directory instead of <replaceable>DIRECTORY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--strict</option></term>
<listitem><para>
Abort on any errors in schemas. Without this option, faulty schema files are
simply omitted from the resulting compiled schema.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem><para>
Don't write <filename>gschemas.compiled</filename>. This option can be used
to check <filename>.gschema.xml</filename> sources for errors.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--allow-any-name</option></term>
<listitem><para>
Do not enforce restrictions on key names. Note that this option is purely
to facility the transition from GConf, and will be removed at some time
in the future.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

66
docs/reference/gio/gresource.rst Normal file
View File

@ -0,0 +1,66 @@
.. _gresource(1):
.. meta::
: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: 2012 Red Hat, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
=========
gresource
=========
--------------
GResource tool
--------------
SYNOPSIS
--------
| **gresource** [--section *SECTION*] list *FILE* [*PATH*]
| **gresource** [--section *SECTION*] details *FILE* [*PATH*]
| **gresource** [--section *SECTION*] extract *FILE* *PATH*
| **gresource** sections *FILE*
| **gresource** help [*COMMAND*]
DESCRIPTION
-----------
``gresource`` offers a simple commandline interface to ``GResource``. It lets
you list and extract resources that have been compiled into a resource file or
included in an ELF file (a binary or a shared library).
The file to operate on is specified by the ``FILE`` argument.
If an ELF file includes multiple sections with resources, it is possible to
select which one to operate on with the ``--section`` option. Use the
``sections`` command to find available sections.
COMMANDS
--------
``list``
Lists resources. If ``SECTION`` is given, only list resources in this section.
If ``PATH`` is given, only list matching resources.
``details``
Lists resources with details. If ``SECTION`` is given, only list resources in
this section. If ``PATH`` is given, only list matching resources. Details
include the section, size and compression of each resource.
``extract``
Extracts the resource named by ``PATH`` to stdout. Note that resources may
contain binary data.
``sections``
Lists sections containing resources. This is only interesting if ``FILE`` is
an ELF file.
``help``
Prints help and exits.

127
docs/reference/gio/gresource.xml
View File

@ -1,127 +0,0 @@
<refentry id="gresource-tool" lang="en">
<refentryinfo>
<title>gresource</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gresource</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gresource</refname>
<refpurpose>GResource tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">list</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">details</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">extract</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="plain"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">sections</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gresource</command> offers a simple commandline
interface to <link linkend="GResource"><type>GResource</type></link>.
It lets you list and extract resources that have been compiled
into a resource file or included in an elf file (a binary or a
shared library).
</para>
<para>
The file to operate on is specified by the <replaceable>FILE</replaceable>
argument.
</para>
<para>
If an elf file includes multiple sections with resources, it is
possible to select which one to operate on with the
<arg choice="plain">--section</arg> option. Use the
<arg choice="plain">sections</arg> command to find available sections.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>list</option></term>
<listitem><para>
Lists resources. If <replaceable>SECTION</replaceable> is given, only
list resources in this section. If <replaceable>PATH</replaceable> is
given, only list matching resources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>details</option></term>
<listitem><para>
Lists resources with details. If <replaceable>SECTION</replaceable>
is given, only list resources in this section. If
<replaceable>PATH</replaceable> is given, only list matching resources.
Details include the section, size and compression of each resource.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>extract</option></term>
<listitem><para>
Extracts the resource named by <replaceable>PATH</replaceable> to stdout.
Note that resources may contain binary data.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>sections</option></term>
<listitem><para>
Lists sections containing resources. This is only interesting if
<replaceable>FILE</replaceable> is an elf file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

125
docs/reference/gio/gsettings.rst Normal file
View File

@ -0,0 +1,125 @@
.. _gsettings(1):
.. meta::
:copyright: Copyright 2010, 2011, 2013 Red Hat, Inc.
:copyright: Copyright 2011 Colin Walters
:copyright: Copyright 2016 Jeremy Whiting
:copyright: Copyright 2018 Arnaud Bonatti
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2013 Red Hat, Inc.
SPDX-FileCopyrightText: 2011 Colin Walters
SPDX-FileCopyrightText: 2016 Jeremy Whiting
SPDX-FileCopyrightText: 2018 Arnaud Bonatti
SPDX-License-Identifier: LGPL-2.1-or-later
=========
gsettings
=========
----------------------------
GSettings configuration tool
----------------------------
SYNOPSIS
--------
| **gsettings** get *SCHEMA*[:*PATH*] *KEY*
| **gsettings** monitor *SCHEMA*[:*PATH*] *KEY*
| **gsettings** writable *SCHEMA*[:*PATH*] *KEY*
| **gsettings** range *SCHEMA*[:*PATH*] *KEY*
| **gsettings** describe *SCHEMA*[:*PATH*] *KEY*
| **gsettings** set *SCHEMA*[:*PATH*] *KEY* *VALUE*
| **gsettings** reset *SCHEMA*[:*PATH*] *KEY*
| **gsettings** reset-recursively *SCHEMA*[:*PATH*]
| **gsettings** list-schemas [--print-paths]
| **gsettings** list-relocatable-schemas
| **gsettings** list-keys *SCHEMA*[:*PATH*]
| **gsettings** list-children *SCHEMA*[:*PATH*]
| **gsettings** list-recursively [*SCHEMA*[:*PATH*]]
| **gsettings** help [*COMMAND*]
DESCRIPTION
-----------
``gsettings`` offers a simple commandline interface to ``GSettings``. It lets
you get, set or monitor an individual key for changes.
The ``SCHEMA`` and ``KEY`` arguments are required for most commands to specify
the schema ID and the name of the key to operate on. The schema ID may
optionally have a ``:PATH`` suffix. Specifying the path is only needed if the
schema does not have a fixed path.
When setting a key, you also need specify a ``VALUE``. The format for the value
is that of a serialized ``GVariant``, so e.g. a string must include explicit
quotes: ``'foo'``. This format is also used when printing out values.
Note that ``gsettings`` needs a D-Bus session bus connection to write changes to
the dconf database.
COMMANDS
--------
``get``
Gets the value of ``KEY``. The value is printed out as a serialized
``GVariant``.
``monitor``
Monitors ``KEY`` for changes and prints the changed values. If no ``KEY`` is
specified, all keys in the schema are monitored. Monitoring will continue
until the process is terminated.
``writable``
Finds out whether ``KEY`` is writable.
``range``
Queries the range of valid values for ``KEY``.
``describe``
Queries the description of valid values for ``KEY``.
``set``
Sets the value of ``KEY`` to ``VALUE``. The value is specified as a serialized
``GVariant``.
``reset``
Resets ``KEY`` to its default value.
``reset-recursively``
Reset all keys under the given ``SCHEMA``.
``list-schemas``
Lists the installed, non-relocatable schemas. See ``list-relocatable-schemas``
if you are interested in relocatable schemas. If ``--print-paths`` is given,
the path where each schema is mapped is also printed.
``list-relocatable-schemas``
Lists the installed, relocatable schemas. See ``list-schemas`` if you are
interested in non-relocatable schemas.
``list-keys``
Lists the keys in ``SCHEMA``.
``list-children``
Lists the children of ``SCHEMA``.
``list-recursively``
Lists keys and values, recursively. If no ``SCHEMA`` is given, list keys in
all schemas.
``help``
Prints help and exits.

248
docs/reference/gio/gsettings.xml
View File

@ -1,248 +0,0 @@
<refentry id="gsettings-tool" lang="en">
<refentryinfo>
<title>gsettings</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gsettings</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gsettings</refname>
<refpurpose>GSettings configuration tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">get</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">monitor</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="opt"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">writable</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">range</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">describe</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">set</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
<arg choice="plain"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset-recursively</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-schemas</arg>
<arg choice="opt">--print-paths</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-relocatable-schemas</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-keys</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-children</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-recursively</arg>
<arg choice="opt"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gsettings</command> offers a simple commandline
interface to <link linkend="GSettings"><type>GSettings</type></link>.
It lets you get, set or monitor an individual key for changes.
</para>
<para>
The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
arguments are required for most commands to specify the schema id and the
name of the key to operate on. The schema id may optionally have a
:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
if the schema does not have a fixed path.
</para>
<para>
When setting a key, you also need specify a <replaceable>VALUE</replaceable>
The format for the value is that of a serialized
<link linkend="GVariant"><type>GVariant</type></link>,
so e.g. a string
must include explicit quotes: "'foo'". This format is also used when printing
out values.
</para>
<para>
Note that gsettings needs a D-Bus session bus connection to write changes to
the dconf database.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>get</option></term>
<listitem><para>
Gets the value of <replaceable>KEY</replaceable>.
The value is printed out as a serialized
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors <replaceable>KEY</replaceable> for changes and prints the changed
values. If no <replaceable>KEY</replaceable> is specified, all keys in the
schema are monitored. Monitoring will continue until the process is terminated.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>writable</option></term>
<listitem><para>
Finds out whether <replaceable>KEY</replaceable> is writable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>range</option></term>
<listitem><para>
Queries the range of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>describe</option></term>
<listitem><para>
Queries the description of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>set</option></term>
<listitem><para>
Sets the value of <replaceable>KEY</replaceable> to
<replaceable>VALUE</replaceable>. The value is specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset</option></term>
<listitem><para>
Resets <replaceable>KEY</replaceable> to its default value.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset-recursively</option></term>
<listitem><para>
Reset all keys under the given <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-schemas</option></term>
<listitem><para>
Lists the installed, non-relocatable schemas.
See <option>list-relocatable-schemas</option> if you are interested in
relocatable schemas. If <optional><option>--print-paths</option></optional>
is given, the path where each schema is mapped is also printed.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-relocatable-schemas</option></term>
<listitem><para>
Lists the installed, relocatable schemas.
See <option>list-schemas</option> if you are interested in
non-relocatable schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-keys</option></term>
<listitem><para>
Lists the keys in <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-children</option></term>
<listitem><para>
Lists the children of <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-recursively</option></term>
<listitem><para>
Lists keys and values, recursively. If no <replaceable>SCHEMA</replaceable>
is given, list keys in all schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

11
docs/reference/gio/meson.build
View File

@ -1,12 +1,17 @@
if get_option('man')
if get_option('man-pages').enabled()
manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
'gio', 'gdbus-codegen']
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',

11
docs/reference/glib/building.md
View File

@ -146,12 +146,11 @@ configuring the GLib library:
: By default, GLib will not build documentation for the library and tools. This
option can be used to enable building the documentation.
`-Dman=false` and `-Dman=true`
: By default, GLib will detect whether `xsltproc` and the necessary DocBook
stylesheets are installed. If they are, then it will use them to rebuild
the included man pages from the XML sources. These options can be used to
explicitly control whether man pages should be rebuilt used or not. The
distribution includes pre-generated man pages.
`-Dman-pages=disabled` and `-Dman-pages=enabled`
: By default, GLib will detect whether `rst2man` and the necessary DocBook
stylesheets are installed. If they are, then it will use them to build
the included man pages from the reStructuredText sources. These options can be
used to explicitly control whether man pages should be built and used.
`-Dxattr=false` and `-Dxattr=true`
: By default, GLib will detect whether the `getxattr()` family of functions is

59
docs/reference/glib/glib-gettextize.rst Normal file
View File

@ -0,0 +1,59 @@
.. _glib-gettextize(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
===============
glib-gettextize
===============
------------------------------------
gettext internationalization utility
------------------------------------
SYNOPSIS
--------
| **glib-gettextize** [*OPTION*…] [*DIRECTORY*]
DESCRIPTION
-----------
``glib-gettextize`` helps to prepare a source package for being
internationalized through `gettext <https://www.gnu.org/software/gettext/>`_.
It is a variant of the ``gettextize`` that ships with gettext.
``glib-gettextize`` differs from ``gettextize`` in that it doesn’t create an
``intl/`` subdirectory and doesn’t modify ``po/ChangeLog`` (note that newer
versions of ``gettextize`` behave like this when called with the
``--no-changelog`` option).
OPTIONS
-------
``--help``
Print help and exit.
``--version``
Print version information and exit.
``-c``, ``--copy``
Copy files instead of making symlinks.
``-f``, ``--force``
Force writing of new files even if old ones exist.
SEE ALSO
--------
`gettextize(1) <man:gettextize(1)>`_

88
docs/reference/glib/glib-gettextize.xml
View File

@ -1,88 +0,0 @@
<refentry id="glib-gettextize" lang="en">
<refentryinfo>
<title>glib-gettextize</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Owen</firstname>
<surname>Taylor</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-gettextize</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-gettextize</refname>
<refpurpose>gettext internationalization utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-gettextize</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-gettextize</command> helps to prepare a source package for being
internationalized through <application>gettext</application>.
It is a variant of the <command>gettextize</command> that ships with
<application>gettext</application>.
</para>
<para><command>glib-gettextize</command> differs
from <command>gettextize</command> in that it doesn't create an
<filename>intl/</filename> subdirectory and doesn't modify
<filename>po/ChangeLog</filename> (note that newer versions of
<command>gettextize</command> behave like this when called with the
<option>--no-changelog</option> option).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--copy</option></term>
<listitem><para>
copy files instead of making symlinks
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>
force writing of new files even if old ones exist
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry><refentrytitle>gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

54
docs/reference/glib/gtester-report.rst Normal file
View File

@ -0,0 +1,54 @@
.. _gtester-report(1):
.. meta::
:copyright: Copyright 2008 Matthias Clasen
:copyright: Copyright 2012, 2013 Red Hat, Inc.
:copyright: Copyright 2019 Endless Mobile, Inc.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2008 Matthias Clasen
SPDX-FileCopyrightText: 2012, 2013 Red Hat, Inc.
SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
==============
gtester-report
==============
------------------------------
test report formatting utility
------------------------------
SYNOPSIS
--------
| **gtester-report** [*OPTION*…] *gtester-log*
DESCRIPTION
-----------
``gtester-report`` is a script which converts the XML output generated by
``gtester`` into HTML.
Since GLib 2.62, ``gtester-report`` is deprecated. Use TAP for reporting test
results instead, and feed it to the test harness provided by your build system.
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``-v``, ``--version``
Print version information and exit.
``-s``, ``--subunit``
Output subunit. Needs ``python-subunit``.
SEE ALSO
--------
`gtester(1) <man:gtester(1)>`_

78
docs/reference/glib/gtester-report.xml
View File

@ -1,78 +0,0 @@
<refentry id="gtester-report">
<refentryinfo>
<title>gtester-report</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester-report</refname>
<refpurpose>test report formatting utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester-report</command>
<arg choice="opt" rep="repeat">option</arg>
<arg>gtester-log</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester-report</command> is a script which converts
the XML output generated by gtester into HTML.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--subunit</option></term>
<listitem><para>
Output subunit. Needs python-subunit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

120
docs/reference/glib/gtester.rst Normal file
View File

@ -0,0 +1,120 @@
.. _gtester(1):
.. meta::
:copyright: Copyright 2008 Matthias Clasen
:copyright: Copyright 2011 Collabora, Ltd.
:copyright: Copyright 2011 Carlos Garcia Campos
:copyright: Copyright 2012 Red Hat, Inc.
:copyright: Copyright 2019 Endless Mobile, Inc.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2008 Matthias Clasen
SPDX-FileCopyrightText: 2011 Collabora, Ltd.
SPDX-FileCopyrightText: 2011 Carlos Garcia Campos
SPDX-FileCopyrightText: 2012 Red Hat, Inc.
SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
=======
gtester
=======
--------------------
test running utility
--------------------
SYNOPSIS
--------
| **gtester** [*OPTION*…] *test-program*
DESCRIPTION
-----------
``gtester`` is a utility to run unit tests that have been written using the GLib
test framework.
Since GLib 2.62, ``gtester-report`` is deprecated. Use TAP for reporting test
results instead, and feed it to the test harness provided by your build system.
When called with the ``-o`` option, ``gtester`` writes an XML report of the test
results, which can be converted into HTML using the ``gtester-report`` utility.
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``-v``, ``--verbose``
Print version information and exit.
``--g-fatal-warnings``
Make warnings fatal.
``-k``, ``--keep-going``
Continue running after tests failed.
``-l``
List paths of available test cases.
``-m=<MODE>``
Run test cases in ``MODE``, which can be one of:
* ``perf``
Run performance tests.
* ``slow``, ``thorough``
Run slow tests, or repeat non-deterministic tests more often.
* ``quick``
Do not run slow or performance tests, or do extra repeats of
non-deterministic tests (default).
* ``undefined``
Run test cases that deliberately provoke checks or assertion failures, if
implemented (default).
* ``no-undefined``
Do not run test cases that deliberately provoke checks or assertion
failures.
``-p=<TEST-PATH>``
Only run test cases matching ``TEST-PATH``.
``-s=<TEST-PATH>``
Skip test cases matching ``TEST-PATH``.
``--seed=<SEED-STRING>``
Run all test cases with random number seed ``SEED-STRING``.
``-o=<LOG-FILE>``
Write the test log to ``LOG-FILE``.
``-q``, ``--quiet``
Suppress per-test-binary output.
``--verbose``
Report success per testcase.
SEE ALSO
--------
`gtester-report(1) <man:gtester-report(1)>`_

192
docs/reference/glib/gtester.xml
View File

@ -1,192 +0,0 @@
<refentry id="gtester">
<refentryinfo>
<title>gtester</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
<author>
<contrib>Developer</contrib>
<firstname>Sven</firstname>
<surname>Herzberg</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester</refname>
<refpurpose>test running utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg>testprogram</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester</command> is a utility to run unit tests that have
been written using the GLib test framework.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
<para>
When called with the <option>-o</option> option, <command>gtester</command>
writes an XML report of the test results, which can be converted
into HTML using the <command>gtester-report</command> utility.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--g-fatal-warnings</option></term>
<listitem><para>
make warnings fatal
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-k</option>, <option>--keep-going</option></term>
<listitem><para>
continue running after tests failed
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<listitem><para>
list paths of available test cases
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m=<replaceable>MODE</replaceable></option></term>
<listitem><para>
run test cases in <replaceable>MODE</replaceable>, which can be one of:
<variablelist>
<varlistentry>
<term><option>perf</option></term>
<listitem><para>
run performance tests
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>slow</option>, <option>thorough</option></term>
<listitem><para>
run slow tests, or repeat non-deterministic tests more often
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>quick</option></term>
<listitem><para>
do not run slow or performance tests, or do extra repeats
of non-deterministic tests (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>undefined</option></term>
<listitem><para>
run test cases that deliberately provoke checks or assertion
failures, if implemented (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>no-undefined</option></term>
<listitem><para>
do not run test cases that deliberately provoke checks or
assertion failures
</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
only run test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
skip test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--seed=<replaceable>SEEDSTRING</replaceable></option></term>
<listitem><para>
run all test cases with random number seed <replaceable>SEEDSTRING</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o=<replaceable>LOGFILE</replaceable></option></term>
<listitem><para>
write the test log to <replaceable>LOGFILE</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option>, <option>--quiet</option></term>
<listitem><para>
suppress per test binary output
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem><para>
report success per testcase
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

11
docs/reference/glib/meson.build
View File

@ -1,11 +1,16 @@
if get_option('man')
if get_option('man-pages').enabled()
manpages = ['glib-gettextize', 'gtester', 'gtester-report']
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',

390
docs/reference/gobject/glib-genmarshal.rst Normal file
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)>`_

579
docs/reference/gobject/glib-genmarshal.xml
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>

491
docs/reference/gobject/glib-mkenums.rst Normal file
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)>`_

659
docs/reference/gobject/glib-mkenums.xml
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>

74
docs/reference/gobject/gobject-query.rst Normal file
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.

123
docs/reference/gobject/gobject-query.xml
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>

11
docs/reference/gobject/meson.build
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',

19
meson.build
View File

@ -2558,19 +2558,10 @@ endif
configure_file(output : 'config.h', configuration : glib_conf)
if get_option('man')
xsltproc = find_program('xsltproc', required : true)
xsltproc_command = [
xsltproc,
'--nonet',
'--stringparam', 'man.output.quietly', '1',
'--stringparam', 'funcsynopsis.style', 'ansi',
'--stringparam', 'man.th.extra1.suppress', '1',
'--stringparam', 'man.authors.section.enabled', '0',
'--stringparam', 'man.copyright.section.enabled', '0',
'-o', '@OUTPUT@',
'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
'@INPUT@',
rst2man = find_program('rst2man', 'rst2man.py', required: get_option('man-pages'))
if rst2man.found()
rst2man_flags = [
'--syntax-highlight=none',
]
man1_dir = join_paths(glib_prefix, get_option('mandir'), 'man1')
endif
@ -2634,7 +2625,7 @@ endif
summary({
'xattr' : xattr_dep.length() > 0,
'man' : get_option('man'),
'man-pages' : get_option('man-pages'),
'dtrace' : get_option('dtrace'),
'systemtap' : enable_systemtap,
'sysprof' : libsysprof_capture_dep.found(),

9
meson_options.txt
View File

@ -40,7 +40,14 @@ option('libmount',
option('man',
type : 'boolean',
value : false,
description : 'generate man pages (requires xsltproc)')
description : 'generate man pages (requires xsltproc)',
deprecated : 'man-pages')
option('man-pages',
type : 'feature',
value : 'auto',
description : 'generate man pages (requires rst2man)',
deprecated : { 'true': 'enabled', 'false': 'disabled' })
option('dtrace',
type : 'boolean',