Merge branch '3037-split-platform-docs' into 'main'

introspection: Generate separate GIR files and documentation for platform specific APIs

See merge request GNOME/glib!3892

.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

.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/

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 = []

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 = []

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",
@@ -47,7 +47,6 @@ content_files = [
   "error.md",
 
   "pollable-utils.md",
-  "unix-mounts.md",
 
   "dbus-error.md",
   "dbus-introspection.md",

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

docs/reference/gio/migrating-posix.md

@@ -6,12 +6,16 @@ SPDX-FileCopyrightText: 2007 Matthias Clasen
 
 ## Comparison of POSIX and GIO concepts
 
-| POSIX                 | GIO                                                 |
+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
-| `char *path`          | [iface@Gio.File]                                    |
+as `Gio-2.0`).
-| `struct stat *buf`    | [class@Gio.FileInfo]                                |
+
-| `struct statvfs *buf` | [class@Gio.FileInfo]                                |
+| POSIX                 | GIO                                                         |
-| `int fd`              | [class@Gio.InputStream] or [class@Gio.OutputStream] |
+|-----------------------|-------------------------------------------------------------|
-| `DIR *`               | [class@Gio.FileEnumerator]                          |
+| `char *path`          | [iface@Gio.File]                                            |
-| `fstab entry`         | [struct@Gio.UnixMountPoint]                         |
+| `struct stat *buf`    | [class@Gio.FileInfo]                                        |
-| `mtab entry`          | [struct@Gio.UnixMountEntry]                         |
+| `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) |

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
+or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file as well as
-`gio-2.0.pc`.
+`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`).
 
 ## Running GIO applications
 

docs/reference/gio/unix-mounts.md

@@ -9,27 +9,27 @@ Routines for managing mounted UNIX mount points and paths.
 
 Note that `<gio/gunixmounts.h>` 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:
 
- * [struct@Gio.UnixMountEntry]
+ * [struct@GioUnix.MountEntry]
- * [struct@Gio.UnixMountPoint]
+ * [struct@GioUnix.MountPoint]
- * [class@Gio.UnixMountMonitor]
+ * [class@GioUnix.MountMonitor]
 
 Various helper functions for querying mounts:
 
- * [func@Gio.unix_mount_points_get]
+ * [func@GioUnix.mount_points_get]
- * [func@Gio.UnixMountPoint.at]
+ * [func@GioUnix.MountPoint.at]
- * [func@Gio.unix_mounts_get]
+ * [func@GioUnix.mounts_get]
- * [func@Gio.unix_mount_at]
+ * [func@GioUnix.mount_at]
- * [func@Gio.unix_mount_for]
+ * [func@GioUnix.mount_for]
- * [func@Gio.unix_mounts_changed_since]
+ * [func@GioUnix.mounts_changed_since]
- * [func@Gio.unix_mount_points_changed_since]
+ * [func@GioUnix.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@GioUnix.is_mount_path_system_internal]
- * [func@Gio.unix_is_system_fs_type]
+ * [func@GioUnix.is_system_fs_type]
- * [func@Gio.unix_is_system_device_path]
+ * [func@GioUnix.is_system_device_path]
 

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",

docs/reference/girepository/urlmap.js

@@ -1,10 +0,0 @@
-// 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/' ],
-    [ 'Gio', 'https://docs.gtk.org/gio/' ],
-    [ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
-];

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 = []

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 = []

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",
@@ -75,8 +75,6 @@ content_files = [
   "checked-math.md",
   "threads.md",
   "spawn.md",
-  "unix.md",
-  "windows.md",
   "random.md",
   "numerical.md",
   "markup.md",

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

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@GLibUnix.open_pipe]
- * [func@GLib.unix_set_fd_nonblocking]
+ * [func@GLibUnix.set_fd_nonblocking]
 
 ## Pipes
 
-The [struct@GLib.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.
 
 <!-- FIXME: https://gitlab.gnome.org/GNOME/gi-docgen/-/issues/173 -->
@@ -33,16 +33,16 @@ The methods for it are all static inline for efficiency. They are:
 
 ## Signals
 
- * [func@GLib.unix_signal_add]
+ * [func@GLibUnix.signal_add]
- * [func@GLib.unix_signal_add_full]
+ * [func@GLibUnix.signal_add_full]
- * [func@GLib.unix_signal_source_new]
+ * [func@GLibUnix.signal_source_new]
 
 ## Polling
 
- * [func@GLib.unix_fd_add]
+ * [func@GLibUnix.fd_add]
- * [func@GLib.unix_fd_add_full]
+ * [func@GLibUnix.fd_add_full]
- * [func@GLib.unix_fd_source_new]
+ * [func@GLibUnix.fd_source_new]
 
 ## User Database
 
- * [func@GLib.unix_get_passwd_entry]
+ * [func@GLibUnix.get_passwd_entry]

docs/reference/glib/urlmap.js

@@ -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/' ],
-];

docs/reference/glib/windows.md

@@ -8,18 +8,18 @@ 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]
+ * [type@GLibWin32.OSType]
- * [func@GLib.win32_check_windows_version]
+ * [func@GLibWin32.check_windows_version]
- * [func@GLib.win32_get_command_line]
+ * [func@GLibWin32.get_command_line]
- * [func@GLib.win32_error_message]
+ * [func@GLibWin32.error_message]
- * [func@GLib.win32_getlocale]
+ * [func@GLibWin32.getlocale]
- * [func@GLib.win32_get_package_installation_directory]
+ * [func@GLibWin32.get_package_installation_directory]
- * [func@GLib.win32_get_package_installation_directory_of_module]
+ * [func@GLibWin32.get_package_installation_directory_of_module]
- * [func@GLib.win32_get_package_installation_subdirectory]
+ * [func@GLibWin32.get_package_installation_subdirectory]
- * [func@GLib.win32_get_windows_version]
+ * [func@GLibWin32.get_windows_version]
- * [func@GLib.win32_locale_filename_from_utf8]
+ * [func@GLibWin32.locale_filename_from_utf8]
- * [func@GLib.WIN32_HAVE_WIDECHAR_API]
+ * [func@GLibWin32.HAVE_WIDECHAR_API]
- * [func@GLib.WIN32_IS_NT_BASED]
+ * [func@GLibWin32.IS_NT_BASED]
 
 ## Deprecated API
 

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",

docs/reference/gmodule/urlmap.js

@@ -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/' ],
-];

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",

docs/reference/gobject/urlmap.js

@@ -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/' ],
-];

docs/reference/urlmap.js

@@ -1,10 +1,13 @@
 // 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/' ],
+    [ '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/' ],
 ];

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]
+ *  - [`g_desktop_app_info_get_implementations()`](../gio-unix/type_func.DesktopAppInfo.get_implementation.html)
- *  - [ctor@Gio.DesktopAppInfo.new]
+ *  - [`g_desktop_app_info_new()`](../gio-unix/ctor.DesktopAppInfo.new.html)
- *  - [ctor@Gio.DesktopAppInfo.new_from_filename]
+ *  - [`g_desktop_app_info_new_from_filename()`](../gio-unix/ctor.DesktopAppInfo.new_from_filename.html)
- *  - [ctor@Gio.DesktopAppInfo.new_from_keyfile]
+ *  - [`g_desktop_app_info_new_from_keyfile()`](../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html)
- *  - [func@Gio.DesktopAppInfo.search]
+ *  - [`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

gio/gdesktopappinfo.c

@@ -70,7 +70,7 @@
  *
  * Note that `<gio/gdesktopappinfo.h>` 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"

gio/gfiledescriptorbased.c

@@ -35,7 +35,7 @@
  *
  * Note that `<gio/gfiledescriptorbased.h>` 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
  **/

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.

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;

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

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].

gio/gunixfdmessage.c

@@ -29,7 +29,7 @@
  *
  * Note that `<gio/gunixfdmessage.h>` 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"

gio/gunixinputstream.c

@@ -49,7 +49,7 @@
  *
  * Note that `<gio/gunixinputstream.h>` 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 {

gio/gunixoutputstream.c

@@ -51,7 +51,7 @@
  *
  * Note that `<gio/gunixoutputstream.h>` 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 {

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

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: [
+  sources: 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,
-  ],
   namespace: 'GLib',
   nsversion: '2.0',
   identifier_prefix: gi_identifier_prefix,
@@ -49,6 +62,65 @@ 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',
+      '--symbol-prefix=g_win32',
+      '--identifier-prefix=GWin32',
+      '--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',
+      '--symbol-prefix=g_unix',
+      '--identifier-prefix=GUnix',
+      '--library-path=' + meson.current_build_dir(),
+      '--library=gobject-2.0',
+      '--c-include=glib-unix.h',
+    ],
+  )
+endif
+
 # GObject
 gobject_gir = gnome.generate_gir(libgobject,
   sources: [
@@ -111,10 +183,7 @@ gio_gir_sources = [
   gio_base_sources,
   application_sources,
   gdbus_sources,
-  appinfo_sources,
   contenttype_sources,
-  unix_sources,
-  win32_sources,
   settings_sources,
 ]
 gio_gir_packages = [ 'gio-2.0' ]
@@ -123,15 +192,21 @@ gio_gir_args = [
   '-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
+  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
+  gio_gir_sources += [ gio_unix_include_headers, unix_sources ]
   foreach h: gio_unix_include_headers
     gio_gir_args += '--c-include=@0@'.format(h)
   endforeach
@@ -158,6 +233,65 @@ 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 + gio_win32_gir_c_includes + [
+      '--pkg=gio-win32-2.0',
+      '--symbol-prefix=g_win32',
+      '--identifier-prefix=GWin32'
+    ],
+  )
+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 + gio_unix_gir_c_includes + [
+      '--pkg=gio-unix-2.0',
+      '--symbol-prefix=g_unix',
+      '--identifier-prefix=GUnix'
+    ],
+  )
+endif
+
+# GIRepository
 libgirepository_gir_sources = [
   gi_visibility_h,
   girepo_headers,

girepository/tests/test-common.h

@@ -19,8 +19,6 @@
 
 #pragma once
 
-#include "config.h"
-
 #include "girepository.h"
 
 typedef struct

glib/gwin32.h

@@ -33,7 +33,7 @@
 
 #include <glib/gtypes.h>
 
-#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__ */

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
+  glib_unix_headers = files('glib-unix.h')
-  # when it includes GLib as a subproject
+  install_headers(glib_unix_headers, install_dir : glib_includedir)
-  glib_unix_h = files('glib-unix.h')
 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',