Move it to a separate documentation file, since most of what’s covered
isn’t introspectable.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so the difference between `g_rand_*()` and
`g_random_*()` can be explained.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so more detail can be provided about all the
groups of API.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page so an overview of the deprecated threading
API can be given.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
This is a variant of `g_test_trap_subprocess()` which allows the
environment for the child process to be specified. This is quite useful
when you want to test code which reads environment variables, as it’s
not safe to set those after the start of `main()`.
This will be useful within and outwith GLib for testing such code.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #1618
Move it to a separate page, since it doesn’t quite make sense to
incorporate into the `GDBusConnection` docs.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate page, as there isn’t a `GIOScheduler` struct.
Ensure that all its functions/methods/types are correctly marked as
deprecated. Fix a few broken links about I/O priority which pointed to
it.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Move it to a separate content page as there is no `GDBusIntrospection`
type to hang the rest of the documentation off.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Adding it all to the docs for the `GDBusError` enum seemed a bit much,
so I moved it to its own content page.
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 there isn’t actually a
`GFileAttribute` type.
Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>
Helps: #3037
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.
g_strv_builder_take() allows to transfer ownership of the passed in
string.
This can be useful to avoid additional allocations when using functions
that transfer ownership to the caller like g_strdup_printf().
The testcase uses g_strv_builder_take and g_strv_builder_add to demo
that calls can be mixed.
This copies the test code inline into the Markdown, which means it could
diverge from the test code which is compiled and run as part of the
tests. That needs improving, but that can happen in a subsequent commit.
Helps: #3037
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
We can't easily use g_autofd with g_unix_open_pipe, because its
parameter is an array of two fds that both need closing. Add an inline
convenience wrapper providing the obvious semantics.
Signed-off-by: Simon McVittie <smcv@collabora.com>
I'm not aware of any platforms where this is a problem in practice, but
it's definitely nonportable and doesn't hurt to document it.
I wonder about CHERI....
These functions can be used to initalize pointer-type variables rather
than a gsize. This is required to support CHERI-enabled platforms where
gsize cannot be used to store pointers. Follow-up changes will migrate
the uses of g_once_init that store pointers to the new API
Helps: https://gitlab.gnome.org/GNOME/glib/-/issues/2842
The `GTK_USE_PORTAL` environment variable has started to be misused by
users, which is causing deployment issues (such as portal services
themselves ending up being forced to use portals, which is never going
to work).
Try and sidestep users’ broken configurations by renaming the
environment variable, and also separating it from the old GTK
environment variable, since the GLib one affects a lot more processes.
This environment variable is meant to be used for
debugging and development, and never in production.
GTK already renamed their environment variable in
https://gitlab.gnome.org/GNOME/gtk/-/merge_requests/4829, so keeping the
`GTK_USE_PORTAL` name in GLib doesn’t make sense anyway.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #3107
This reverts commit 252bbcd207.
After further discussion in !3511, we’ve decided that there are risks
associated with this change, and it’s not the best way of addressing the
original problem.
The original motivation for the change turned out to be that
`-mms-bitfields` was not handled by `windres`, which was receiving it
from `pkg-config --cflags glib-2.0` in some projects. However, if
`windres` is claiming to accept CFLAGS then it should accept (and
ignore) `-mms-bitfields`, since the `-m` family of options are defined
in `man gcc`, just like `-I`, `-D`, etc.
There is some question that there might still be third party projects
which are built with an old enough compiler that `-mms-bitfields` is not
the compiler default. For that reason, we should either still continue
to specify `-mms-bitfields` in the `.pc` file, or add a test to assert
that third party projects are always compiled with `-mms-bitfields` set.
But adding a new test for all third-party compilations is risky (if we
get it wrong, things will break; and it’s a test which may behave
differently on different platforms), so it seems safer to just keep
`-mms-bitfields` in `.pc` for now.
Once all compilers which we require specify `-mms-bitfields` by default,
we can finally drop this flag (without adding a test for third-party
compilations).
See: https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3511
This documents the practices that I’ve been trying to follow for the
last few years for managing GLib issues and merge requests, and why they
seem to work well enough.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
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
Since we have a convenience method to add actions let's allow to remove
them just as easily. This makes resource cleanup as simple as initially
adding the entries.
Adds a helper to truncate UTF8 strings in the middle, allowing to make
them fit certain size constraints.
This function is modeled after similar functionality that has existed
since 2008 in nautilus and in eel before that.
It’s a bit confusing to have two files called `README`, especially given
that `README.win32.md` only contains build instructions and none of the
other overview/contribution/bug reporting information that `README.md`
contains.
It feels like these would be better organised by having one top-level
`README.md`, and pointing to the Windows build instructions from there.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
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.
While x86_64 has enough precision in long double to do a round trip
from guint64 to long double and back, this is platform-specific, and
is a disservice to users trying to debug failing unit tests on other
architectures where it loses precision for g_assert_cmp{int,uint,hex}.
See also https://bugzilla.gnome.org/show_bug.cgi?id=788385 which
mentions having to add casts to specifically silence the compiler on
platforms where the precision loss occurs.
Meanwhile, g_assert_cmpuint() does an unsigned comparison, but outputs
signed values if the comparison fails, which is confusing.
Fix both issues by introducing a new g_assertion_message_cmpint()
function with a new 'u' numtype. For backwards compatibility, the
macros still call into the older g_assertion_message_cmpnum() when not
targetting 2.78, and that function still works when passed 'i' and 'x'
types even though code compiled for 2.78 and later will never invoke
it with numtype anything other than 'f'. Note that g_assert_cmpmem
can also take advantage of the new code, even though in practice,
comparison between two size_t values representing array lengths that
can actually be compiled is unlikely to have ever hit the precision
loss. The macros in signals.c test code does not have to worry about
versioning, since it is not part of the glib library proper.
Closes#2997
Signed-off-by: Eric Blake <eblake@redhat.com>
I’ve finally found the right place in the docs to put this stuff.
This doesn’t auto-link this section from every string in the GLib
documentation, but I think that at this point (with gtk-doc in
maintenance mode, and gi-docgen not fully applied to GLib) I don’t think
we can do any better. The perfect is the enemy of the good, and having
this stuff documented somewhere means that someone can link to it from
multiple places in future *somehow*.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #116
By default, if a host environment has the `rst2html5` application
available, builds will automatically perform some HTML documentation
generation from the documentation's glib reference content (e.g.
creating `gvariant-specification-1.0.html`). The creation of this
documentation is not required for all use cases.
This commit tweaks the building of the HTML-based GLIB specification
document to be guarded by `gtk_doc`.
Signed-off-by: James Knight <james.d.knight@live.com>
Most of the document was about traps, which have not existed since
commit 58cdf0b474, 10 years ago.
The rest of the document was about `GOBJECT_DEBUG`, and that information
would be more easily findable in the full GObject documentation — so
move it there and update it a bit.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Without a timeout, some lookup requests can go on forever, typically due
to bugs in underlying systems.
This can have particularly significant effects on the Happy Eyeballs
algorithm in `GSocketClient`, which relies on multiple name lookups as
its first step.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #2866
We need a way to initialise refcounted types placed in static storage,
or on the stack. Using proper macros avoids knowing the magic constant
used for grefcount and gatomicrefcount.
