The gdbus-codegen tool generates documentation from the XML introspection
description of a D-Bus interface. Currently, only DocBook is supported at
the moment, but not every modern documentation generator can handle that
format. The reStructuredText format is a bit more well-supported,
especially in documentation generators for non-C languages.
Unlike DocBook, we get to make our own structure and conventions for how
we structure the documentation when using reStructuredText.
When parsing a comment we're adding <para> elements ourselves, but the
DocBook generator already wraps any block of text that does not start
with a <para> element with one.
The version of `black` on the CI server wanted these changes. Make them
to keep the `style-check-diff` CI job from constantly failing.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is the unmodified results of running
```
black $(git ls-files '*.py')
```
with black version 19.10b0. See #2046.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Like G_SOURCE_REMOVE and G_SOURCE_CONTINUE, these make it clearer what
it means to return TRUE or FALSE.
In particular, in GDBus methods that fail, the failure case still needs
to return TRUE (unlike the typical GError pattern), leading to comments
like this:
g_dbus_method_invocation_return_error (invocation, ...);
return TRUE; /* handled */
which can now be replaced by:
g_dbus_method_invocation_return_error (invocation, ...);
return G_DUS_METHOD_INVOCATION_HANDLED;
G_DBUS_METHOD_INVOCATION_UNHANDLED is added for symmetry, but is very
rarely (perhaps never?) useful in practice.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This was mostly machine generated with the following command:
```
codespell \
--builtin clear,rare,usage \
--skip './po/*' --skip './.git/*' --skip './NEWS*' \
--write-changes .
```
using the latest git version of `codespell` as per [these
instructions](https://github.com/codespell-project/codespell#user-content-updating).
Then I manually checked each change using `git add -p`, made a few
manual fixups and dropped a load of incorrect changes.
There are still some outdated or loaded terms used in GLib, mostly to do
with git branch terminology. They will need to be changed later as part
of a wider migration of git terminology.
If I’ve missed anything, please file an issue!
Signed-off-by: Philip Withnall <withnall@endlessm.com>
This adds three options to gdbus-codegen so that we may be able to
use a self-defined symbol decorator, such as _GLIB_EXTERN, to decorate
the generated prototypes, to be used possibly to export the symbols, if
needed.
The other two options allows including headers that are required for the
specified symbol decorator to be usable and preprocessor macros that are
required for the symbol decorator to be defined appropriately, also when
needed.
There were a couple of custom paths which could end up being relative,
rather than absolute, due to not properly prefixing them with
`get_option('prefix')`.
The use of `join_paths()` here correctly drops all path components
before the final absolute path in the list of arguments. So if someone
configures GLib with an absolute path for `gio_module_dir`, that will be
used unprefixed; but if someone configures with a relative path, it will
be prefixed by `get_option('prefix)`.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Fixes: #1919
Python tuple comparisons actually do what we want for comparing major
and minor versions, so tidy things up by using that.
This introduces no functional changes.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
This complements the `--glib-min-required` argument, just like the
`GLIB_MIN_REQUIRED` and `GLIB_MAX_ALLOWED` preprocessor defines which
control access to APIs in C.
Currently, it doesn’t affect code generation at all. When we next change
code generation, we will need to gate any new API usage on this
argument.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Fixes: #1993
This makes it consistent with the `GLIB_MIN_REQUIRED` defines which are
used for API stability/versioning in C code.
It doesn’t otherwise change the behaviour of the `--glib-min-version`
argument.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Helps: #1993
Currently the code generated by gdbus-codegen uses
G_DBUS_CALL_FLAGS_NONE in its D-Bus calls, which occur for each method
defined by the input XML, and for proxy_set_property functions. This
means that if the daemon which implements the methods checks for
G_DBUS_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION and only does interactive
authorization if that flag is present, users of the generated code have
no way to cause the daemon to use interactive authorization (e.g. polkit
dialogs).
If we simply changed the generated code to always use
G_DBUS_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION, its users would have no
way to disallow interactive authorization (except for manually calling
the D-Bus method themselves).
So instead, this commit adds a GDBusCallFlags argument to method call
functions. Since this is an API break which will require changes in
projects using gdbus-codegen code, the change is conditional on the
command line argument --glib-min-version having the value 2.64 or
higher.
The impetus for this change is that I'm changing accountsservice to
properly respect G_DBUS_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION, and
libaccountsservice uses generated code for D-Bus method calls. So
these changes will allow libaccountsservice to continue allowing
interactive authorization, and avoid breaking any users of it which
expect that. See
https://gitlab.freedesktop.org/accountsservice/accountsservice/merge_requests/46
It might make sense to also let GDBusCallFlags be specified for property
set operations, but that is not needed in the case of accountsservice,
and would require significant work and breaking API in multiple places.
Similarly, the generated code currently hard codes -1 as the timeout
value when calling g_dbus_proxy_call*(). Add a timeout_msec argument so
the user of the generated code can specify the timeout as well.
Also, test this new API. In gio/tests/codegen.py we test that the new
arguments are generated if and only of --glib-min-version is used with a
value greater than or equal to 2.64, and in gio/tests/meson.build we
test that the generated code with the new API can be linked against.
The test_unix_fd_list() test also needed modification to continue
working now that we're using gdbus-test-codegen.c with code generated
with --glib-min-version=2.64 in one test.
Finally, update the docs for gdbus-codegen to explain the effect of
using --glib-min-version 2.64, both from this commit and from
"gdbus-codegen: Emit GUnixFDLists if an arg has type `h` w/
min-version".
This is a reimplementation of commit
4aba03562b from Will Thompson, but
conditional on the caller passing `--glib-min-version 2.64` to
`gdbus-codegen` to explicitly opt-in to the new behaviour.
From the commit message for that commit:
Previously, if a method was not annotated with org.gtk.GDBus.C.UnixFD
then the generated code would never contain GUnixFDList parameters, even
if the method has 'h' (file descriptor) parameters. However, in this
case, the generated code is essentially useless: the method cannot be
called or handled except in degenerate cases where the file descriptors
are missing or ignored.
Check the argument types for 'h', and if present, generate code as if
org.gtk.GDBus.C.UnixFD annotation were specified.
Includes a unit test too.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Fixes: #1726
This can be used by callers to opt-in to backwards-incompatible changes
to the behaviour or output of `gdbus-codegen` in future. This commit
doesn’t introduce any such changes, though.
Documentation and unit tests included.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Helps: #1726
gtk-doc switched from DocBook to Markdown ages ago. There is no Markdown
equivalent for `<warning>`, so just drop it. It wasn’t adding anything
particularly valuable to the documentation.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Fixes: #1130
gtk-doc long since switched to Markdown, so we shouldn’t be emitting
DocBook `<link>` tags.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Helps: #1130
Previously, running `gdbus-codegen` with no arguments would exit
successfully with no output. While technically correct, that seems
unhelpful.
Require at least one interface file to be specified, so the user gets an
error message if they don’t specify any.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
It’s not particularly useful to put the gdbus-codegen version or the
name of the input file into the output from `gdbus-codegen`, and it
makes the output less reproducible. Drop it.
Also clarify the licensing.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Helps: #1612
Whitelist a safe set of characters for use in header guards instead of
maintaining a (growing) blacklist.
The whitelist is intentionally short since reading up on all
peculiarities of the C and C++ standard for identifiers is not my idea
of fun. :)
Fixes#1379
This reverts commit 4aba03562b, preserving
the new tests but adjusting them to assert that the old behaviour is
restored.
As expected, there were a few projects which broke because of this.
Unfortunately, in one case the breakage crosses a project boundary:
sysprof ships D-Bus introspection XML, which is consumed by mutter and
passed through gdbus-codegen.
Since sysprof cannot add this annotation without breaking its existing
users, a warning is also not appropriate.
https://gitlab.gnome.org/GNOME/jhbuild/issues/41https://gitlab.gnome.org/GNOME/sysprof/issues/17https://gitlab.gnome.org/GNOME/glib/issues/1726
Previously, if a method was not annotated with org.gtk.GDBus.C.UnixFD
then the generated code would never contain GUnixFDList parameters, even
if the method has 'h' (file descriptor) parameters. However, in this
case, the generated code is essentially useless: the method cannot be
called or handled except in degenerate cases where the file descriptors
are missing or ignored.
Check the argument types for 'h', and if present, generate code as if
org.gtk.GDBus.C.UnixFD annotation were specified.
This change will break any existing code which refers to the (useless)
wrappers for such methods. The workaround for such code is to add the
org.gtk.GDBus.C.UnixFD annotation, which will cause the same generated
code to be emitted before and after this change.
If this is found to cause widespread problems, we can explore a
different approach (perhaps emitting a warning from the code generator,
or annotating the symbols as deprecated).
https://gitlab.gnome.org/GNOME/glib/issues/1726
We're using the `install` argument for configure_file() all over the
place.
The support for an `install` argument for configure_file() was added in
Meson 0.50, but we haven't bumped the minimum version of Meson we
require, yet; which means we're getting compatibility warnings when
using recent versions of Meson, and undefined behaviour when using older
versions.
The configure_file() object defaults to `install: false`, unless an
install directory is used. This means that all instances of an `install`
argument with an explicit `true` or `false` value can be removed,
whereas all instances of `install` with a value determined from a
configuration option must be turned into an explicit conditional.
If using the --interface-info-{body,header} options to gdbus-codegen,
and the first interface to be outputted has no methods, but does have
properties or signals, an uninitialised variable would be used for the
property/signal ‘since’ values.
In other situations, the ‘since’ value for a prior method would have
been incorrectly used for the properties/signals.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
So long, and thanks for everything. We’re a Meson-only shop now.
glib-2-58 will remain the last stable GLib release series which is
buildable using autotools.
We continue to install autoconf macros for autotools-using projects
which depend on GLib; they are stable API.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
This means the output (including lists of filenames) does not depend on
the order of the input files, which may matter if this tool is invoked
with a glob or some other mechanism that doesn't guarantee an order.
Previously, method and signal arguments were sorted by name, which
(assuming you don't happen to give your arguments
lexicographically-ordered names) means the generated signatures were
incorrect when there is more than 1 argument.
While sorting the methods and signals themselves (and properties, and
annotations on all these) is fine, it's easiest to not sort anything.
Since 1217b1bc4f, LICENSE_STR has taken two
parameters, not one. Without this change, running either mode fails
with a traceback like:
Traceback (most recent call last):
File "../gdbus-codegen", line 55, in <module>
sys.exit(codegen_main.codegen_main())
File ".../codegen_main.py", line 294, in codegen_main
gen.generate()
File ".../codegen.py", line 896, in generate
self.generate_body_preamble()
File ".../codegen.py", line 682, in generate_body_preamble
self.outfile.write(LICENSE_STR.format(config.VERSION))
IndexError: tuple index out of range
8916874ee6, which introduced these flags,
was actually merged after that commit, but I assume it was written
beforehand.
If a D-Bus interface was annotated with o.fd.DBus.Deprecated, then the
corresponding GObject property, in the common GInterface implemented
by the generated GDBusObjectProxies and GDBusObjectSkeletons, to
access the generated code for the D-Bus interface was not being marked
with G_PARAM_DEPRECATED, even though the gtk-doc snippet had the
'Deprecated: ' tag.
G_PARAM_DEPRECATED is older than gdbus-codegen, 2.26 and 2.30
respectively, hence it can be used unconditionally.
https://gitlab.gnome.org/GNOME/glib/merge_requests/485
If a D-Bus interface has a property that's annotated with
o.fd.DBus.Deprecated, then the corresponding GObject property was not
being marked with G_PARAM_DEPRECATED, even though the gtk-doc snippet
had the 'Deprecated: ' tag.
G_PARAM_DEPRECATED is older than gdbus-codegen, 2.26 and 2.30
respectively, hence it can be used unconditionally.
https://gitlab.gnome.org/GNOME/glib/merge_requests/485
None of these files starts with a #! line, and they are not native
binary executables, so if a user attempts to execute them as a program,
Unix shells will run them as /bin/sh scripts. This is not going to end
well, since none of them are shell scripts (the gio bash completion
is for bash, which is not a lowest-common-denominator POSIX shell, and
in any case is designed to be sourced rather than executed).
Fixes: #1539
Signed-off-by: Simon McVittie <smcv@collabora.com>
The existing code was generating code with undefined results that modern compilers warn about:
accounts-generated.c:204:23: warning: dereferencing type-punned pointer will break strict-aliasing rules [-Wstrict-aliasing]
(GDBusArgInfo **) &_accounts_accounts_method_info_list_cached_users_OUT_ARG_pointers,
The new python module, added with 0.46, works with Python 2 and 3 and
allows to pass a path for the interpreter to use, if the need arises.
Previously the meson build set PYTHON, used in the shebang line of
the scripts installed by glib, to the full path of the interpreter.
The new meson module doesn't expose that atm, but we should set it to
a executable name anyway, and not a full path.
Several of our tools are installed and are used by other projects to
generate code. However, there is no 'install' when projects use glib
as a subproject.
We need some way for glib to 'provide' these tools so that when some
project uses glib as a subproject, find_program('glib-mkenums') will
transparently return the glib-mkenums we just built.
Starting from Meson 0.46, this can be done with the
`meson.override_find_program()` function.
As a bonus, the Meson GNOME module will also use these
'overriden'/'provided' programs instead of looking for them in PATH.
PEP8 says that:
"Comparisons to singletons like None should always be done with is or
is not, never the equality operators."
glib uses a mix of "== None" and "is None". This patch changes all
cases to the latter.
