msys2-clang64 noticed that the `spacing` variable was written to but
never read from. Indeed, this option has been a no-op since I
accidentally/deliberately broke it in commit
98e6ac788e.
Drop it, because nobody has complained about it breaking since 2022, and
I’m not sure about what the use case for it originally was meant to be.
See https://gitlab.gnome.org/pwithnall/glib/-/jobs/7171235
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
g_type_ensure has a large comment saying _get_type shouldn't be
marked with G_GNUC_CONST because it has side-effects on the first
run, but it's OK if you consistently call g_type_ensure first.
Unfortunately, this isn't accurate. GCC trunk (observed at r17-1725-ge259a182e1f100)
now analyses points-to information more effectively and propagates its
findings, so it sees the function modifies some global state, concludes
that can't be possible (because of the const attribute), and deletes
the stores.
pure unfortunately is unsuitable for *_get_type too as it has a side-effect
(writes to global memory).
Mesa had a similar issue which I fixed recently [0]. glib and glibmm likely
want the (not-yet-implemented) 'idempotent' attribute instead [1]. In fact,
this exact problem is what motivated that request! :)
ebassi mentions an alternative to the current setup as well, using
atomics [2].
This problem has gone back many years but the compiler has finally
fully outsmarted us here, so give in.
[0] https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/42361
[1] https://gcc.gnu.org/PR32911
[2] https://gitlab.gnome.org/GNOME/glib/-/merge_requests/4249#note_2583110
Fixes: https://gitlab.gnome.org/GNOME/glib/-/work_items/3984
Signed-off-by: Sam James <sam@gentoo.org>
The description of the distinction between default and user signal
handlers leaves it a bit unclear whether any signal handler connected
within the class implementation can actually be a default signal
handler. The term "object method handler" is ambiguous, because all
signal handlers are bound to an object, but the default signal handler
is bound to the class.
We should also link the GSignalFlags values, now that we can point to
specific enumeration values.
These rules are not new, they’ve been around for a long time and are
needed to allow introspection machinery to be able to work reliably and
deterministically.
Unfortunately, they have not been documented canonically in one place
before.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
The `gi-docgen` tool is not designed to be used like that. In
particular, when nesting documentation directories, the generated
`*.devhelp2` files (needed by Devhelp to show the documentation) are
nested one directory level too deep for Devhelp to find them, and hence
are useless, and the documentation doesn’t show up in this common
documentation viewer.
So, change the installed documentation directory hierarchy:
* `${PREFIX}/share/doc/glib-2.0/gio` → `${PREFIX}/share/doc/gio-2.0`
* `${PREFIX}/share/doc/glib-2.0/glib-unix` →
`${PREFIX}/share/doc/glib-unix-2.0`
* `${PREFIX}/share/doc/glib-2.0/gobject` →
`${PREFIX}/share/doc/gobject-2.0`
* etc.
* `${PREFIX}/share/doc/glib-2.0/glib` → `${PREFIX}/share/doc/glib-2.0`
This is going to seem like pointless churn (the contents of the
documentation have not changed), and packagers may mourn the split of
content in `/usr/share/doc` from `/usr/share/doc/${package_name}` to
`/usr/share/doc/${pkg_config_id}` instead, but that seems to be the best
approach to fix this issue in GLib. gi-docgen’s behaviour does feel
fairly consistent and correct with the rest of how it works (single
output directory).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Fixes: #3287
This is nowhere near a complete check-through and gi-docgenification of
the signals docs, just a few bits I was looking at anyway.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
Seems no point in keeping them separate. It doesn’t seem to matter if
they contain entries which are unused for a particular docs build.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Now that the reference documentation uses gi-docgen, it's more
troublesome to generate in less standard build scenarios like
cross-compiling.
In distributions like Debian, reference documentation is generally
packaged separately (in libglib2.0-doc in Debian's case), but man pages
are generally packaged alongside the executables themselves (in the
libglib2.0-bin and libglib2.0-dev-bin packages, in Debian's case). We
can exclude the reference documentation when cross-compiling, but ideally
we would like the man pages to still be built, so that a cross-compiled
libglib2.0-bin or libglib2.0-dev-bin package has the same content as a
native build.
Signed-off-by: Simon McVittie <smcv@debian.org>
They are now installed to (e.g.)
`${prefix}/share/doc/glib-2.0/{glib,gmodule,gobject,gio}/index.html`.
We might want to drop one level of nesting out of that, but for the
moment I thought I’d keep it in so we can disambiguate by installed
major version.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.
This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
The GIR files are now built by GLib itself, so they will be in the build
directories of each sub-library, except for GLib-2.0 which is built
alongside GObject-2.0.
On CHERI-enabled systems we use uintptr_t as the underlying storage for
GType and therefore casting to gsize strips the upper bits from a pointer.
Fix this by casting via uintptr_t instead and introduce a new set of
macros to convert between GType and pointers.
It needs to be in a separate page because it’s all macros and they have
no type/class associated with them.
Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>
Helps: #3037
Gate the API reference on the availability of the introspection data as
well, so we don't accidentally try and generate the documentation
without a description of our API.
As we start moving documentation over from gtk-doc to gi-docgen, the
gtk-doc coverage is going to go down and things are going to start
breaking. That’s OK; we don’t need to test it any more.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #3037
The files here are copied from the docs-gtk-org
branch of gtk.
This adds gi-docgen to the CI Dockerfiles and ensures the new versions
(including the OS upgrades from the previous commit) are used during CI.
Helps: #3037
The introspection scanner cannot deal very well with function pointers
into a plain structure. In order to document the various function
pointers in GTypeValueTable we need to create typed callbacks, and
use them to replace the anonymous function pointers inside the
structure. This not only allows us to properly document the function
pointers, but it also allows us to annotate the arguments and return
value of those function pointers.
See also: https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/400#note_1721707
GTK lost it's '+' suffix back in 2019, according to
<https://mail.gnome.org/archives/gtk-devel-list/2019-February/msg00000.html>
This commit can be re-generated with:
git grep -l GTK+ \
| grep -v -e ^NEWS -e ^glib/tests/collate.c \
| xargs sed -i 's/GTK+/GTK/g'
Most of the changes are in comments and documentation.
The documentation previously implicitly said in a few places that
interfaces are classed, but reading through the implementation of
`GType`, I don’t think they are. If they were, the registration of the
fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify
`G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`.
I think this makes sense, because you can’t subclass an interface.
Subclassing is a key property of being classed.
Tweak the `GType` tutorial to remove that implicit statement, and expand
the documentation for `G_TYPE_IS_CLASSED`.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #252
