From e58abedf28ef1c77512ae1a0d84261cf42b5ffb9 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 2 Feb 2024 14:39:46 +0000 Subject: [PATCH 01/13] Revert "gwin32: Un-hide symbols when building GIR" This reverts commit 50d432c77b07574e16d0bf8ba0de93819e5f92a3. The platform-specific headers of GLib and Gio are now introspected separately, so the documentation for them can be built separately, and this workaround is no longer needed. Helps: #3037 --- glib/gwin32.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/glib/gwin32.h b/glib/gwin32.h index a44c4c8ca..e38a7f90a 100644 --- a/glib/gwin32.h +++ b/glib/gwin32.h @@ -33,7 +33,7 @@ #include -#if defined(G_PLATFORM_WIN32) || defined(__GI_SCANNER__) +#ifdef G_PLATFORM_WIN32 G_BEGIN_DECLS @@ -41,7 +41,7 @@ G_BEGIN_DECLS #define MAXPATHLEN 1024 #endif -#if defined(G_OS_WIN32) || defined(__GI_SCANNER__) +#ifdef G_OS_WIN32 /* * To get prototypes for the following POSIXish functions, you have to @@ -68,7 +68,7 @@ G_BEGIN_DECLS GLIB_AVAILABLE_IN_ALL gint g_win32_ftruncate (gint f, guint size); -#endif /* G_OS_WIN32 || __GI_SCANNER__ */ +#endif /* G_OS_WIN32 */ /* The MS setlocale uses locale names of the form "English_United * States.1252" etc. We want the Unixish standard form "en", "zh_TW" @@ -137,6 +137,6 @@ gboolean g_win32_check_windows_version (const gint major, G_END_DECLS -#endif /* G_PLATFORM_WIN32 || __GI_SCANNER__ */ +#endif /* G_PLATFORM_WIN32 */ #endif /* __G_WIN32_H__ */ From 3695249ebb3195357ead7d2cab602d8e999d5cf4 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:37:51 +0000 Subject: [PATCH 02/13] docs: Drop unnecessary GdkPixbuf reference from urlmap.js It was unused. Signed-off-by: Philip Withnall --- docs/reference/gio/urlmap.js | 1 - docs/reference/girepository/urlmap.js | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/reference/gio/urlmap.js b/docs/reference/gio/urlmap.js index 32243001c..b1f0962b0 100644 --- a/docs/reference/gio/urlmap.js +++ b/docs/reference/gio/urlmap.js @@ -1,7 +1,6 @@ // SPDX-License-Identifier: LGPL-2.1-or-later // SPDX-FileCopyrightText: 2023 Matthias Clasen var baseURLs = [ - [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ], [ 'GLib', 'https://docs.gtk.org/glib/' ], [ 'GModule', 'https://docs.gtk.org/gmodule/' ], [ 'GObject', 'https://docs.gtk.org/gobject/' ], diff --git a/docs/reference/girepository/urlmap.js b/docs/reference/girepository/urlmap.js index 32243001c..b1f0962b0 100644 --- a/docs/reference/girepository/urlmap.js +++ b/docs/reference/girepository/urlmap.js @@ -1,7 +1,6 @@ // SPDX-License-Identifier: LGPL-2.1-or-later // SPDX-FileCopyrightText: 2023 Matthias Clasen var baseURLs = [ - [ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ], [ 'GLib', 'https://docs.gtk.org/glib/' ], [ 'GModule', 'https://docs.gtk.org/gmodule/' ], [ 'GObject', 'https://docs.gtk.org/gobject/' ], From 4c178fa6230e9ee09ab97d0f0398672e84b20926 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:39:50 +0000 Subject: [PATCH 03/13] build: Combine duplicate urlmap.js files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/reference/gio/gio.toml.in | 2 +- docs/reference/girepository/girepository.toml.in | 2 +- docs/reference/girepository/urlmap.js | 9 --------- docs/reference/glib/glib.toml.in | 2 +- docs/reference/glib/urlmap.js | 9 --------- docs/reference/gmodule/gmodule.toml.in | 2 +- docs/reference/gmodule/urlmap.js | 9 --------- docs/reference/gobject/gobject.toml.in | 2 +- docs/reference/gobject/urlmap.js | 9 --------- docs/reference/{gio => }/urlmap.js | 0 10 files changed, 5 insertions(+), 41 deletions(-) delete mode 100644 docs/reference/girepository/urlmap.js delete mode 100644 docs/reference/glib/urlmap.js delete mode 100644 docs/reference/gmodule/urlmap.js delete mode 100644 docs/reference/gobject/urlmap.js rename docs/reference/{gio => }/urlmap.js (100%) diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in index 40559fabb..0d846eedc 100644 --- a/docs/reference/gio/gio.toml.in +++ b/docs/reference/gio/gio.toml.in @@ -37,7 +37,7 @@ show_index_summary = true show_class_hierarchy = true [extra] -urlmap_file = "urlmap.js" +urlmap_file = "../urlmap.js" # The same order will be used when generating the index content_files = [ "overview.md", diff --git a/docs/reference/girepository/girepository.toml.in b/docs/reference/girepository/girepository.toml.in index 2ff8f1e12..4c16c11d2 100644 --- a/docs/reference/girepository/girepository.toml.in +++ b/docs/reference/girepository/girepository.toml.in @@ -42,7 +42,7 @@ show_index_summary = true show_class_hierarchy = true [extra] -urlmap_file = "urlmap.js" +urlmap_file = "../urlmap.js" # The same order will be used when generating the index content_files = [ "migrating-gi.md", diff --git a/docs/reference/girepository/urlmap.js b/docs/reference/girepository/urlmap.js deleted file mode 100644 index b1f0962b0..000000000 --- a/docs/reference/girepository/urlmap.js +++ /dev/null @@ -1,9 +0,0 @@ -// SPDX-License-Identifier: LGPL-2.1-or-later -// SPDX-FileCopyrightText: 2023 Matthias Clasen -var baseURLs = [ - [ 'GLib', 'https://docs.gtk.org/glib/' ], - [ 'GModule', 'https://docs.gtk.org/gmodule/' ], - [ 'GObject', 'https://docs.gtk.org/gobject/' ], - [ 'Gio', 'https://docs.gtk.org/gio/' ], - [ 'Gtk', 'https://docs.gtk.org/gtk4/' ], -]; diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 96914790c..5eacf24e4 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -37,7 +37,7 @@ show_index_summary = true show_class_hierarchy = true [extra] -urlmap_file = "urlmap.js" +urlmap_file = "../urlmap.js" # The same order will be used when generating the index content_files = [ "building.md", diff --git a/docs/reference/glib/urlmap.js b/docs/reference/glib/urlmap.js deleted file mode 100644 index b1f0962b0..000000000 --- a/docs/reference/glib/urlmap.js +++ /dev/null @@ -1,9 +0,0 @@ -// SPDX-License-Identifier: LGPL-2.1-or-later -// SPDX-FileCopyrightText: 2023 Matthias Clasen -var baseURLs = [ - [ 'GLib', 'https://docs.gtk.org/glib/' ], - [ 'GModule', 'https://docs.gtk.org/gmodule/' ], - [ 'GObject', 'https://docs.gtk.org/gobject/' ], - [ 'Gio', 'https://docs.gtk.org/gio/' ], - [ 'Gtk', 'https://docs.gtk.org/gtk4/' ], -]; diff --git a/docs/reference/gmodule/gmodule.toml.in b/docs/reference/gmodule/gmodule.toml.in index 46f1efd1d..20a0a9dd6 100644 --- a/docs/reference/gmodule/gmodule.toml.in +++ b/docs/reference/gmodule/gmodule.toml.in @@ -40,7 +40,7 @@ show_class_hierarchy = true base_url = "https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/" [extra] -urlmap_file = "urlmap.js" +urlmap_file = "../urlmap.js" # The same order will be used when generating the index content_files = [ "modules.md", diff --git a/docs/reference/gmodule/urlmap.js b/docs/reference/gmodule/urlmap.js deleted file mode 100644 index b1f0962b0..000000000 --- a/docs/reference/gmodule/urlmap.js +++ /dev/null @@ -1,9 +0,0 @@ -// SPDX-License-Identifier: LGPL-2.1-or-later -// SPDX-FileCopyrightText: 2023 Matthias Clasen -var baseURLs = [ - [ 'GLib', 'https://docs.gtk.org/glib/' ], - [ 'GModule', 'https://docs.gtk.org/gmodule/' ], - [ 'GObject', 'https://docs.gtk.org/gobject/' ], - [ 'Gio', 'https://docs.gtk.org/gio/' ], - [ 'Gtk', 'https://docs.gtk.org/gtk4/' ], -]; diff --git a/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in index de39bc489..8c2667244 100644 --- a/docs/reference/gobject/gobject.toml.in +++ b/docs/reference/gobject/gobject.toml.in @@ -39,7 +39,7 @@ show_index_summary = true show_class_hierarchy = true [extra] -urlmap_file = "urlmap.js" +urlmap_file = "../urlmap.js" # The same order will be used when generating the index content_files = [ "concepts.md", diff --git a/docs/reference/gobject/urlmap.js b/docs/reference/gobject/urlmap.js deleted file mode 100644 index b1f0962b0..000000000 --- a/docs/reference/gobject/urlmap.js +++ /dev/null @@ -1,9 +0,0 @@ -// SPDX-License-Identifier: LGPL-2.1-or-later -// SPDX-FileCopyrightText: 2023 Matthias Clasen -var baseURLs = [ - [ 'GLib', 'https://docs.gtk.org/glib/' ], - [ 'GModule', 'https://docs.gtk.org/gmodule/' ], - [ 'GObject', 'https://docs.gtk.org/gobject/' ], - [ 'Gio', 'https://docs.gtk.org/gio/' ], - [ 'Gtk', 'https://docs.gtk.org/gtk4/' ], -]; diff --git a/docs/reference/gio/urlmap.js b/docs/reference/urlmap.js similarity index 100% rename from docs/reference/gio/urlmap.js rename to docs/reference/urlmap.js From f63cc38328c586930ea1b198fb0756bffbcdca6a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:23:02 +0000 Subject: [PATCH 04/13] gfiledescriptorbased: Move across typedef from giotypes.h MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `GFileDescriptorBased` is in `gio-unix-2.0` rather than `gio-2.0`, so its types shouldn’t be declared in a header belonging to the latter. This hasn’t been a problem previously because C is fine with that. But upcoming commits are going to split the introspection scanning for `gio-2.0` and `gio-unix-2.0`, and the introspection scanner is a little more picky about declarations not being spread all over the place. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gfiledescriptorbased.h | 5 +++-- gio/giotypes.h | 1 - 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/gio/gfiledescriptorbased.h b/gio/gfiledescriptorbased.h index a512feb50..7c7c78afb 100644 --- a/gio/gfiledescriptorbased.h +++ b/gio/gfiledescriptorbased.h @@ -27,14 +27,15 @@ G_BEGIN_DECLS +typedef struct _GFileDescriptorBased GFileDescriptorBased; +typedef struct _GFileDescriptorBasedIface GFileDescriptorBasedIface; + #define G_TYPE_FILE_DESCRIPTOR_BASED (g_file_descriptor_based_get_type ()) #define G_FILE_DESCRIPTOR_BASED(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_FILE_DESCRIPTOR_BASED, GFileDescriptorBased)) #define G_IS_FILE_DESCRIPTOR_BASED(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE_DESCRIPTOR_BASED)) #define G_FILE_DESCRIPTOR_BASED_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE_DESCRIPTOR_BASED, GFileDescriptorBasedIface)) G_DEFINE_AUTOPTR_CLEANUP_FUNC(GFileDescriptorBased, g_object_unref) -typedef struct _GFileDescriptorBasedIface GFileDescriptorBasedIface; - /** * GFileDescriptorBasedIface: * @g_iface: The parent interface. diff --git a/gio/giotypes.h b/gio/giotypes.h index c2c09d16d..98143ba93 100644 --- a/gio/giotypes.h +++ b/gio/giotypes.h @@ -82,7 +82,6 @@ typedef struct _GFileInfo GFileInfo; typedef struct _GFileAttributeMatcher GFileAttributeMatcher; typedef struct _GFileAttributeInfo GFileAttributeInfo; typedef struct _GFileAttributeInfoList GFileAttributeInfoList; -typedef struct _GFileDescriptorBased GFileDescriptorBased; typedef struct _GFileInputStream GFileInputStream; typedef struct _GFileOutputStream GFileOutputStream; typedef struct _GFileIOStream GFileIOStream; From 0d9170c6b8b4192d9208d0d2a82bc732b42f52a3 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:25:16 +0000 Subject: [PATCH 05/13] gio: Remove unnecessary appinfo_sources variable There was no obvious logical need to list the `GAppInfo` subclass sources separately in the build. It makes more sense to add them to the platform-specific source lists, since they are platform specific. This will be used in an upcoming commit which generates platform-specific GIR files, so needs the full platform-specific lists of sources. Signed-off-by: Philip Withnall Helps: #3037 --- gio/meson.build | 8 +++----- girepository/introspection/meson.build | 1 - 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/gio/meson.build b/gio/meson.build index 39d2f4d15..59c2b0fc0 100644 --- a/gio/meson.build +++ b/gio/meson.build @@ -341,7 +341,6 @@ local_sources = files( platform_deps = [] internal_deps = [] -appinfo_sources = [] contenttype_sources = [] portal_sources = [] unix_sources = [] @@ -394,7 +393,7 @@ if host_system != 'windows' if glib_have_cocoa settings_sources += files('gnextstepsettingsbackend.m') contenttype_sources += files('gosxcontenttype.m') - appinfo_sources += files('gosxappinfo.m') + unix_sources += files('gosxappinfo.m') framework_dep = dependency('appleframeworks', modules : ['Foundation', 'CoreFoundation', 'AppKit']) platform_deps += [framework_dep] if glib_have_os_x_9_or_later @@ -403,7 +402,7 @@ if host_system != 'windows' application_headers += files('gosxappinfo.h') else contenttype_sources += files('gcontenttype.c') - appinfo_sources += files('gdesktopappinfo.c') + unix_sources += files('gdesktopappinfo.c') gio_unix_include_headers += files('gdesktopappinfo.h') launch_desktop_sources = files('gio-launch-desktop.c') @@ -433,7 +432,7 @@ if host_system != 'windows' ) endif else - appinfo_sources += files('gwin32appinfo.c') + win32_sources += files('gwin32appinfo.c') contenttype_sources += files('gcontenttype-win32.c') platform_deps += [cc.find_library('shlwapi'), cc.find_library('dnsapi'), @@ -613,7 +612,6 @@ if glib_build_shared gio_sources += files ('../glib/gtrace.c') endif -gio_sources += appinfo_sources gio_sources += contenttype_sources gio_sources += gdbus_daemon_sources gio_sources += unix_sources diff --git a/girepository/introspection/meson.build b/girepository/introspection/meson.build index 126993659..dc5495296 100644 --- a/girepository/introspection/meson.build +++ b/girepository/introspection/meson.build @@ -111,7 +111,6 @@ gio_gir_sources = [ gio_base_sources, application_sources, gdbus_sources, - appinfo_sources, contenttype_sources, unix_sources, win32_sources, From 1f9e44d6232c3e96caa8a96d9b1cc2c65cf5848c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:26:57 +0000 Subject: [PATCH 06/13] glib: Install platform specific headers in a separate step Maintain them in separate lists within `meson.build`. This makes no functional difference at the moment, but will be used in an upcoming commit to generate separate GIR files per platform. Signed-off-by: Philip Withnall Helps: #3037 --- glib/meson.build | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/glib/meson.build b/glib/meson.build index 077a81f55..d2efebadc 100644 --- a/glib/meson.build +++ b/glib/meson.build @@ -147,15 +147,11 @@ glib_headers = files( 'glib.h', 'glib-object.h', ) -if host_system != 'windows' - glib_headers += files('glib-unix.h') -endif install_headers(glib_headers, install_dir : glib_includedir) if host_system != 'windows' - # Expose as variable to be used by gobject-introspection - # when it includes GLib as a subproject - glib_unix_h = files('glib-unix.h') + glib_unix_headers = files('glib-unix.h') + install_headers(glib_unix_headers, install_dir : glib_includedir) endif if host_system == 'windows' @@ -251,12 +247,16 @@ glib_sub_headers = files( 'gvarianttype.h', 'gvariant.h', 'gversion.h', - 'gwin32.h', 'gprintf.h', ) install_headers(glib_sub_headers, install_dir : glib_sub_includedir) +if host_system == 'windows' + glib_win32_headers = files('gwin32.h') + install_headers(glib_win32_headers, install_dir : glib_sub_includedir) +endif + glib_deprecated_sources = files( 'deprecated/gallocator.c', 'deprecated/gcache.c', From 5021d002abe55e4d09e7e83b3ffe3a8cf1a074ac Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:29:30 +0000 Subject: [PATCH 07/13] introspection: Generate separate GIR files for platform specific APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For both GLib and GIO. (GObject, GIRepository and GModule don’t have any platform specific APIs.) This is needed for two reasons: * If the same GIR file is shipped on multiple platforms, it has no way to conditionally define/not-define an API based on the platform (like an `#ifdef` in a C header). So we either end up shipping differing GIR APIs on different platforms, or shipping a GIR file which declares APIs which aren’t resolvable by `dlopen()` on certain platforms, and will cause a language runtime error. * The API reference documentation is now generated from the GIR, and similar problems are present there: if the GIR contains different symbols depending on the platform, there is no way to generate API documentation for the union of all of them. The fix is to ensure that there are no conditional symbols in a GIR, by splitting out the platform specific symbols into platform specific GIR files. Platform specific documentation can then be generated from these, in addition to the main, platform agnostic, documentation. The documentation changes will following in a subsequent commit. Signed-off-by: Philip Withnall Helps: #3037 --- girepository/introspection/meson.build | 126 +++++++++++++++++++++---- 1 file changed, 107 insertions(+), 19 deletions(-) diff --git a/girepository/introspection/meson.build b/girepository/introspection/meson.build index dc5495296..d96f19f60 100644 --- a/girepository/introspection/meson.build +++ b/girepository/introspection/meson.build @@ -49,6 +49,61 @@ glib_gir = gnome.generate_gir(libglib, ], ) +if host_system == 'windows' + glib_win32_gir = gnome.generate_gir(libglib, + sources: [ + gi_gen_shared_sources, + glib_win32_headers, + ], + namespace: 'GLibWin32', + nsversion: '2.0', + identifier_prefix: gi_identifier_prefix, + symbol_prefix: gi_symbol_prefix, + export_packages: 'glib-2.0', + header: 'glib.h', + includes: [ glib_gir[0] ], + install: true, + dependencies: [ + libgobject_dep, + ], + env: gi_gen_env_variables, + extra_args: gir_args + [ + '-DGLIB_COMPILATION', + '-DGETTEXT_PACKAGE="dummy"', + '--symbol-prefix=glib', + '--library-path=' + meson.current_build_dir(), + '--library=gobject-2.0', + ], + ) +else + glib_unix_gir = gnome.generate_gir(libglib, + sources: [ + gi_gen_shared_sources, + glib_unix_headers, + ], + namespace: 'GLibUnix', + nsversion: '2.0', + identifier_prefix: gi_identifier_prefix, + symbol_prefix: gi_symbol_prefix, + export_packages: 'glib-2.0', + header: 'glib.h', + includes: [ glib_gir[0] ], + install: true, + dependencies: [ + libgobject_dep, + ], + env: gi_gen_env_variables, + extra_args: gir_args + [ + '-DGLIB_COMPILATION', + '-DGETTEXT_PACKAGE="dummy"', + '--symbol-prefix=glib', + '--library-path=' + meson.current_build_dir(), + '--library=gobject-2.0', + '--c-include=glib-unix.h', + ], + ) +endif + # GObject gobject_gir = gnome.generate_gir(libgobject, sources: [ @@ -112,31 +167,13 @@ gio_gir_sources = [ application_sources, gdbus_sources, contenttype_sources, - unix_sources, - win32_sources, settings_sources, ] -gio_gir_packages = [ 'gio-2.0' ] gio_gir_args = [ '-DGIO_COMPILATION', '-DG_SETTINGS_ENABLE_BACKEND', '--symbol-prefix=gio', ] -if host_system == 'windows' - gio_gir_sources += gio_win32_include_headers - foreach h: gio_win32_include_headers - gio_gir_args += '--c-include=@0@'.format(h) - endforeach - gio_gir_packages += 'gio-win32-2.0' - gio_gir_args += '--pkg=gio-win32-2.0' -else - gio_gir_sources += gio_unix_include_headers - foreach h: gio_unix_include_headers - gio_gir_args += '--c-include=@0@'.format(h) - endforeach - gio_gir_packages += 'gio-unix-2.0' - gio_gir_args += '--pkg=gio-unix-2.0' -endif gio_gir = gnome.generate_gir(libgio, sources: gio_gir_sources, @@ -144,7 +181,7 @@ gio_gir = gnome.generate_gir(libgio, nsversion: '2.0', identifier_prefix: gi_identifier_prefix, symbol_prefix: gi_symbol_prefix, - export_packages: gio_gir_packages, + export_packages: [ 'gio-2.0' ], header: 'gio/gio.h', includes: [ glib_gir[0], gmodule_gir[0], gobject_gir[0] ], install: true, @@ -157,6 +194,57 @@ gio_gir = gnome.generate_gir(libgio, extra_args: gir_args + gio_gir_args, ) +if host_system == 'windows' + gio_win32_gir_c_includes = [] + foreach h: gio_win32_include_headers + gio_win32_gir_c_includes += '--c-include=@0@'.format(h) + endforeach + + gio_win32_gir = gnome.generate_gir(libgio, + sources: gio_win32_include_headers + win32_sources, + namespace: 'GioWin32', + nsversion: '2.0', + identifier_prefix: gi_identifier_prefix, + symbol_prefix: gi_symbol_prefix, + export_packages: [ 'gio-win32-2.0' ], + header: 'gio/gio.h', + includes: [ glib_gir[0], gmodule_gir[0], gobject_gir[0], gio_gir[0] ], + install: true, + dependencies: [ + libglib_dep, + libgobject_dep, + libgmodule_dep, + ], + env: gi_gen_env_variables, + extra_args: gir_args + gio_gir_args + [ '--pkg=gio-win32-2.0' ] + gio_win32_gir_c_includes, + ) +else + gio_unix_gir_c_includes = [] + foreach h: gio_unix_include_headers + gio_unix_gir_c_includes += '--c-include=@0@'.format(h) + endforeach + + gio_unix_gir = gnome.generate_gir(libgio, + sources: gio_unix_include_headers + unix_sources, + namespace: 'GioUnix', + nsversion: '2.0', + identifier_prefix: gi_identifier_prefix, + symbol_prefix: gi_symbol_prefix, + export_packages: [ 'gio-unix-2.0' ], + header: 'gio/gio.h', + includes: [ glib_gir[0], gmodule_gir[0], gobject_gir[0], gio_gir[0] ], + install: true, + dependencies: [ + libglib_dep, + libgobject_dep, + libgmodule_dep, + ], + env: gi_gen_env_variables, + extra_args: gir_args + gio_gir_args + [ '--pkg=gio-unix-2.0' ] + gio_unix_gir_c_includes, + ) +endif + +# GIRepository libgirepository_gir_sources = [ gi_visibility_h, girepo_headers, From c498c9a8c911739bcca05ae8cd8c2e1984b866a0 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:36:14 +0000 Subject: [PATCH 08/13] docs: Split out platform specific GIO and GLib documentation This creates `GioUnix`, `GioWin32`, `GLibUnix` and `GLibWin32`. These bodies of documentation are in addition to the main, platform agnostic, documentation for both libraries. This commit necessarily includes various mechanical changes to update the repository namespace used in various existing documentation links to platform specific APIs. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/gio/gio-unix.toml.in | 50 +++++++++++++++++++++++++ docs/reference/gio/gio-win32.toml.in | 48 ++++++++++++++++++++++++ docs/reference/gio/gio.toml.in | 1 - docs/reference/gio/meson.build | 47 ++++++++++++++++++++++++ docs/reference/gio/migrating-posix.md | 22 ++++++----- docs/reference/gio/unix-mounts.md | 26 ++++++------- docs/reference/glib/glib-unix.toml.in | 51 ++++++++++++++++++++++++++ docs/reference/glib/glib-win32.toml.in | 51 ++++++++++++++++++++++++++ docs/reference/glib/glib.toml.in | 2 - docs/reference/glib/meson.build | 50 ++++++++++++++++++++++++- docs/reference/glib/unix.md | 20 +++++----- docs/reference/glib/windows.md | 26 ++++++------- docs/reference/urlmap.js | 4 ++ gio/gappinfo.c | 14 ++++--- gio/gsimpleiostream.c | 4 +- gio/gunixfdlist.c | 3 +- 16 files changed, 363 insertions(+), 56 deletions(-) create mode 100644 docs/reference/gio/gio-unix.toml.in create mode 100644 docs/reference/gio/gio-win32.toml.in create mode 100644 docs/reference/glib/glib-unix.toml.in create mode 100644 docs/reference/glib/glib-win32.toml.in diff --git a/docs/reference/gio/gio-unix.toml.in b/docs/reference/gio/gio-unix.toml.in new file mode 100644 index 000000000..3a9deb3bd --- /dev/null +++ b/docs/reference/gio/gio-unix.toml.in @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later +# Copyright 2023 Matthias Clasen +# Copyright 2023 Philip Withnall + +[library] +name = "GioUnix" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/glib/" +repository_url = "https://gitlab.gnome.org/GNOME/glib.git" +website_url = "https://www.gtk.org" +docs_urls = "https://docs.gtk.org/gio-unix/" +authors = "GLib Development Team" +license = "LGPL-2.1-or-later" +description = "Unix-specific APIs in Gio" +dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GLib-2.0"] + name = "GLib" + description = "The base utility library" + docs_url = "https://docs.gtk.org/glib/" + + [dependencies."GModule-2.0"] + name = "GModule" + description = "Portable API for dynamically loading modules" + docs_url = "https://docs.gtk.org/gmodule/" + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "A library of useful classes for I/O, networking and IPC" + docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[extra] +urlmap_file = "../urlmap.js" +# The same order will be used when generating the index +content_files = [ + "unix-mounts.md", +] +content_images = [] diff --git a/docs/reference/gio/gio-win32.toml.in b/docs/reference/gio/gio-win32.toml.in new file mode 100644 index 000000000..84e75ce7c --- /dev/null +++ b/docs/reference/gio/gio-win32.toml.in @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later +# Copyright 2023 Matthias Clasen +# Copyright 2023 Philip Withnall + +[library] +name = "GioWin32" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/glib/" +repository_url = "https://gitlab.gnome.org/GNOME/glib.git" +website_url = "https://www.gtk.org" +docs_urls = "https://docs.gtk.org/gio-win32/" +authors = "GLib Development Team" +license = "LGPL-2.1-or-later" +description = "Windows-specific APIs in Gio" +dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GLib-2.0"] + name = "GLib" + description = "The base utility library" + docs_url = "https://docs.gtk.org/glib/" + + [dependencies."GModule-2.0"] + name = "GModule" + description = "Portable API for dynamically loading modules" + docs_url = "https://docs.gtk.org/gmodule/" + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "A library of useful classes for I/O, networking and IPC" + docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[extra] +urlmap_file = "../urlmap.js" +# The same order will be used when generating the index +content_files = [] +content_images = [] diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in index 0d846eedc..d9c8a8362 100644 --- a/docs/reference/gio/gio.toml.in +++ b/docs/reference/gio/gio.toml.in @@ -47,7 +47,6 @@ content_files = [ "error.md", "pollable-utils.md", - "unix-mounts.md", "dbus-error.md", "dbus-introspection.md", diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index ecef66673..3bb321e9a 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -38,8 +38,11 @@ if get_option('documentation') and enable_gir 'overview.md', 'pollable-utils.md', 'tls-overview.md', + ] + expand_content_unix_files = [ 'unix-mounts.md', ] + expand_content_win32_files = [] gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf) @@ -61,4 +64,48 @@ if get_option('documentation') and enable_gir install_dir: docs_dir, install_tag: 'doc', ) + + if host_system == 'windows' + gio_win32_toml = configure_file(input: 'gio-win32.toml.in', output: 'gio-win32.toml', configuration: toml_conf) + + custom_target('gio-win32-docs', + input: [ gio_win32_toml, gio_win32_gir[0] ], + output: 'gio-win32', + command: [ + gidocgen, + 'generate', + gidocgen_common_args, + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + build_by_default: true, + depend_files: expand_content_win32_files, + install: true, + install_dir: docs_dir, + install_tag: 'doc', + ) + else + gio_unix_toml = configure_file(input: 'gio-unix.toml.in', output: 'gio-unix.toml', configuration: toml_conf) + + custom_target('gio-unix-docs', + input: [ gio_unix_toml, gio_unix_gir[0] ], + output: 'gio-unix', + command: [ + gidocgen, + 'generate', + gidocgen_common_args, + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + build_by_default: true, + depend_files: expand_content_unix_files, + install: true, + install_dir: docs_dir, + install_tag: 'doc', + ) + endif endif diff --git a/docs/reference/gio/migrating-posix.md b/docs/reference/gio/migrating-posix.md index 14efa1e03..ded78f141 100644 --- a/docs/reference/gio/migrating-posix.md +++ b/docs/reference/gio/migrating-posix.md @@ -6,12 +6,16 @@ SPDX-FileCopyrightText: 2007 Matthias Clasen ## Comparison of POSIX and GIO concepts -| POSIX | GIO | -|-----------------------|-----------------------------------------------------| -| `char *path` | [iface@Gio.File] | -| `struct stat *buf` | [class@Gio.FileInfo] | -| `struct statvfs *buf` | [class@Gio.FileInfo] | -| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] | -| `DIR *` | [class@Gio.FileEnumerator] | -| `fstab entry` | [struct@Gio.UnixMountPoint] | -| `mtab entry` | [struct@Gio.UnixMountEntry] | +The final two entries in this table require including `gio-unix-2.0.pc` as well +as `gio-2.0.pc` in your build (or, in GIR namespace terms, `GioUnix-2.0` as well +as `Gio-2.0`). + +| POSIX | GIO | +|-----------------------|-------------------------------------------------------------| +| `char *path` | [iface@Gio.File] | +| `struct stat *buf` | [class@Gio.FileInfo] | +| `struct statvfs *buf` | [class@Gio.FileInfo] | +| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] | +| `DIR *` | [class@Gio.FileEnumerator] | +| `fstab entry` | [`GUnixMountPoint`](../gio-unix/struct.UnixMountPoint.html) | +| `mtab entry` | [`GUnixMountEntry`](../gio-unix/struct.UnixMountEntry.html) | diff --git a/docs/reference/gio/unix-mounts.md b/docs/reference/gio/unix-mounts.md index dc450103c..f88102b80 100644 --- a/docs/reference/gio/unix-mounts.md +++ b/docs/reference/gio/unix-mounts.md @@ -13,23 +13,23 @@ file when using it. There are three main classes: - * [struct@Gio.UnixMountEntry] - * [struct@Gio.UnixMountPoint] - * [class@Gio.UnixMountMonitor] + * [struct@GioUnix.UnixMountEntry] + * [struct@GioUnix.UnixMountPoint] + * [class@GioUnix.UnixMountMonitor] Various helper functions for querying mounts: - * [func@Gio.unix_mount_points_get] - * [func@Gio.UnixMountPoint.at] - * [func@Gio.unix_mounts_get] - * [func@Gio.unix_mount_at] - * [func@Gio.unix_mount_for] - * [func@Gio.unix_mounts_changed_since] - * [func@Gio.unix_mount_points_changed_since] + * [func@GioUnix.unix_mount_points_get] + * [func@GioUnix.UnixMountPoint.at] + * [func@GioUnix.unix_mounts_get] + * [func@GioUnix.unix_mount_at] + * [func@GioUnix.unix_mount_for] + * [func@GioUnix.unix_mounts_changed_since] + * [func@GioUnix.unix_mount_points_changed_since] And several helper functions for checking the type of a mount or path: - * [func@Gio.unix_is_mount_path_system_internal] - * [func@Gio.unix_is_system_fs_type] - * [func@Gio.unix_is_system_device_path] + * [func@GioUnix.unix_is_mount_path_system_internal] + * [func@GioUnix.unix_is_system_fs_type] + * [func@GioUnix.unix_is_system_device_path] diff --git a/docs/reference/glib/glib-unix.toml.in b/docs/reference/glib/glib-unix.toml.in new file mode 100644 index 000000000..9280c1a34 --- /dev/null +++ b/docs/reference/glib/glib-unix.toml.in @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later +# Copyright 2023 Matthias Clasen +# Copyright 2023 Philip Withnall + +[library] +name = "GLibUnix" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/glib/" +repository_url = "https://gitlab.gnome.org/GNOME/glib.git" +website_url = "https://www.gtk.org" +docs_url = "https://docs.gtk.org/glib-unix/" +authors = "GLib Development Team" +license = "LGPL-2.1-or-later" +description = "Unix-specific APIs in GLib" +dependencies = [ "GLib-2.0" ] +related = [ "GModule-2.0", "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GLib-2.0"] + name = "GLib" + description = "The base utility library" + docs_url = "https://docs.gtk.org/glib/" + + [related."GModule-2.0"] + name = "GModule" + description = "Portable API for dynamically loading modules" + docs_url = "https://docs.gtk.org/gmodule/" + + [related."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [related."Gio-2.0"] + name = "GIO" + description = "GObject Interfaces and Objects, Networking, IPC, and I/O" + docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[extra] +urlmap_file = "../urlmap.js" +# The same order will be used when generating the index +content_files = [ + "unix.md", +] +content_images = [] diff --git a/docs/reference/glib/glib-win32.toml.in b/docs/reference/glib/glib-win32.toml.in new file mode 100644 index 000000000..a9f624f99 --- /dev/null +++ b/docs/reference/glib/glib-win32.toml.in @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later +# Copyright 2023 Matthias Clasen +# Copyright 2023 Philip Withnall + +[library] +name = "GLibWin32" +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/glib/" +repository_url = "https://gitlab.gnome.org/GNOME/glib.git" +website_url = "https://www.gtk.org" +docs_url = "https://docs.gtk.org/glib-win32/" +authors = "GLib Development Team" +license = "LGPL-2.1-or-later" +description = "Windows-specific APIs in GLib" +dependencies = [ "GLib-2.0" ] +related = [ "GModule-2.0", "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GLib-2.0"] + name = "GLib" + description = "The base utility library" + docs_url = "https://docs.gtk.org/glib/" + + [related."GModule-2.0"] + name = "GModule" + description = "Portable API for dynamically loading modules" + docs_url = "https://docs.gtk.org/gmodule/" + + [related."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [related."Gio-2.0"] + name = "GIO" + description = "GObject Interfaces and Objects, Networking, IPC, and I/O" + docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[extra] +urlmap_file = "../urlmap.js" +# The same order will be used when generating the index +content_files = [ + "windows.md", +] +content_images = [] diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 5eacf24e4..83acea5c4 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -75,8 +75,6 @@ content_files = [ "checked-math.md", "threads.md", "spawn.md", - "unix.md", - "windows.md", "random.md", "numerical.md", "markup.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index c9589636a..1777e537e 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -91,10 +91,14 @@ if get_option('documentation') and enable_gir 'string-utils.md', 'types.md', 'unicode.md', - 'unix.md', 'uuid.md', 'version.md', 'warnings.md', + ] + expand_content_unix_files = [ + 'unix.md', + ] + expand_content_win32_files = [ 'windows.md', ] @@ -118,4 +122,48 @@ if get_option('documentation') and enable_gir install_dir: docs_dir, install_tag: 'doc', ) + + if host_system == 'windows' + glib_win32_toml = configure_file(input: 'glib-win32.toml.in', output: 'glib-win32.toml', configuration: toml_conf) + + custom_target('glib-win32-docs', + input: [ glib_win32_toml, glib_win32_gir[0] ], + output: 'glib-win32', + command: [ + gidocgen, + 'generate', + gidocgen_common_args, + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + build_by_default: true, + depend_files: expand_content_win32_files, + install: true, + install_dir: docs_dir, + install_tag: 'doc', + ) + else + glib_unix_toml = configure_file(input: 'glib-unix.toml.in', output: 'glib-unix.toml', configuration: toml_conf) + + custom_target('glib-unix-docs', + input: [ glib_unix_toml, glib_unix_gir[0] ], + output: 'glib-unix', + command: [ + gidocgen, + 'generate', + gidocgen_common_args, + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', + ], + build_by_default: true, + depend_files: expand_content_unix_files, + install: true, + install_dir: docs_dir, + install_tag: 'doc', + ) + endif endif diff --git a/docs/reference/glib/unix.md b/docs/reference/glib/unix.md index fa446c5c4..792200b03 100644 --- a/docs/reference/glib/unix.md +++ b/docs/reference/glib/unix.md @@ -14,12 +14,12 @@ To use these functions, you must explicitly include the ## File Descriptors - * [func@GLib.unix_open_pipe] - * [func@GLib.unix_set_fd_nonblocking] + * [func@GLibUnix.unix_open_pipe] + * [func@GLibUnix.unix_set_fd_nonblocking] ## Pipes -The [struct@GLib.UnixPipe] structure can be used to conveniently open and +The [struct@GLibUnix.UnixPipe] structure can be used to conveniently open and manipulate a Unix pipe. @@ -33,16 +33,16 @@ The methods for it are all static inline for efficiency. They are: ## Signals - * [func@GLib.unix_signal_add] - * [func@GLib.unix_signal_add_full] - * [func@GLib.unix_signal_source_new] + * [func@GLibUnix.unix_signal_add] + * [func@GLibUnix.unix_signal_add_full] + * [func@GLibUnix.unix_signal_source_new] ## Polling - * [func@GLib.unix_fd_add] - * [func@GLib.unix_fd_add_full] - * [func@GLib.unix_fd_source_new] + * [func@GLibUnix.unix_fd_add] + * [func@GLibUnix.unix_fd_add_full] + * [func@GLibUnix.unix_fd_source_new] ## User Database - * [func@GLib.unix_get_passwd_entry] + * [func@GLibUnix.unix_get_passwd_entry] diff --git a/docs/reference/glib/windows.md b/docs/reference/glib/windows.md index c6a1080ec..91b1cf94f 100644 --- a/docs/reference/glib/windows.md +++ b/docs/reference/glib/windows.md @@ -8,19 +8,19 @@ These functions provide some level of Unix emulation on the Windows platform. If your application really needs the POSIX APIs, we suggest you try the [Cygwin project](https://cygwin.com/). - * [type@GLib.Win32OSType] - * [func@GLib.win32_check_windows_version] - * [func@GLib.win32_get_command_line] - * [func@GLib.win32_error_message] - * [func@GLib.win32_getlocale] - * [func@GLib.win32_get_package_installation_directory] - * [func@GLib.win32_get_package_installation_directory_of_module] - * [func@GLib.win32_get_package_installation_subdirectory] - * [func@GLib.win32_get_windows_version] - * [func@GLib.win32_locale_filename_from_utf8] - * [func@GLib.WIN32_HAVE_WIDECHAR_API] - * [func@GLib.WIN32_IS_NT_BASED] + * [type@GLibWin32.Win32OSType] + * [func@GLibWin32.win32_check_windows_version] + * [func@GLibWin32.win32_get_command_line] + * [func@GLibWin32.win32_error_message] + * [func@GLibWin32.win32_getlocale] + * [func@GLibWin32.win32_get_package_installation_directory] + * [func@GLibWin32.win32_get_package_installation_directory_of_module] + * [func@GLibWin32.win32_get_package_installation_subdirectory] + * [func@GLibWin32.win32_get_windows_version] + * [func@GLibWin32.win32_locale_filename_from_utf8] + * [func@GLibWin32.WIN32_HAVE_WIDECHAR_API] + * [func@GLibWin32.WIN32_IS_NT_BASED] ## Deprecated API - * [func@GLib.WIN32_DLLMAIN_FOR_DLL_NAME] + * [func@GLibWin32.WIN32_DLLMAIN_FOR_DLL_NAME] diff --git a/docs/reference/urlmap.js b/docs/reference/urlmap.js index b1f0962b0..05ca7675e 100644 --- a/docs/reference/urlmap.js +++ b/docs/reference/urlmap.js @@ -2,8 +2,12 @@ // SPDX-FileCopyrightText: 2023 Matthias Clasen var baseURLs = [ [ 'GLib', 'https://docs.gtk.org/glib/' ], + [ 'GLibUnix', 'https://docs.gtk.org/glib-unix/' ], + [ 'GLibWin32', 'https://docs.gtk.org/glib-win32/' ], [ 'GModule', 'https://docs.gtk.org/gmodule/' ], [ 'GObject', 'https://docs.gtk.org/gobject/' ], [ 'Gio', 'https://docs.gtk.org/gio/' ], + [ 'GioUnix', 'https://docs.gtk.org/gio-unix/' ], + [ 'GioWin32', 'https://docs.gtk.org/gio-win32/' ], [ 'Gtk', 'https://docs.gtk.org/gtk4/' ], ]; diff --git a/gio/gappinfo.c b/gio/gappinfo.c index 264de6913..652cae6e1 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -1674,11 +1674,15 @@ g_app_launch_context_launch_failed (GAppLaunchContext *context, * - [func@Gio.AppInfo.get_default_for_type] * - [func@Gio.AppInfo.get_fallback_for_type] * - [func@Gio.AppInfo.get_recommended_for_type] - * - [func@Gio.DesktopAppInfo.get_implementations] - * - [ctor@Gio.DesktopAppInfo.new] - * - [ctor@Gio.DesktopAppInfo.new_from_filename] - * - [ctor@Gio.DesktopAppInfo.new_from_keyfile] - * - [func@Gio.DesktopAppInfo.search] + * - [`g_desktop_app_info_get_implementations()`](../gio-unix/type_func.DesktopAppInfo.get_implementation.html) + * - [`g_desktop_app_info_new()`](../gio-unix/ctor.DesktopAppInfo.new.html) + * - [`g_desktop_app_info_new_from_filename()`](../gio-unix/ctor.DesktopAppInfo.new_from_filename.html) + * - [`g_desktop_app_info_new_from_keyfile()`](../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html) + * - [`g_desktop_app_info_search()`](../gio-unix/type_func.DesktopAppInfo.search.html) + * + * The latter functions are available if using + * [`GDesktopAppInfo`](../gio-unix/class.DesktopAppInfo.html) from + * `gio-unix-2.0.pc` (GIR namespace `GioUnix-2.0`). * * In the usual case, applications should try to make note of the change * (doing things like invalidating caches) but not act on it. In diff --git a/gio/gsimpleiostream.c b/gio/gsimpleiostream.c index f46d6e255..1b13fa24a 100644 --- a/gio/gsimpleiostream.c +++ b/gio/gsimpleiostream.c @@ -36,7 +36,9 @@ * * This is useful when you obtained a [class@Gio.InputStream] and a * [class@Gio.OutputStream] by other means, for instance creating them with - * platform specific methods as [ctor@Gio.UnixInputStream.new], and you want to + * platform specific methods as + * [`g_unix_input_stream_new()`](../gio-unix/ctor.UnixInputStream.new.html) + * (from `gio-unix-2.0.pc` / `GioUnix-2.0`), and you want to * take advantage of the methods provided by [class@Gio.IOStream]. * * Since: 2.44 diff --git a/gio/gunixfdlist.c b/gio/gunixfdlist.c index f17bb8dc0..88a5a5f8a 100644 --- a/gio/gunixfdlist.c +++ b/gio/gunixfdlist.c @@ -20,7 +20,8 @@ * A `GUnixFDList` contains a list of file descriptors. It owns the file * descriptors that it contains, closing them when finalized. * - * It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a + * It may be wrapped in a + * [`GUnixFDMessage`](../gio-unix/class.UnixFDMessage.html) and sent over a * [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using * [method@Gio.Socket.send_message] and received using * [method@Gio.Socket.receive_message]. From 434d3ff52442198244804785265878c219ca88da Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:41:11 +0000 Subject: [PATCH 09/13] docs: Mention GioUnix-2.0 GIR namespace alongside gio-unix-2.0.pc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This should clarify things a little for users of language bindings, who don’t directly use `.pc` files. Signed-off-by: Philip Withnall --- docs/reference/gio/overview.md | 4 ++-- docs/reference/gio/unix-mounts.md | 2 +- gio/gdesktopappinfo.c | 2 +- gio/gfiledescriptorbased.c | 2 +- gio/gunixfdmessage.c | 2 +- gio/gunixinputstream.c | 2 +- gio/gunixoutputstream.c | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/gio/overview.md b/docs/reference/gio/overview.md index 2e496e6d6..824a2a2a3 100644 --- a/docs/reference/gio/overview.md +++ b/docs/reference/gio/overview.md @@ -234,8 +234,8 @@ information on how to use pkg-config to compile your application. If you are using GIO on UNIX-like systems, you may want to use UNIX-specific GIO interfaces such as `GUnixInputStream`, `GUnixOutputStream`, `GUnixMount` -or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file instead of -`gio-2.0.pc`. +or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file as well as +`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`). ## Running GIO applications diff --git a/docs/reference/gio/unix-mounts.md b/docs/reference/gio/unix-mounts.md index f88102b80..1dc0665b9 100644 --- a/docs/reference/gio/unix-mounts.md +++ b/docs/reference/gio/unix-mounts.md @@ -9,7 +9,7 @@ Routines for managing mounted UNIX mount points and paths. Note that `` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. +file or the `GioUnix-2.0` GIR namespace when using it. There are three main classes: diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index bde0793fd..87db7a97a 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -70,7 +70,7 @@ * * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. + * file or the `GioUnix-2.0` GIR namespace when using it. */ #define DEFAULT_APPLICATIONS_GROUP "Default Applications" diff --git a/gio/gfiledescriptorbased.c b/gio/gfiledescriptorbased.c index 2647a9b8e..8a09632e4 100644 --- a/gio/gfiledescriptorbased.c +++ b/gio/gfiledescriptorbased.c @@ -35,7 +35,7 @@ * * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. + * file or the `GioUnix-2.0` GIR namespace when using it. * * Since: 2.24 **/ diff --git a/gio/gunixfdmessage.c b/gio/gunixfdmessage.c index 2d11a35c9..f800e95a1 100644 --- a/gio/gunixfdmessage.c +++ b/gio/gunixfdmessage.c @@ -29,7 +29,7 @@ * * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. + * file or the `GioUnix-2.0` GIR namespace when using it. */ #include "config.h" diff --git a/gio/gunixinputstream.c b/gio/gunixinputstream.c index 1ace44a11..210decd67 100644 --- a/gio/gunixinputstream.c +++ b/gio/gunixinputstream.c @@ -49,7 +49,7 @@ * * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. + * file or the `GioUnix-2.0` GIR namespace when using it. */ enum { diff --git a/gio/gunixoutputstream.c b/gio/gunixoutputstream.c index e0782cabc..96d9e952e 100644 --- a/gio/gunixoutputstream.c +++ b/gio/gunixoutputstream.c @@ -51,7 +51,7 @@ * * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file - * when using it. + * file or the `GioUnix-2.0` GIR namespace when using it. */ enum { From c428d6e67318e7b02c13111db260ed98622e982a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 16:34:36 +0000 Subject: [PATCH 10/13] ci: Build and tar the platform specific documentation Enable the msys2-mingw32 CI job for merges, just like the fedora-x86_64 job is. The pair of them can then build the platform specific GIR and documentation files. The `download-reference.sh` script in the `docs-gtk-org` branch of GTK can then download the docs as an artifact from the latest GLib build of `main`, and publish them on docs.gtk.org, as is currently done for the platform agnostic documentation. Signed-off-by: Philip Withnall Helps: #3037 --- .gitlab-ci.yml | 5 ++++- .gitlab-ci/test-msys2.sh | 16 +++++++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 59384ccec..d1d59c62f 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -198,9 +198,11 @@ fedora-x86_64: # can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md - mkdir -p _reference/ - mv _build/docs/reference/glib/glib/ _reference/glib/ + - mv _build/docs/reference/glib/glib-unix/ _reference/glib-unix/ - mv _build/docs/reference/gmodule/gmodule/ _reference/gmodule/ - mv _build/docs/reference/gobject/gobject/ _reference/gobject/ - mv _build/docs/reference/gio/gio/ _reference/gio/ + - mv _build/docs/reference/gio/gio-unix/ _reference/gio-unix/ - mv _build/docs/reference/girepository/girepository/ _reference/girepository/ artifacts: reports: @@ -476,7 +478,7 @@ cross-mingw64: - _build/gobject/libgobject-2.0-0.dll msys2-mingw32: - extends: .only-default + extends: .only-default-and-merges stage: build tags: - win32-ps @@ -501,6 +503,7 @@ msys2-mingw32: paths: - _build/meson-logs - _coverage/ + - _reference/ msys2-clang64: extends: .only-schedules-or-manual diff --git a/.gitlab-ci/test-msys2.sh b/.gitlab-ci/test-msys2.sh index 6ee6f124b..b5a6d9adb 100755 --- a/.gitlab-ci/test-msys2.sh +++ b/.gitlab-ci/test-msys2.sh @@ -11,10 +11,13 @@ pacman --noconfirm -S --needed \ lcov \ "${MINGW_PACKAGE_PREFIX}"-ccache \ "${MINGW_PACKAGE_PREFIX}"-gettext \ + "${MINGW_PACKAGE_PREFIX}"-gi-docgen \ + "${MINGW_PACKAGE_PREFIX}"-gobject-introspection \ "${MINGW_PACKAGE_PREFIX}"-libffi \ "${MINGW_PACKAGE_PREFIX}"-meson \ "${MINGW_PACKAGE_PREFIX}"-pcre2 \ "${MINGW_PACKAGE_PREFIX}"-python3 \ + "${MINGW_PACKAGE_PREFIX}"-python-docutils \ "${MINGW_PACKAGE_PREFIX}"-python-pip \ "${MINGW_PACKAGE_PREFIX}"-toolchain \ "${MINGW_PACKAGE_PREFIX}"-zlib \ @@ -33,7 +36,12 @@ DIR="$(pwd)" export PATH CFLAGS # shellcheck disable=SC2086 -meson setup ${MESON_COMMON_OPTIONS} --werror _build +meson setup ${MESON_COMMON_OPTIONS} \ + --werror \ + -Ddocumentation=true \ + -Dintrospection=enabled \ + -Dman-pages=enabled \ + _build meson compile -C _build @@ -59,3 +67,9 @@ if [[ "$CFLAGS" == *"-coverage"* ]]; then --capture \ --output-file "${DIR}/_coverage/${CI_JOB_NAME}.lcov" fi + +# Copy the built documentation to an artifact directory. The build for docs.gtk.org +# can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md +mkdir -p _reference/ +mv _build/docs/reference/glib/glib-win32/ _reference/glib-win32/ +mv _build/docs/reference/gio/gio-win32/ _reference/gio-win32/ \ No newline at end of file From 2b4bfadfb7f03b08b8a4687a478db83946309894 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 23:08:53 +0000 Subject: [PATCH 11/13] tests: Remove an unnecessary include from test-common.h It causes a build failure on mingw32, as `_WIN32_WINNT` is redefined. Signed-off-by: Philip Withnall --- girepository/tests/test-common.h | 2 -- 1 file changed, 2 deletions(-) diff --git a/girepository/tests/test-common.h b/girepository/tests/test-common.h index 8793a635d..9d31998d1 100644 --- a/girepository/tests/test-common.h +++ b/girepository/tests/test-common.h @@ -19,8 +19,6 @@ #pragma once -#include "config.h" - #include "girepository.h" typedef struct From 4314944e561e61b8658dd1ca8c8cc38983e8927e Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 8 Feb 2024 23:58:26 +0000 Subject: [PATCH 12/13] introspection: Drop Unix and Win32 prefixes from platform specific APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit So now introspection users will have to call `GLibUnix.open_pipe()` rather than `GLibUnix.unix_open_pipe()` — or `GLibWin32.check_windows_version()` rather than `GLibWin32.win32_check_windows_version()`. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/gio/unix-mounts.md | 26 +++++++++++++------------- docs/reference/glib/unix.md | 20 ++++++++++---------- docs/reference/glib/windows.md | 26 +++++++++++++------------- girepository/introspection/meson.build | 16 ++++++++++++++-- 4 files changed, 50 insertions(+), 38 deletions(-) diff --git a/docs/reference/gio/unix-mounts.md b/docs/reference/gio/unix-mounts.md index 1dc0665b9..404df3e6b 100644 --- a/docs/reference/gio/unix-mounts.md +++ b/docs/reference/gio/unix-mounts.md @@ -13,23 +13,23 @@ file or the `GioUnix-2.0` GIR namespace when using it. There are three main classes: - * [struct@GioUnix.UnixMountEntry] - * [struct@GioUnix.UnixMountPoint] - * [class@GioUnix.UnixMountMonitor] + * [struct@GioUnix.MountEntry] + * [struct@GioUnix.MountPoint] + * [class@GioUnix.MountMonitor] Various helper functions for querying mounts: - * [func@GioUnix.unix_mount_points_get] - * [func@GioUnix.UnixMountPoint.at] - * [func@GioUnix.unix_mounts_get] - * [func@GioUnix.unix_mount_at] - * [func@GioUnix.unix_mount_for] - * [func@GioUnix.unix_mounts_changed_since] - * [func@GioUnix.unix_mount_points_changed_since] + * [func@GioUnix.mount_points_get] + * [func@GioUnix.MountPoint.at] + * [func@GioUnix.mounts_get] + * [func@GioUnix.mount_at] + * [func@GioUnix.mount_for] + * [func@GioUnix.mounts_changed_since] + * [func@GioUnix.mount_points_changed_since] And several helper functions for checking the type of a mount or path: - * [func@GioUnix.unix_is_mount_path_system_internal] - * [func@GioUnix.unix_is_system_fs_type] - * [func@GioUnix.unix_is_system_device_path] + * [func@GioUnix.is_mount_path_system_internal] + * [func@GioUnix.is_system_fs_type] + * [func@GioUnix.is_system_device_path] diff --git a/docs/reference/glib/unix.md b/docs/reference/glib/unix.md index 792200b03..4dad67366 100644 --- a/docs/reference/glib/unix.md +++ b/docs/reference/glib/unix.md @@ -14,12 +14,12 @@ To use these functions, you must explicitly include the ## File Descriptors - * [func@GLibUnix.unix_open_pipe] - * [func@GLibUnix.unix_set_fd_nonblocking] + * [func@GLibUnix.open_pipe] + * [func@GLibUnix.set_fd_nonblocking] ## Pipes -The [struct@GLibUnix.UnixPipe] structure can be used to conveniently open and +The [struct@GLibUnix.Pipe] structure can be used to conveniently open and manipulate a Unix pipe. @@ -33,16 +33,16 @@ The methods for it are all static inline for efficiency. They are: ## Signals - * [func@GLibUnix.unix_signal_add] - * [func@GLibUnix.unix_signal_add_full] - * [func@GLibUnix.unix_signal_source_new] + * [func@GLibUnix.signal_add] + * [func@GLibUnix.signal_add_full] + * [func@GLibUnix.signal_source_new] ## Polling - * [func@GLibUnix.unix_fd_add] - * [func@GLibUnix.unix_fd_add_full] - * [func@GLibUnix.unix_fd_source_new] + * [func@GLibUnix.fd_add] + * [func@GLibUnix.fd_add_full] + * [func@GLibUnix.fd_source_new] ## User Database - * [func@GLibUnix.unix_get_passwd_entry] + * [func@GLibUnix.get_passwd_entry] diff --git a/docs/reference/glib/windows.md b/docs/reference/glib/windows.md index 91b1cf94f..bdef6dae2 100644 --- a/docs/reference/glib/windows.md +++ b/docs/reference/glib/windows.md @@ -8,19 +8,19 @@ These functions provide some level of Unix emulation on the Windows platform. If your application really needs the POSIX APIs, we suggest you try the [Cygwin project](https://cygwin.com/). - * [type@GLibWin32.Win32OSType] - * [func@GLibWin32.win32_check_windows_version] - * [func@GLibWin32.win32_get_command_line] - * [func@GLibWin32.win32_error_message] - * [func@GLibWin32.win32_getlocale] - * [func@GLibWin32.win32_get_package_installation_directory] - * [func@GLibWin32.win32_get_package_installation_directory_of_module] - * [func@GLibWin32.win32_get_package_installation_subdirectory] - * [func@GLibWin32.win32_get_windows_version] - * [func@GLibWin32.win32_locale_filename_from_utf8] - * [func@GLibWin32.WIN32_HAVE_WIDECHAR_API] - * [func@GLibWin32.WIN32_IS_NT_BASED] + * [type@GLibWin32.OSType] + * [func@GLibWin32.check_windows_version] + * [func@GLibWin32.get_command_line] + * [func@GLibWin32.error_message] + * [func@GLibWin32.getlocale] + * [func@GLibWin32.get_package_installation_directory] + * [func@GLibWin32.get_package_installation_directory_of_module] + * [func@GLibWin32.get_package_installation_subdirectory] + * [func@GLibWin32.get_windows_version] + * [func@GLibWin32.locale_filename_from_utf8] + * [func@GLibWin32.HAVE_WIDECHAR_API] + * [func@GLibWin32.IS_NT_BASED] ## Deprecated API - * [func@GLibWin32.WIN32_DLLMAIN_FOR_DLL_NAME] + * [func@GLib.WIN32_DLLMAIN_FOR_DLL_NAME] diff --git a/girepository/introspection/meson.build b/girepository/introspection/meson.build index d96f19f60..d23909647 100644 --- a/girepository/introspection/meson.build +++ b/girepository/introspection/meson.build @@ -71,6 +71,8 @@ if host_system == 'windows' '-DGLIB_COMPILATION', '-DGETTEXT_PACKAGE="dummy"', '--symbol-prefix=glib', + '--symbol-prefix=g_win32', + '--identifier-prefix=GWin32', '--library-path=' + meson.current_build_dir(), '--library=gobject-2.0', ], @@ -97,6 +99,8 @@ else '-DGLIB_COMPILATION', '-DGETTEXT_PACKAGE="dummy"', '--symbol-prefix=glib', + '--symbol-prefix=g_unix', + '--identifier-prefix=GUnix', '--library-path=' + meson.current_build_dir(), '--library=gobject-2.0', '--c-include=glib-unix.h', @@ -216,7 +220,11 @@ if host_system == 'windows' libgmodule_dep, ], env: gi_gen_env_variables, - extra_args: gir_args + gio_gir_args + [ '--pkg=gio-win32-2.0' ] + gio_win32_gir_c_includes, + extra_args: gir_args + gio_gir_args + gio_win32_gir_c_includes + [ + '--pkg=gio-win32-2.0', + '--symbol-prefix=g_win32', + '--identifier-prefix=GWin32' + ], ) else gio_unix_gir_c_includes = [] @@ -240,7 +248,11 @@ else libgmodule_dep, ], env: gi_gen_env_variables, - extra_args: gir_args + gio_gir_args + [ '--pkg=gio-unix-2.0' ] + gio_unix_gir_c_includes, + extra_args: gir_args + gio_gir_args + gio_unix_gir_c_includes + [ + '--pkg=gio-unix-2.0', + '--symbol-prefix=g_unix', + '--identifier-prefix=GUnix' + ], ) endif From 19308d6c1853f4f7a25c5f02e0d7d64dae574b1e Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 12 Feb 2024 15:17:20 +0000 Subject: [PATCH 13/13] introspection: Re-add platform specific APIs to GLib-2.0.gir and Gio-2.0.gir To avoid a big introspection API break. These APIs are now listed in the new `{GLib,Gio}{Unix,Win32}-2.0.gir` files, but for backwards compatibility they need to continue to be listed in `Gio-2.0.gir` and `GLib-2.0.gir` as well, until the next major introspection API break (and none is planned). No new platform specific APIs should be added to these GIR files, but these existing ones must remain. See https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3892#note_2001361 Signed-off-by: Philip Withnall --- girepository/introspection/meson.build | 63 ++++++++++++++++++++------ 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/girepository/introspection/meson.build b/girepository/introspection/meson.build index d23909647..9405686c1 100644 --- a/girepository/introspection/meson.build +++ b/girepository/introspection/meson.build @@ -15,20 +15,33 @@ if get_option('b_sanitize') != '' endif # GLib +glib_gir_sources = [ + gi_gen_shared_sources, + glibconfig_h, + gversionmacros_h, + glib_visibility_h, + glib_headers, + glib_deprecated_headers, + glib_sub_headers, + glib_enumtypes_h, + glib_types_h, + glib_deprecated_sources, + glib_sources, +] + +# For API compatibility reasons, GLib-2.0.gir needs to contain the platform +# specific APIs which are also present in the (newer) GLibUnix-2.0.gir and +# GLibWin32-2.0.gir repositories. +# See https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3892#note_2001361 +# These can be dropped when GLib next breaks API (i.e. with GLib-3.0.gir). +if host_system == 'windows' + glib_gir_sources += files('../../glib/gwin32.h') +else + glib_gir_sources += files('../../glib/glib-unix.h') +endif + glib_gir = gnome.generate_gir(libglib, - sources: [ - gi_gen_shared_sources, - glibconfig_h, - gversionmacros_h, - glib_visibility_h, - glib_headers, - glib_deprecated_headers, - glib_sub_headers, - glib_enumtypes_h, - glib_types_h, - glib_deprecated_sources, - glib_sources, - ], + sources: glib_gir_sources, namespace: 'GLib', nsversion: '2.0', identifier_prefix: gi_identifier_prefix, @@ -173,19 +186,41 @@ gio_gir_sources = [ contenttype_sources, settings_sources, ] +gio_gir_packages = [ 'gio-2.0' ] gio_gir_args = [ '-DGIO_COMPILATION', '-DG_SETTINGS_ENABLE_BACKEND', '--symbol-prefix=gio', ] +# For API compatibility reasons, Gio-2.0.gir needs to contain the platform +# specific APIs which are also present in the (newer) GioUnix-2.0.gir and +# GioWin32-2.0.gir repositories. +# See https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3892#note_2001361 +# These can be dropped when GIO next breaks API (i.e. with Gio-3.0.gir). +if host_system == 'windows' + gio_gir_sources += [ gio_win32_include_headers, win32_sources ] + foreach h: gio_win32_include_headers + gio_gir_args += '--c-include=@0@'.format(h) + endforeach + gio_gir_packages += 'gio-win32-2.0' + gio_gir_args += '--pkg=gio-win32-2.0' +else + gio_gir_sources += [ gio_unix_include_headers, unix_sources ] + foreach h: gio_unix_include_headers + gio_gir_args += '--c-include=@0@'.format(h) + endforeach + gio_gir_packages += 'gio-unix-2.0' + gio_gir_args += '--pkg=gio-unix-2.0' +endif + gio_gir = gnome.generate_gir(libgio, sources: gio_gir_sources, namespace: 'Gio', nsversion: '2.0', identifier_prefix: gi_identifier_prefix, symbol_prefix: gi_symbol_prefix, - export_packages: [ 'gio-2.0' ], + export_packages: gio_gir_packages, header: 'gio/gio.h', includes: [ glib_gir[0], gmodule_gir[0], gobject_gir[0] ], install: true,