[gtk/docs-gtk-org] Add GModule API
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/docs-gtk-org] Add GModule API
- Date: Tue, 24 Aug 2021 11:04:53 +0000 (UTC)
commit 5bd66748744c9b8718eff2afe1783901d8d709e3
Author: Emmanuele Bassi <ebassi gnome org>
Date: Tue Aug 24 12:02:55 2021 +0100
Add GModule API
In the gtk-doc API reference GModule is part of GLib, but for
introspection purposes, GModule has its own namespace, which means it
requires its own documentation module.
.gitlab-ci.yml | 1 +
glib/gmodule/GModule-2.0.gir | 539 +++++++++++++++++++++++++++++++++++++++++++
glib/gmodule/gmodule.toml.in | 44 ++++
glib/gmodule/meson.build | 23 ++
glib/gmodule/modules.md | 92 ++++++++
glib/gmodule/urlmap.js | 7 +
meson.build | 1 +
7 files changed, 707 insertions(+)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 106fc86650..b45a71c5ad 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -15,6 +15,7 @@ reference:
- meson setup _build
- meson compile -C _build
- mv _build/glib/glib/glib/ docs/glib/
+ - mv _build/glib/gmodule/gmodule/ docs/gmodule/
- mv _build/glib/gobject/gobject/ docs/gobject/
- mv _build/glib/gio/gio/ docs/gio/
- mv _build/gtk3/gdk/gdk3/ docs/gdk3/
diff --git a/glib/gmodule/GModule-2.0.gir b/glib/gmodule/GModule-2.0.gir
new file mode 100644
index 0000000000..4843158f1e
--- /dev/null
+++ b/glib/gmodule/GModule-2.0.gir
@@ -0,0 +1,539 @@
+<?xml version="1.0"?>
+<!-- This file was automatically generated from C sources - DO NOT EDIT!
+To affect the contents of this file, edit the original C definitions,
+and/or use gtk-doc annotations. -->
+<repository version="1.2"
+ xmlns="http://www.gtk.org/introspection/core/1.0";
+ xmlns:c="http://www.gtk.org/introspection/c/1.0";
+ xmlns:glib="http://www.gtk.org/introspection/glib/1.0";>
+ <include name="GLib" version="2.0"/>
+ <package name="gmodule-2.0"/>
+ <c:include name="gmodule.h"/>
+ <namespace name="GModule"
+ version="2.0"
+ shared-library="libgmodule-2.0.so.0"
+ c:identifier-prefixes="G"
+ c:symbol-prefixes="g">
+ <record name="Module" c:type="GModule" disguised="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="5">The #GModule struct is an opaque data structure to represent a
+[dynamically-loaded module][glib-Dynamic-Loading-of-Modules].
+It should only be accessed via the following functions.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="65"/>
+ <method name="close" c:identifier="g_module_close">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="185">Closes a module.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="105"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="191">%TRUE on success</doc>
+ <type name="gboolean" c:type="gboolean"/>
+ </return-value>
+ <parameters>
+ <instance-parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="187">a #GModule to close</doc>
+ <type name="Module" c:type="GModule*"/>
+ </instance-parameter>
+ </parameters>
+ </method>
+ <method name="make_resident" c:identifier="g_module_make_resident">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="204">Ensures that a module will never be unloaded.
+Any future g_module_close() calls on the module will be ignored.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="109"/>
+ <return-value transfer-ownership="none">
+ <type name="none" c:type="void"/>
+ </return-value>
+ <parameters>
+ <instance-parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="206">a #GModule to make permanently resident</doc>
+ <type name="Module" c:type="GModule*"/>
+ </instance-parameter>
+ </parameters>
+ </method>
+ <method name="name" c:identifier="g_module_name">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="213">Returns the filename that the module was opened with.
+
+If @module refers to the application itself, "main" is returned.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="123"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="221">the filename of the module</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </return-value>
+ <parameters>
+ <instance-parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="215">a #GModule</doc>
+ <type name="Module" c:type="GModule*"/>
+ </instance-parameter>
+ </parameters>
+ </method>
+ <method name="symbol" c:identifier="g_module_symbol">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="273">Gets a symbol pointer from a module, such as one exported
+by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="117"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="282">%TRUE on success</doc>
+ <type name="gboolean" c:type="gboolean"/>
+ </return-value>
+ <parameters>
+ <instance-parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="275">a #GModule</doc>
+ <type name="Module" c:type="GModule*"/>
+ </instance-parameter>
+ <parameter name="symbol_name" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="276">the name of the symbol to find</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ <parameter name="symbol"
+ direction="out"
+ caller-allocates="0"
+ transfer-ownership="full"
+ nullable="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="277">returns the pointer to the symbol value</doc>
+ <type name="gpointer" c:type="gpointer*"/>
+ </parameter>
+ </parameters>
+ </method>
+ <function name="build_path" c:identifier="g_module_build_path">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="159">A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result
+is added to the directory, using the correct separator character.
+
+The directory should specify the directory where the module can be found.
+It can be %NULL or an empty string to indicate that the module is in a
+standard platform-specific directory, though this is not recommended
+since the wrong module may be found.
+
+For example, calling g_module_build_path() on a Linux system with a
+@directory of `/lib` and a @module_name of "mylibrary" will return
+`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+directory it will return `\Windows\mylibrary.dll`.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="137"/>
+ <return-value transfer-ownership="full">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="180">the complete path of the module, including the standard library
+ prefix and suffix. This should be freed when no longer needed</doc>
+ <type name="utf8" c:type="gchar*"/>
+ </return-value>
+ <parameters>
+ <parameter name="directory"
+ transfer-ownership="none"
+ nullable="1"
+ allow-none="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="161">the directory where the module is. This can be
+ %NULL or the empty string to indicate that the standard platform-specific
+ directories will be used, though that is not recommended</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ <parameter name="module_name" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="164">the name of the module</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ </parameters>
+ </function>
+ <function name="error" c:identifier="g_module_error">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="195">Gets a string describing the last module error.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="113"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="200">a string describing the last module error</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </return-value>
+ </function>
+ <function name="error_quark" c:identifier="g_module_error_quark">
+ <return-value transfer-ownership="none">
+ <type name="GLib.Quark" c:type="GQuark"/>
+ </return-value>
+ </function>
+ <function name="open" c:identifier="g_module_open" introspectable="0">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="225">A thin wrapper function around g_module_open_full()</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="95"/>
+ <return-value>
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="234">a #GModule on success, or %NULL on failure</doc>
+ <type name="Module" c:type="GModule*"/>
+ </return-value>
+ <parameters>
+ <parameter name="file_name"
+ transfer-ownership="none"
+ nullable="1"
+ allow-none="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="227">the name of the file containing the module, or %NULL
+ to obtain a #GModule representing the main program itself</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ <parameter name="flags" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="229">the flags used for opening the module. This can be the
+ logical OR of any of the #GModuleFlags.</doc>
+ <type name="ModuleFlags" c:type="GModuleFlags"/>
+ </parameter>
+ </parameters>
+ </function>
+ <function name="open_full"
+ c:identifier="g_module_open_full"
+ version="2.70"
+ introspectable="0"
+ throws="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="238">Opens a module. If the module has already been opened,
+its reference count is incremented.
+
+First of all g_module_open_full() tries to open @file_name as a module.
+If that fails and @file_name has the ".la"-suffix (and is a libtool
+archive) it tries to open the corresponding module. If that fails
+and it doesn't have the proper module suffix for the platform
+(#G_MODULE_SUFFIX), this suffix will be appended and the corresponding
+module will be opened. If that fails and @file_name doesn't have the
+".la"-suffix, this suffix is appended and g_module_open_full() tries to open
+the corresponding module. If eventually that fails as well, %NULL is
+returned.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="99"/>
+ <return-value>
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="259">a #GModule on success, or %NULL on failure</doc>
+ <type name="Module" c:type="GModule*"/>
+ </return-value>
+ <parameters>
+ <parameter name="file_name"
+ transfer-ownership="none"
+ nullable="1"
+ allow-none="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="240">the name of the file containing the module, or %NULL
+ to obtain a #GModule representing the main program itself</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ <parameter name="flags" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="242">the flags used for opening the module. This can be the
+ logical OR of any of the #GModuleFlags</doc>
+ <type name="ModuleFlags" c:type="GModuleFlags"/>
+ </parameter>
+ </parameters>
+ </function>
+ <function name="supported" c:identifier="g_module_supported">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="264">Checks if modules are supported on the current platform.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="91"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="269">%TRUE if modules are supported</doc>
+ <type name="gboolean" c:type="gboolean"/>
+ </return-value>
+ </function>
+ </record>
+ <callback name="ModuleCheckInit" c:type="GModuleCheckInit">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="14">Specifies the type of the module initialization function.
+If a module contains a function named g_module_check_init() it is called
+automatically when the module is loaded. It is passed the #GModule structure
+and should return %NULL on success or a string describing the initialization
+error.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="66"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="24">%NULL on success, or a string describing the initialization error</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </return-value>
+ <parameters>
+ <parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="16">the #GModule corresponding to the module which has just been loaded</doc>
+ <type name="Module" c:type="GModule*"/>
+ </parameter>
+ </parameters>
+ </callback>
+ <enumeration name="ModuleError"
+ version="2.70"
+ c:type="GModuleError"
+ glib:error-domain="g-module-error-quark">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="73">Errors returned by g_module_open_full().</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="86"/>
+ <member name="failed" value="0" c:identifier="G_MODULE_ERROR_FAILED">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="75">there was an error loading or opening a module file</doc>
+ </member>
+ <member name="check_failed"
+ value="1"
+ c:identifier="G_MODULE_ERROR_CHECK_FAILED">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="76">a module returned an error from its `g_module_check_init()` function</doc>
+ </member>
+ </enumeration>
+ <bitfield name="ModuleFlags" c:type="GModuleFlags">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="44">Flags passed to g_module_open().
+Note that these flags are not supported on all platforms.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="63"/>
+ <member name="lazy" value="1" c:identifier="G_MODULE_BIND_LAZY">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="46">specifies that symbols are only resolved when
+ needed. The default action is to bind all symbols when the module
+ is loaded.</doc>
+ </member>
+ <member name="local" value="2" c:identifier="G_MODULE_BIND_LOCAL">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="49">specifies that symbols in the module should
+ not be added to the global name space. The default action on most
+ platforms is to place symbols in the module in the global name space,
+ which may cause conflicts with existing symbols.</doc>
+ </member>
+ <member name="mask" value="3" c:identifier="G_MODULE_BIND_MASK">
+ <doc xml:space="preserve"
+ filename="install/include/glib-2.0/gmodule.h"
+ line="53">mask for all flags.</doc>
+ </member>
+ </bitfield>
+ <callback name="ModuleUnload" c:type="GModuleUnload">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="28">Specifies the type of the module function called when it is unloaded.
+If a module contains a function named g_module_unload() it is called
+automatically when the module is unloaded.
+It is passed the #GModule structure.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="67"/>
+ <return-value transfer-ownership="none">
+ <type name="none" c:type="void"/>
+ </return-value>
+ <parameters>
+ <parameter name="module" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="30">the #GModule about to be unloaded</doc>
+ <type name="Module" c:type="GModule*"/>
+ </parameter>
+ </parameters>
+ </callback>
+ <function name="module_build_path"
+ c:identifier="g_module_build_path"
+ moved-to="Module.build_path">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="159">A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result
+is added to the directory, using the correct separator character.
+
+The directory should specify the directory where the module can be found.
+It can be %NULL or an empty string to indicate that the module is in a
+standard platform-specific directory, though this is not recommended
+since the wrong module may be found.
+
+For example, calling g_module_build_path() on a Linux system with a
+@directory of `/lib` and a @module_name of "mylibrary" will return
+`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+directory it will return `\Windows\mylibrary.dll`.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="137"/>
+ <return-value transfer-ownership="full">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="180">the complete path of the module, including the standard library
+ prefix and suffix. This should be freed when no longer needed</doc>
+ <type name="utf8" c:type="gchar*"/>
+ </return-value>
+ <parameters>
+ <parameter name="directory"
+ transfer-ownership="none"
+ nullable="1"
+ allow-none="1">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="161">the directory where the module is. This can be
+ %NULL or the empty string to indicate that the standard platform-specific
+ directories will be used, though that is not recommended</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ <parameter name="module_name" transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="164">the name of the module</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </parameter>
+ </parameters>
+ </function>
+ <function name="module_error"
+ c:identifier="g_module_error"
+ moved-to="Module.error">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="195">Gets a string describing the last module error.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="113"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="200">a string describing the last module error</doc>
+ <type name="utf8" c:type="const gchar*"/>
+ </return-value>
+ </function>
+ <function name="module_error_quark"
+ c:identifier="g_module_error_quark"
+ moved-to="Module.error_quark">
+ <return-value transfer-ownership="none">
+ <type name="GLib.Quark" c:type="GQuark"/>
+ </return-value>
+ </function>
+ <function name="module_supported"
+ c:identifier="g_module_supported"
+ moved-to="Module.supported">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="264">Checks if modules are supported on the current platform.</doc>
+ <source-position filename="install/include/glib-2.0/gmodule.h"
+ line="91"/>
+ <return-value transfer-ownership="none">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="269">%TRUE if modules are supported</doc>
+ <type name="gboolean" c:type="gboolean"/>
+ </return-value>
+ </function>
+ <docsection name="modules">
+ <doc xml:space="preserve"
+ filename="source/gobject-introspection/gir/gmodule-2.0.c"
+ line="79">These functions provide a portable way to dynamically load object files
+(commonly known as 'plug-ins'). The current implementation supports all
+systems that provide an implementation of dlopen() (e.g. Linux/Sun), as
+well as Windows platforms via DLLs.
+
+A program which wants to use these functions must be linked to the
+libraries output by the command `pkg-config --libs gmodule-2.0`.
+
+To use them you must first determine whether dynamic loading
+is supported on the platform by calling g_module_supported().
+If it is, you can open a module with g_module_open(),
+find the module's symbols (e.g. function names) with g_module_symbol(),
+and later close the module with g_module_close().
+g_module_name() will return the file name of a currently opened module.
+
+If any of the above functions fail, the error status can be found with
+g_module_error().
+
+The #GModule implementation features reference counting for opened modules,
+and supports hook functions within a module which are called when the
+module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
+
+If your module introduces static data to common subsystems in the running
+program, e.g. through calling
+`g_quark_from_static_string ("my-module-stuff")`,
+it must ensure that it is never unloaded, by calling g_module_make_resident().
+
+Example: Calling a function defined in a GModule
+|[<!-- language="C" -->
+// the function signature for 'say_hello'
+typedef void (* SayHelloFunc) (const char *message);
+
+gboolean
+just_say_hello (const char *filename, GError **error)
+{
+ SayHelloFunc say_hello;
+ GModule *module;
+
+ module = g_module_open (filename, G_MODULE_BIND_LAZY);
+ if (!module)
+ {
+ g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
+ "%s", g_module_error ());
+ return FALSE;
+ }
+
+ if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "%s: %s", filename, g_module_error ());
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return FALSE;
+ }
+
+ if (say_hello == NULL)
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "symbol say_hello is NULL");
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return FALSE;
+ }
+
+ // call our function in the module
+ say_hello ("Hello world!");
+
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+ return TRUE;
+ }
+]|</doc>
+ </docsection>
+ </namespace>
+</repository>
diff --git a/glib/gmodule/gmodule.toml.in b/glib/gmodule/gmodule.toml.in
new file mode 100644
index 0000000000..9e310ba895
--- /dev/null
+++ b/glib/gmodule/gmodule.toml.in
@@ -0,0 +1,44 @@
+[library]
+name = "GModule"
+version = "2.68"
+browse_url = "https://gitlab.gnome.org/GNOME/glib/";
+repository_url = "https://gitlab.gnome.org/GNOME/glib.git";
+website_url = "https://www.gtk.org";
+authors = "GTK Development Team"
+license = "GPL-2.1-or-later"
+description = "Portable API for dynamically loading modules"
+dependencies = [ "GLib-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."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 = "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
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/glib/-/blob/master/";
+
+[extra]
+urlmap_file = "urlmap.js"
+# The same order will be used when generating the index
+content_files = [
+ "modules.md",
+]
+content_images = [
+]
diff --git a/glib/gmodule/meson.build b/glib/gmodule/meson.build
new file mode 100644
index 0000000000..52730d54c1
--- /dev/null
+++ b/glib/gmodule/meson.build
@@ -0,0 +1,23 @@
+expand_content_files = [
+ 'modules.md',
+]
+
+gmodule_gir = meson.current_source_dir() / 'GModule-2.0.gir'
+gmodule_toml = configure_file(input: 'gmodule.toml.in', output: 'gmodule.toml', configuration: toml_conf)
+
+custom_target('gmodule-doc',
+ input: [ gmodule_toml, gmodule_gir ],
+ output: 'gmodule',
+ command: [
+ gidocgen,
+ 'generate',
+ '--quiet',
+ '--config=@INPUT0@',
+ '--output-dir=@OUTPUT@',
+ '--no-namespace-dir',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '@INPUT1@',
+ ],
+ build_by_default: true,
+ depend_files: expand_content_files,
+)
diff --git a/glib/gmodule/modules.md b/glib/gmodule/modules.md
new file mode 100644
index 0000000000..8f0eeeb4a0
--- /dev/null
+++ b/glib/gmodule/modules.md
@@ -0,0 +1,92 @@
+Title: Dynamic Loading of Modules
+
+## Dynamic Loading of Modules
+
+These functions provide a portable way to dynamically load object files
+(commonly known as 'plug-ins'). The current implementation supports all
+systems that provide an implementation of `dlopen()` (e.g. Linux/Sun), as
+well as Windows platforms via DLLs.
+
+A program which wants to use these functions must be linked to the libraries
+output by the command:
+
+ pkg-config --libs gmodule-2.0
+
+To use them you must first determine whether dynamic loading is supported on
+the platform by calling [`func@GModule.Module.supported`]. If it is, you can
+open a module with [`func GModule Module open`], find the module's symbols
+(e.g. function names) with [`method@GModule.Module.symbol`], and later close
+the module with [`method@GModule.Module.close`].
+[`method GModule Module name`] will return the file name of a currently
+opened module.
+
+If any of the above functions fail, the error status can be found with
+[`func@GModule.Module.error`].
+
+The `GModule` implementation features reference counting for opened modules,
+and supports hook functions within a module which are called when the module
+is loaded and unloaded (see [callback@GModule.ModuleCheckInit] and
+[callback@GModule.ModuleUnload]).
+
+If your module introduces static data to common subsystems in the running
+program, e.g. through calling API like:
+
+```c
+static GQuark my_module_quark =
+ g_quark_from_static_string ("my-module-stuff");
+```
+
+it must ensure that it is never unloaded, by calling
+[`method@GModule.Module.make_resident`].
+
+### Calling a function defined in a GModule
+
+```c
+// the function signature for 'say_hello'
+typedef void (* SayHelloFunc) (const char *message);
+
+gboolean
+just_say_hello (const char *filename, GError **error)
+{
+ SayHelloFunc say_hello;
+ GModule *module;
+
+ module = g_module_open (filename, G_MODULE_BIND_LAZY);
+ if (module == NULL)
+ {
+ g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
+ "%s", g_module_error ());
+ return FALSE;
+ }
+
+ if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "%s: %s", filename, g_module_error ());
+
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+
+ return FALSE;
+ }
+
+ if (say_hello == NULL)
+ {
+ g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
+ "symbol say_hello is NULL");
+
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+
+ return FALSE;
+ }
+
+ // call our function in the module
+ say_hello ("Hello world!");
+
+ if (!g_module_close (module))
+ g_warning ("%s: %s", filename, g_module_error ());
+
+ return TRUE;
+ }
+```
diff --git a/glib/gmodule/urlmap.js b/glib/gmodule/urlmap.js
new file mode 100644
index 0000000000..443294788d
--- /dev/null
+++ b/glib/gmodule/urlmap.js
@@ -0,0 +1,7 @@
+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/meson.build b/meson.build
index 8b2580c930..ebb6f520f6 100644
--- a/meson.build
+++ b/meson.build
@@ -17,6 +17,7 @@ toml_conf.set('VERSION', meson.project_version())
gidocgen = find_program('gi-docgen', required: true)
subdir('glib/glib')
+subdir('glib/gmodule')
subdir('glib/gobject')
subdir('glib/gio')
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
