diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 01c309e8a..647e374d1 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -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 diff --git a/.gitlab-ci/fedora.Dockerfile b/.gitlab-ci/fedora.Dockerfile index e73964064..3713cc357 100644 --- a/.gitlab-ci/fedora.Dockerfile +++ b/.gitlab-ci/fedora.Dockerfile @@ -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 \ diff --git a/docs/reference/gio/gapplication.rst b/docs/reference/gio/gapplication.rst new file mode 100644 index 000000000..338b3a7e6 --- /dev/null +++ b/docs/reference/gio/gapplication.rst @@ -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 +| **gapplication** launch [FILE…] +| **gapplication** list-actions +| **gapplication** 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 [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 `` + + List the actions declared in the application’s ``.desktop`` file. The + parameter is the application ID, as above. + +``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 `_, +`gdbus(1) `_, +`xdg-open(1) `_, +`desktop-file-validate(1) `_ \ No newline at end of file diff --git a/docs/reference/gio/gapplication.xml b/docs/reference/gio/gapplication.xml deleted file mode 100644 index 13e3f2300..000000000 --- a/docs/reference/gio/gapplication.xml +++ /dev/null @@ -1,352 +0,0 @@ - - - gapplication - GIO - - - Developer - Ryan - Lortie - - - - - - gapplication - 1 - User Commands - - - - gapplication - D-Bus application launcher - - - - - gapplication - help - COMMAND - - - gapplication - version - - - gapplication - list-apps - - - gapplication - launch - APPID - - - gapplication - launch - APPID - FILE - - - gapplication - list-actions - APPID - - - gapplication - action - APPID - 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 - - - Global 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 - APPID - FILE - - - - Launches an application. - - - The first parameter is the application ID in the familiar "reverse DNS" style (eg: - '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 - APPID - - - - List the actions declared in the application's .desktop - file. The parameter is the application ID, as above. - - - - - - - action - APPID - 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 <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> 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, - - gdbus - 1 - , - - xdg-open - 1 - , - - desktop-file-validate - 1 - - - - - diff --git a/docs/reference/gio/gdbus-codegen.rst b/docs/reference/gio/gdbus-codegen.rst new file mode 100644 index 000000000..4a4c07f27 --- /dev/null +++ b/docs/reference/gio/gdbus-codegen.rst @@ -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 `_ +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 `_.) + +GENERATING RESTRUCTUREDTEXT DOCUMENTATION +----------------------------------------- + +Each generated reStructuredText file (see the ``--generate-rst`` option for +details) is a plain text +`reStructuredText `_ 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 `_. + +``--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 `_ or *Ugly_Case* (see + above). + +``--pragma-once`` + + If this option is passed, the + `#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 ````, ````, ```` and + ```` element to specify that the element is deprecated if its value + is ``true``. Note that this annotation is defined in the + `D-Bus specification `_ + 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 ````, ````, ```` and + ```` 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 ````, ````, ````, ```` and + ```` elements. + +``org.gtk.GDBus.DocString.Short`` + + A string with DocBook content for short/brief documentation. This annotation + can only be used on ```` elements. + +``org.gtk.GDBus.C.Name`` + + Can be used on any ````, ````, ```` and + ```` element to specify the name to use when generating C code. The + value is expected to be in + `CamelCase `_ 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 ```` and + ```` 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 ```` 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 `_:: + + + + + + + + + + + + + + + + + + + +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 `_ and +`constant `_ 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:: + + + + + + + + + + + + + + + + + + +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 `_) +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 `_) +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 `_ and +`GObject Introspection `_ 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 `_. + +SEE ALSO +-------- + +`gdbus(1) `_ \ No newline at end of file diff --git a/docs/reference/gio/gdbus-codegen.xml b/docs/reference/gio/gdbus-codegen.xml deleted file mode 100644 index 91d1f0784..000000000 --- a/docs/reference/gio/gdbus-codegen.xml +++ /dev/null @@ -1,1193 +0,0 @@ - - - - gdbus - GIO - - - Developer - David - Zeuthen - zeuthen@gmail.com - - - - - - gdbus-codegen - 1 - User Commands - - - - gdbus-codegen - D-Bus code and documentation generator - - - - - gdbus-codegen - , - org.project.Prefix - OUTFILES - YourProject - - none|objects|all - OUTDIR - OUTFILES - OUTFILES - - FILE - - - - - DECORATOR - HEADER - DEFINE - OUTFILE - - - - ELEMENT - KEY - VALUE - - - VERSION - VERSION - FILE - - 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 from files passed as additional - arguments on the command line and generates output files. - It currently supports generating C source code (via - ) or header (via ) - and Docbook XML (via ). Alternatively, - more restricted C source code and headers can be generated, which just - contain the interface information (as GDBusInterfaceInfo - structures) using and - . - - - - - 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 that - generates source code, that - generates headers, that generates - interface information source code, or - that generates interface information - headers, can be used. These options must be used along with - , which is used to specify the file to output to. - - - Both files can be generated at the same time by using - , but this option is deprecated. - In this case cannot be used due to the - generation of multiple files. Instead pass - 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 - 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 - - 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 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 - option for details) is a RefEntry - article describing the D-Bus interface. - - - - - Generating reStructuredText documentation - - Each generated reStructuredText file (see the - option for details) is a plain text - reStructuredText - document describing the D-Bus interface. - - - - - Options - - The following options are supported: - - - - - , - - - Show help and exit. - - - - - - FILE - - - This option is deprecated; use positional arguments instead. - The D-Bus introspection XML file. - - - - - - org.project.Prefix. - - - A prefix to strip from all D-Bus interface names when - calculating the typename for the C binding and the Docbook - sortas - attribute. - - - - - - OUTFILES - - - Generate Docbook Documentation for each D-Bus interface and - put it in OUTFILES-NAME.xml - where NAME is a place-holder for the interface - name, e.g. net.Corp.FooBar and so on. - - - Pass to specify the directory - to put the output files in. By default the current directory - will be used. - - - - - - OUTFILES - - - Generate reStructuredText Documentation for each D-Bus interface and - put it in OUTFILES-NAME.rst - where NAME is a place-holder for the interface - name, e.g. net.Corp.FooBar and so on. - - - Pass to specify the directory - to put the output files in. By default the current directory - will be used. - - - - - - 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 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}. - - - - - - YourProject - - - The namespace to use for generated C code. This is expected - to be in CamelCase - or Ugly_Case (see above). - - - - - - - - - If this option is passed, the - #pragma once - preprocessor directive is used instead of include guards. - - - - - - - - - If this option is passed, suitable #GDBusObject, - #GDBusObjectProxy, #GDBusObjectSkeleton and - #GDBusObjectManagerClient subclasses are generated. - - - - - - 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. - - - - - - OUTDIR - - - Directory to output generated source to. Equivalent to changing directory before generation. - - - This option cannot be used with , - , or - ; and - must be used. - - - - - - - - - - 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 . - - - Using , or - are not allowed to be used along with - and options, because these options - are used to generate only one file. - - - - - - - - - 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 . - - - Using , or - are not allowed to be used along with - and options, because these options - are used to generate only one file. - - - - - - - - - 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 - . - - - Using , or - are not allowed to be used along with - the and - options, because these options - are used to generate only one file. - - - - - - - - - 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 - . - - - Using , or - are not allowed to be used along with - the and - options, because these options - are used to generate only one file. - - - - - - 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 is added in GLib-2.66 - - - - - - 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 is used). This is used if using another header file is - needed for the decorator passed in via to be defined. - This option is added in GLib-2.66. - - - This option can only be used if is used. - - - - - - 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 uses the correct definition when the - generated source is being compiled. This option is added in GLib-2.66. - - - This option can only be used if is used. - - - - - - OUTFILE - - - The full path where the header (, - ) or the source code - (, ) will - be written, using the path and filename provided by - . The full path could be something like - $($OUTFILE).{c,h}. - - - Using , or - is not allowed along with - , because the latter is used to generate only one file. - - - - - - 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: - - - - Any UTF-8 string can be used for KEY and VALUE. - - - - - - 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 . - 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(). - - - - - - 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 . - 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 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 . - - - 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 - 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: -longer description. - - This is a new paragraph. ---> - - - - - - - - - - - - - - - - -]]> - - - Note that 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 - , - , - and - are all - expanded to links to the respective interface, method, signal and - property. - Additionally, substrings starting with @ and % characters are rendered as - parameter and - constant 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. - - - - - - - - - - - - - - - - - -]]> - - - If gdbus-codegen is used on this file like this: - - - - 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: - - - - 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: - - - - - - - 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 GObject signal. - Use m_a_f_emit_notification() to emit signal. - - - Properties (Reading) - Use m_a_f_get_verbose() or :verbose. - Implement #GObject's get_property() vfunc. - - - Properties (writing) - Use m_a_f_set_verbose() or :verbose. - Implement #GObject's set_property() vfunc. - - - - - - - Client-side usage - - You can use the generated proxy type with the generated - constructors: - - - - 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 #GDBusProxy's - 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 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 #GObject's - get_property() and - set_property() vfuncs, use - g_object_get() and - g_object_set() or the generated property - getters and setters (the generated class has an internal - property bag implementation). - - - - 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 - 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 string (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 #GTypes will be preserved only if - the org.gtk.GDBus.Since annotation is used - judiciously — this is because the VTable for the #GInterface - relies on functions 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 / GObject - Introspection comments / annotations. The layout and - contents might change in the future so no guarantees about - e.g. SECTION usage etc. is 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 revision 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 at - https://gitlab.gnome.org/GNOME/glib/issues/new. - - - - - See also - - - gdbus1 - - - - - diff --git a/docs/reference/gio/gdbus.rst b/docs/reference/gio/gdbus.rst new file mode 100644 index 000000000..b0ea98d50 --- /dev/null +++ b/docs/reference/gio/gdbus.rst @@ -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},) + /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': },) + /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': },) + /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': },) + +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 `_. + +SEE ALSO +-------- + +`dbus-send(1) `_ \ No newline at end of file diff --git a/docs/reference/gio/gdbus.xml b/docs/reference/gio/gdbus.xml deleted file mode 100644 index 60c172e05..000000000 --- a/docs/reference/gio/gdbus.xml +++ /dev/null @@ -1,429 +0,0 @@ - - - - gdbus - GIO - - - Developer - David - Zeuthen - zeuthen@gmail.com - - - - - - gdbus - 1 - User Commands - - - - gdbus - Tool for working with D-Bus objects - - - - - 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 - - ARG1 - ARG2 - - - gdbus - emit - - --system - --session - --address address - - --object-path /path/to/object - --signal org.project.InterfaceName.SignalName - - --dest unique_bus_name - - ARG1 - ARG2 - - - 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 - - - - - 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 option is used, the returned - introspection XML is printed, otherwise a parsed pretty - representation is printed. - The option can be used to - introspect children (and their children and so on) and the - option can be used to - only print the interfaces with properties. - - - - - - Monitors one or all objects owned by the owner of - bus_name. - - - - - - 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. - - - - - - 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. - - - - - - Waits until bus_name is owned by some - process on the bus. If the is specified, - that bus name will be auto-started first. It may be the same as the - bus name being waited for, or different. - - - - - - Prints help and exit. - - - - - - - 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 and 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 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 - 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 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 at - . - - - - - See Also - - - dbus-send1 - - - - - - diff --git a/docs/reference/gio/gio-querymodules.rst b/docs/reference/gio/gio-querymodules.rst new file mode 100644 index 000000000..79141b5c4 --- /dev/null +++ b/docs/reference/gio/gio-querymodules.rst @@ -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. \ No newline at end of file diff --git a/docs/reference/gio/gio-querymodules.xml b/docs/reference/gio/gio-querymodules.xml deleted file mode 100644 index c9c5eeccc..000000000 --- a/docs/reference/gio/gio-querymodules.xml +++ /dev/null @@ -1,45 +0,0 @@ - - - - glib-compile-schemas - GIO - - - Developer - Alexander - Larsson - - - - - - gio-querymodules - 1 - User Commands - - - - gio-querymodules - GIO module cache creation - - - - - 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. - - - diff --git a/docs/reference/gio/gio.rst b/docs/reference/gio/gio.rst new file mode 100644 index 000000000..d3ffa3ede --- /dev/null +++ b/docs/reference/gio/gio.rst @@ -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=`` + + 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=`` + + 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=`` + + 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=`` + + 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=`` + + Monitor the file directly. This allows changes made via hardlinks to be + captured. + + ``-s``, ``--silent=`` + + 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=`` + + Mount volume with device file, or other identifier. + + ``-u``, ``--unmount`` + + Unmount the location. + + ``-e``, ``--eject`` + + Eject the location. + + ``-t``, ``--stop=`` + + Stop drive with device file. + + ``-s``, ``--unmount-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=`` + + 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=`` + + 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) `_, `cp(1) `_, `ls(1) `_, +`mkdir(1) `_, `mv(1) `_, `rm(1) `_, +`tree(1) `_ \ No newline at end of file diff --git a/docs/reference/gio/gio.xml b/docs/reference/gio/gio.xml deleted file mode 100644 index 1805b2790..000000000 --- a/docs/reference/gio/gio.xml +++ /dev/null @@ -1,809 +0,0 @@ - - - - - gio - GIO - - - Developer - Matthias - Clasen - mclasen@redhat.com - - - - - - gio - 1 - User Commands - - - - gio - GIO commandline tool - - - - - 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 - MIMETYPE - 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. - Note: just pipe through cat if you need its formatting options - like , 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 - - - , - Don’t copy into DESTINATION even if it is a directory. - - - , - Show progress. - - - , - Prompt for confirmation before overwriting files. - - - - Preserve all attributes of copied files. - - - , - Create backups of existing destination files. - - - , - Never follow symbolic links. - - - - 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 - - - , - List writable attributes. - - - , - Show information about the filesystem that the given - locations reside on. - - - - 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 comma. - By default, all attributes are listed. - - - , - 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 - - - - 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 comma. - By default, all attributes are listed. - - - , - Show hidden files. - - - , - Use a long listing format. - - - , - Don’t follow symbolic links. - - - , - Print display names. - - - , - Print full URIs. - - - - - - - - - mime - MIMETYPE - HANDLER - - - If no handler is given, the mime 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. - 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 - - - , - 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 - - - , - Monitor the given location as a directory. Normally, - the file type is used to determine whether to monitor a file or directory. - - - , - Monitor the given location as a file. Normally, - the file type is used to determine whether to monitor a file or directory. - - - , - Monitor the file directly. This allows changes made via hardlinks to be captured. - - - , - Monitor the file directly, but don’t report changes. - - - , - Report moves and renames as simple deleted/created events. - - - , - 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 - - - , - Mount as mountable. - - - , - Mount volume with device file, or other identifier. - - - , - Unmount the location. - - - , - Eject the location. - - - , - Stop drive with device file. - - - , - Unmount all mounts with the given scheme. - - - , - Ignore outstanding file operations when unmounting or ejecting. - - - , - Use an anonymous user when authenticating. - - - , - List all GIO mounts. - - - , - Monitor mount-related events. - - - - , - Show extra information. - - - - - The numeric PIM when unlocking a VeraCrypt volume. - - - - - Mount a TCRYPT hidden volume. - - - - - 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 - - - , - Don’t copy into DESTINATION even if it is a directory. - - - , - Show progress. - - - , - Prompt for confirmation before overwriting files. - - - , - Create backups of existing destination files. - - - , - 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 mimetype. - 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 - - - , - 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 - - - , - Back up existing destination files. - - - , - Only create the destination if it doesn’t exist yet. - - - , - Append to the end of the file. - - - , - When creating, restrict access to the current user. - - - , - When replacing, replace as if the destination did not exist. - - - , - Print the new ETag in the end. - - - , - The ETag of the file that is overwritten. - - - - - - - - - set - 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 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 - - - , - 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. - - - - , - Unsets an attribute (same as setting it's type to unset). - - - , - 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 - - - , - Ignore non-existent and non-deletable files. - - - - Empty the trash. - - - - List files in the trash with their original locations - - - - 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 - - - , - Show hidden files. - - - , - Follow symbolic links. - - - - - - - - - - Exit status - On success 0 is returned, a non-zero failure code otherwise. - - - - See Also - - - cat - 1 - , - - cp - 1 - , - - ls - 1 - , - - mkdir - 1 - , - - mv - 1 - , - - rm - 1 - , - - tree - 1 - . - - - diff --git a/docs/reference/gio/glib-compile-resources.rst b/docs/reference/gio/glib-compile-resources.rst new file mode 100644 index 000000000..096dc1dbb --- /dev/null +++ b/docs/reference/gio/glib-compile-resources.rst @@ -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 `_. + +OPTIONS +------- + +``-h``, ``--help`` + + Print help and exit. + +``--version`` + + Print program version and exit. + +``--target `` + + Store the compiled resources in the file ``TARGET``. If not specified a + filename based on the ``FILE`` basename is used. + +``--sourcedir `` + + 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 `` + + 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 `` + + 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``. \ No newline at end of file diff --git a/docs/reference/gio/glib-compile-resources.xml b/docs/reference/gio/glib-compile-resources.xml deleted file mode 100644 index 7ab36f5a9..000000000 --- a/docs/reference/gio/glib-compile-resources.xml +++ /dev/null @@ -1,254 +0,0 @@ - - - - glib-compile-schemas - GIO - - - Developer - Alexander - Larsson - - - - - - glib-compile-resources - 1 - User Commands - - - - glib-compile-resources - GLib resource compiler - - - - - 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. - - - -Options - - - -, - -Print help and exit - - - - - - -Print program version and exit - - - - - - -Store the compiled resources in the file TARGET. -If not specified a filename based on the FILE -basename is used. - - - - - - -The files referenced in FILE are loaded from -this directory. If not specified, the current directory is used. - - - - - - -Write the output file in the format selected for by its filename extension: - - -.c -C source - - -.h -C header - - -.gresource -resource bundle - - - - - - - - -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 a header file for use with C code generated by -. - - - - - - -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 is 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 . - - - - - - - -Specify the prefix used for the C identifiers in the code generated by - and . - - - - - - -By default code generated by 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 , -which will generate custom register and unregister functions that your code -can manually call at initialization and uninitialization time. - - - - - - -By default code generated by 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 does. - - - - - - -By default code generated by embeds the -resource data as a string literal. When -is given, the data is only declared in the generated C file, and the data -has to be linked externally. - - - - - - -Write dependencies in the same style as gcc -M -MF to the given file. -If is -, the dependencies are written to the standard -output. Unlike , this option can be -combined with other options to generate dependencies -as a side-effect of generating sources. - - - - - - -When creating a dependency file with -include phony targets in the same style as gcc -MP. This would typically -be used with make. - - - - - - -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. - - - - - - diff --git a/docs/reference/gio/glib-compile-schemas.rst b/docs/reference/gio/glib-compile-schemas.rst new file mode 100644 index 000000000..4f420929f --- /dev/null +++ b/docs/reference/gio/glib-compile-schemas.rst @@ -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 `` + + 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. \ No newline at end of file diff --git a/docs/reference/gio/glib-compile-schemas.xml b/docs/reference/gio/glib-compile-schemas.xml deleted file mode 100644 index 0796bd744..000000000 --- a/docs/reference/gio/glib-compile-schemas.xml +++ /dev/null @@ -1,118 +0,0 @@ - - - - glib-compile-schemas - GIO - - - Developer - Ryan - Lortie - - - - - - glib-compile-schemas - 1 - User Commands - - - - glib-compile-schemas - GSettings schema compiler - - - - - 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 (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). - - - -Options - - - -, - -Print help and exit - - - - - - -Print program version and exit - - - - - - -Store gschemas.compiled in the TARGET directory instead of DIRECTORY. - - - - - - -Abort on any errors in schemas. Without this option, faulty schema files are -simply omitted from the resulting compiled schema. - - - - - - -Don't write gschemas.compiled. This option can be used -to check .gschema.xml sources for errors. - - - - - - -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. - - - - - - diff --git a/docs/reference/gio/gresource.rst b/docs/reference/gio/gresource.rst new file mode 100644 index 000000000..cb65c69fe --- /dev/null +++ b/docs/reference/gio/gresource.rst @@ -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. \ No newline at end of file diff --git a/docs/reference/gio/gresource.xml b/docs/reference/gio/gresource.xml deleted file mode 100644 index 4ada0eb16..000000000 --- a/docs/reference/gio/gresource.xml +++ /dev/null @@ -1,127 +0,0 @@ - - - - gresource - GIO - - - Developer - Matthias - Clasen - - - - - - gresource - 1 - User Commands - - - - gresource - GResource tool - - - - - 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 - - - - - -Lists resources. If SECTION is given, only -list resources in this section. If PATH is -given, only list matching resources. - - - - - - -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. - - - - - - -Extracts the resource named by PATH to stdout. -Note that resources may contain binary data. - - - - - - -Lists sections containing resources. This is only interesting if -FILE is an elf file. - - - - - - -Prints help and exits. - - - - - - - diff --git a/docs/reference/gio/gsettings.rst b/docs/reference/gio/gsettings.rst new file mode 100644 index 000000000..c89aa356b --- /dev/null +++ b/docs/reference/gio/gsettings.rst @@ -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. \ No newline at end of file diff --git a/docs/reference/gio/gsettings.xml b/docs/reference/gio/gsettings.xml deleted file mode 100644 index 5f720d6e7..000000000 --- a/docs/reference/gio/gsettings.xml +++ /dev/null @@ -1,248 +0,0 @@ - - - - gsettings - GIO - - - Developer - Ryan - Lortie - - - - - - gsettings - 1 - User Commands - - - - gsettings - GSettings configuration tool - - - - - 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 - - - - - -Gets the value of KEY. -The value is printed out as a serialized -GVariant. - - - - - - -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. - - - - - - -Finds out whether KEY is writable. - - - - - - -Queries the range of valid values for KEY. - - - - - - -Queries the description of valid values for KEY. - - - - - - -Sets the value of KEY to -VALUE. The value is specified as a serialized -GVariant. - - - - - - -Resets KEY to its default value. - - - - - - -Reset all keys under the given SCHEMA. - - - - - - -Lists the installed, non-relocatable schemas. -See if you are interested in -relocatable schemas. If -is given, the path where each schema is mapped is also printed. - - - - - - -Lists the installed, relocatable schemas. -See if you are interested in -non-relocatable schemas. - - - - - - -Lists the keys in SCHEMA. - - - - - - -Lists the children of SCHEMA. - - - - - - -Lists keys and values, recursively. If no SCHEMA -is given, list keys in all schemas. - - - - - - -Prints help and exits. - - - - - - - diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index 060cf0708..1b5f4468c 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -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', diff --git a/docs/reference/glib/building.md b/docs/reference/glib/building.md index 450227ab4..1a59c69d2 100644 --- a/docs/reference/glib/building.md +++ b/docs/reference/glib/building.md @@ -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 diff --git a/docs/reference/glib/glib-gettextize.rst b/docs/reference/glib/glib-gettextize.rst new file mode 100644 index 000000000..78b3a06df --- /dev/null +++ b/docs/reference/glib/glib-gettextize.rst @@ -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 `_. +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) `_ \ No newline at end of file diff --git a/docs/reference/glib/glib-gettextize.xml b/docs/reference/glib/glib-gettextize.xml deleted file mode 100644 index f016b2855..000000000 --- a/docs/reference/glib/glib-gettextize.xml +++ /dev/null @@ -1,88 +0,0 @@ - - - -glib-gettextize -GLib - - -Developer -Owen -Taylor - - - - - -glib-gettextize -1 -User Commands - - - -glib-gettextize -gettext internationalization utility - - - - -glib-gettextize -OPTION -DIRECTORY - - - -Description -glib-gettextize helps to prepare a source package for being -internationalized through 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 - option). - - - -Options - - - - - -print help and exit - - - - - - -print version information and exit - - - - -, - -copy files instead of making symlinks - - - - -, - -force writing of new files even if old ones exist - - - - - -See also - -gettextize1 - - - diff --git a/docs/reference/glib/gtester-report.rst b/docs/reference/glib/gtester-report.rst new file mode 100644 index 000000000..b6c5b313c --- /dev/null +++ b/docs/reference/glib/gtester-report.rst @@ -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) `_ \ No newline at end of file diff --git a/docs/reference/glib/gtester-report.xml b/docs/reference/glib/gtester-report.xml deleted file mode 100644 index eee933784..000000000 --- a/docs/reference/glib/gtester-report.xml +++ /dev/null @@ -1,78 +0,0 @@ - - - -gtester-report -GLib - - -Developer -Tim -Janik - - - - - -gtester-report -1 -User Commands - - - -gtester-report -test report formatting utility - - - - -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 - - - -, - -print help and exit - - - - -, - -print version information and exit - - - - -, - -Output subunit. Needs python-subunit. - - - - - - -See also - - -gtester -1 - - - - diff --git a/docs/reference/glib/gtester.rst b/docs/reference/glib/gtester.rst new file mode 100644 index 000000000..68c3f24e4 --- /dev/null +++ b/docs/reference/glib/gtester.rst @@ -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=`` + + 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=`` + + Only run test cases matching ``TEST-PATH``. + +``-s=`` + + Skip test cases matching ``TEST-PATH``. + +``--seed=`` + + Run all test cases with random number seed ``SEED-STRING``. + +``-o=`` + + Write the test log to ``LOG-FILE``. + +``-q``, ``--quiet`` + + Suppress per-test-binary output. + +``--verbose`` + + Report success per testcase. + +SEE ALSO +-------- + +`gtester-report(1) `_ \ No newline at end of file diff --git a/docs/reference/glib/gtester.xml b/docs/reference/glib/gtester.xml deleted file mode 100644 index 5626d4df8..000000000 --- a/docs/reference/glib/gtester.xml +++ /dev/null @@ -1,192 +0,0 @@ - - - -gtester -GLib - - -Developer -Tim -Janik - - -Developer -Sven -Herzberg - - - - - -gtester -1 -User Commands - - - -gtester -test running utility - - - - -gtester -OPTION -testprogram - - - -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 option, gtester -writes an XML report of the test results, which can be converted -into HTML using the gtester-report utility. - - - -Options - - - -, - -print help and exit - - - - -, - -print version information and exit - - - - - - -make warnings fatal - - - - -, - -continue running after tests failed - - - - - - -list paths of available test cases - - - - - - - run test cases in MODE, which can be one of: - - - - - - run performance tests - - - - - , - - run slow tests, or repeat non-deterministic tests more often - - - - - - - do not run slow or performance tests, or do extra repeats - of non-deterministic tests (default) - - - - - - - run test cases that deliberately provoke checks or assertion - failures, if implemented (default) - - - - - - - do not run test cases that deliberately provoke checks or - assertion failures - - - - - - - - - - -only run test cases matching TESTPATH - - - - - - -skip test cases matching TESTPATH - - - - - - -run all test cases with random number seed SEEDSTRING - - - - - - -write the test log to LOGFILE - - - - -, - -suppress per test binary output - - - - - - -report success per testcase - - - - - - -See also - - -gtester-report -1 - - - - diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index f013a5469..028e0e352 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -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', diff --git a/docs/reference/gobject/glib-genmarshal.rst b/docs/reference/gobject/glib-genmarshal.rst new file mode 100644 index 000000000..0e503489b --- /dev/null +++ b/docs/reference/gobject/glib-genmarshal.rst @@ -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 `` + + 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 `` + + 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
`` + + Adds a ``#include`` directive for the given file in the C source file. This + option is only useful when using the ``--body`` option. + +``-D [=]`` + + 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 `` + + 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 `_. + +For more information on how to use the method, see the +`Meson documentation `_ +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) `_ \ No newline at end of file diff --git a/docs/reference/gobject/glib-genmarshal.xml b/docs/reference/gobject/glib-genmarshal.xml deleted file mode 100644 index 2b3e86fdc..000000000 --- a/docs/reference/gobject/glib-genmarshal.xml +++ /dev/null @@ -1,579 +0,0 @@ - - - - glib-genmarshal - GObject - - - Developer - Emmanuele - Bassi - - - Original developer - Tim - Janik - - - - - -glib-genmarshal -1 -User Commands - - - -glib-genmarshal -C code marshaller generation utility for GLib closures - - - - -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 PTYPEs right to 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 64bit integer types (gint64) - - - - -UINT64 - -for unsigned 64bit 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 - - - - - -Generate header file contents of the marshallers. This option is mutually -exclusive with the option. - - - - - - -Generate C code file contents of the marshallers. This option is mutually -exclusive with the option. - - - - - - -Specify marshaller prefix. The default prefix is `g_cclosure_user_marshal'. - - - - - - -Skip source location remarks in generated comments. - - - - - - -Use the standard marshallers of the GObject library, and include -glib-object.h in generated header files. This -option is mutually exclusive with the -option. - - - - - - -Do not use the standard marshallers of the GObject library, and skip -glib-object.h include directive in generated header files. -This option is mutually exclusive with the option. - - - - - - -Mark generated functions as internal, using G_GNUC_INTERNAL. - - - - - - -Generate valist marshallers, for use with g_signal_set_va_marshaller(). - - - - -, - -Print version information. - - - - - - -Make warnings fatal, that is, exit immediately once a warning occurs. - - - - -, - -Print brief help and exit. - - - - -, - -Print version and exit. - - - - - - -Write output to FILE instead of the standard output. - - - - - - -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 -option. - - - - - - -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 - option. - - - - - - -Adds a #include directive for the given file in the C -source file. This option is only useful when using the -option. - - - - - - -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 option. This option is only -useful when using the option. - - - - - - -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 option. -This option is only useful when using the option. - - - - - - -Minimizes the output of glib-genmarshal, by printing only -warnings and errors. This option is mutually exclusive with the - option. - - - - - - -Increases the verbosity of glib-genmarshal, by printing -debugging information. This option is mutually exclusive with the - option. - - - - - - -Using <command>glib-genmarshal</command> 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. - - -For more information on how to use the method, see the -Meson -documentation for gnome.genmarshal(). - - - -Using <command>glib-genmarshal</command> 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 - - - - diff --git a/docs/reference/gobject/glib-mkenums.rst b/docs/reference/gobject/glib-mkenums.rst new file mode 100644 index 000000000..d6a5ccef6 --- /dev/null +++ b/docs/reference/gobject/glib-mkenums.rst @@ -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 `` + + 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 `` + + 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 `` + + 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 `` + + Emits ``TEXT`` every time an enum is encountered in the input files. + +``--vhead `` + + 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 `` + + 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 `` + + 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 `` + + Template for auto-generated comments, the default (for C code generations) is + ``"/* @comment@ */"``. + +``--template `` + + 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 `` + + 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 `` + + 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 `` + + 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 `_. + +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 `_ +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) `_ \ No newline at end of file diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml deleted file mode 100644 index f290fe0a6..000000000 --- a/docs/reference/gobject/glib-mkenums.xml +++ /dev/null @@ -1,659 +0,0 @@ - - - - gdbus - GObject - - - Developer - Owen - Taylor - - - - - -glib-mkenums -1 -User Commands - - - -glib-mkenums -C language enum description generation utility - - - - -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 or not (e.g. flags). - - - - -@Type@ - -The same as @type@ with the first letter capitalized (e.g. Flags). - - - - -@TYPE@ - -The same as @type@ with all letters uppercased (e.g. FLAGS). - - - - -@filename@ - -The 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 - - - - 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. - - - - - 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. - - - - - 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. - - - - - TEXT - -Emits TEXT every time an enum is encountered -in the input files. - - - - - 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. - - - - - 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. - - - - - 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. - - - - - TEXT - -Template for auto-generated comments, the default (for C code generations) is -"/* @comment@ */". - - - - - 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. - - - - - PREFIX - -Indicates what portion of the enum name should be interpreted as the -prefix (eg, the "Gtk" in -"GtkDirectionType"). Normally this will be figured -out automatically, but you may need to override the default if your -namespace is capitalized oddly. - - - - - PREFIX - -Indicates what prefix should be used to correspond to the identifier -prefix in related C function names (eg, the "gtk" -in "gtk_direction_type_get_type". Equivalently, -this is the lowercase version of the prefix component of the enum -value names (eg, the "GTK" in -"GTK_DIR_UP". The default value is the identifier -prefix, converted to lowercase. - - - - - - -Print brief help and exit. - - - - - - -Print version and exit. - - - - - - -Write output to FILE instead of stdout. - - - - - - -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 gsize static_g_@type@_type_id; - - if (g_once_init_enter (&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 (&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: - - - 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 + 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. - - - -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 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 - - - - diff --git a/docs/reference/gobject/gobject-query.rst b/docs/reference/gobject/gobject-query.rst new file mode 100644 index 000000000..4aa4d0c5b --- /dev/null +++ b/docs/reference/gobject/gobject-query.rst @@ -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 `` + + Specify the root type. + +``-n`` + + Don’t descend type tree. + +``-b `` + + Specify indent string. + +``-i `` + + Specify incremental indent string. + +``-s `` + + Specify line spacing. + +``-h``, ``--help`` + + Print brief help and exit. + +``-v``, ``--version`` + + Print version and exit. \ No newline at end of file diff --git a/docs/reference/gobject/gobject-query.xml b/docs/reference/gobject/gobject-query.xml deleted file mode 100644 index 437d714ff..000000000 --- a/docs/reference/gobject/gobject-query.xml +++ /dev/null @@ -1,123 +0,0 @@ - - - - gobject-query - GObject - - - Developer - Tim - Janik - - - - - -gobject-query -1 -User Commands - - - -gobject-query -display a tree of types - - - - -gobject-query -froots -OPTION - - -gobject-query -tree -OPTION - - - -Description - -gobject-query is a small utility that draws a tree of -types. - - - -gobject-query takes a mandatory argument that specifies -whether it should iterate over the fundamental types or print a type tree. - - - -Commands - - - - -iterate over fundamental roots - - - - - -print type tree - - - - - -Options - - - - TYPE - -specify the root type - - - - - - -don't descend type tree - - - - - STRING - -specify indent string - - - - - STRING - -specify incremental indent string - - - - - - NUMBER - -specify line spacing - - - - -, - -Print brief help and exit. - - - - -, - -Print version and exit. - - - - - - diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 4ceb2db23..ad0d1deaf 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -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', diff --git a/meson.build b/meson.build index 0ee4ca014..451590bec 100644 --- a/meson.build +++ b/meson.build @@ -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(), diff --git a/meson_options.txt b/meson_options.txt index 83ede7fd4..69a2135bc 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -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',