New function to check the version of GLib at runtime. (#149175, Michael

Tue Aug  3 14:58:20 2004  Matthias Clasen  <maclas@gmx.de>

	* glib/gutils.h:
	* glib/gutils.c (glib_check_version): New function to
	check the version of GLib at runtime.  (#149175, Michael Natterer)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a6bf71f..ac4f139 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+Tue Aug  3 15:34:16 2004  Matthias Clasen  <maclas@gmx.de>
+
+       * glib/glib-sections.txt: Add a separate section for
+       version information.
+       * glib/glib-docs.sgml: Include version section.
+       * glib/tmpl/version.sgml: New template.
+
 2004-08-02  Matthias Clasen  <mclasen@redhat.com>
 
        * glib/glib-sections.txt: 

diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index a4de335..b0b7ef0 100644 (file)
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -55,6 +55,7 @@
 <!ENTITY glib-Shell SYSTEM "xml/shell.xml">
 <!ENTITY glib-Markup SYSTEM "xml/markup.xml">
 <!ENTITY glib-i18n SYSTEM "xml/i18n.xml">
+<!ENTITY glib-Version SYSTEM "xml/version.xml">
 
 <!ENTITY glib-Compiling SYSTEM "compiling.sgml">
 <!ENTITY glib-Building SYSTEM "building.sgml">
@@ -100,6 +101,7 @@ synchronize their operation.
 
   <chapter id="glib-fundamentals">
     <title>GLib Fundamentals</title>
+    &glib-Version;
     &glib-Basic-Types;
     &glib-Limits-of-Basic-Types;
     &glib-Standard-Macros;

diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 371f6ee..4d2e31f 100644 (file)
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -95,21 +95,31 @@ G_MAXDOUBLE
 </SECTION>
 
 <SECTION>
-<TITLE>Standard Macros</TITLE>
-<FILE>macros</FILE>
+<TITLE>Version Information</TITLE>
+<FILE>version</FILE>
+glib_major_version
+glib_minor_version
+glib_micro_version
+glib_binary_age
+glib_interface_age
+glib_check_version
+
+<SUBSECTION>
 GLIB_MAJOR_VERSION
 GLIB_MINOR_VERSION
 GLIB_MICRO_VERSION
+GLIB_CHECK_VERSION
+</SECTION>
 
+<SECTION>
+<TITLE>Standard Macros</TITLE>
+<FILE>macros</FILE>
 <SUBSECTION>
 G_OS_WIN32
 G_OS_BEOS
 G_OS_UNIX
 
 <SUBSECTION>
-GLIB_CHECK_VERSION
-
-<SUBSECTION>
 G_DIR_SEPARATOR
 G_DIR_SEPARATOR_S
 G_SEARCHPATH_SEPARATOR
@@ -141,12 +151,6 @@ G_MEM_ALIGN
 <SUBSECTION>
 G_CONST_RETURN
 
-<SUBSECTION Private>
-glib_major_version
-glib_micro_version
-glib_minor_version
-glib_interface_age
-glib_binary_age
 </SECTION>
 
 <SECTION>

diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml
index 3749d28..2c498ed 100644 (file)
--- a/docs/reference/glib/tmpl/macros.sgml
+++ b/docs/reference/glib/tmpl/macros.sgml
@@ -14,27 +14,6 @@ These macros provide a few commonly-used features.
 
 </para>
 
-<!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
-<para>
-The major version number of the GLib library.
-</para>
-
-
-
-<!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
-<para>
-The minor version number of the GLib library.
-</para>
-
-
-
-<!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
-<para>
-The micro version number of the GLib library.
-</para>
-
-
-
 <!-- ##### MACRO G_OS_WIN32 ##### -->
 <para>
 This macro is defined only on Windows. So you can bracket
@@ -59,26 +38,6 @@ UNIX-specific code in "&num;ifdef G_OS_UNIX".
 
 
 
-<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
-<para>
-Checks the version of the GLib library.
-It returns %TRUE if the GLib library is the same or newer than the given
-version.
-
-<example>
-<title>Checking the version of the GLib library</title>
-<programlisting>
-  if (!GLIB_CHECK_VERSION (1, 2, 0))
-    g_error ("GLib version 1.2.0 or above is needed");
-</programlisting>
-</example>
-</para>
-
-@major: the major version number.
-@minor: the minor version number.
-@micro: the micro version number.
-
-
 <!-- ##### MACRO G_DIR_SEPARATOR ##### -->
 <para>
 The directory separator character.

diff --git a/docs/reference/glib/tmpl/version.sgml b/docs/reference/glib/tmpl/version.sgml
new file mode 100644 (file)
index 0000000..1154cf1
--- /dev/null
+++ b/docs/reference/glib/tmpl/version.sgml
@@ -0,0 +1,136 @@
+<!-- ##### SECTION Title ##### -->
+Version Information
+
+<!-- ##### SECTION Short_Description ##### -->
+Variables and functions to check the GLib version
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+GLib provides version information, primarily useful in configure checks
+for builds that have a configure script. Applications will not
+typically use the features described here.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### VARIABLE glib_major_version ##### -->
+<para>
+The major version number of the GLib library. 
+(e.g. in GLib version 1.2.5 this is 1.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MAJOR_VERSION macro, which represents the major version of the
+GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_minor_version ##### -->
+<para>
+The minor version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 2.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MINOR_VERSION macro, which represents the minor version of the
+GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_micro_version ##### -->
+<para>
+The micro version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 5.)
+</para>
+
+<para>
+This variable is in the library, so represents the GLib library you
+have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
+represents the micro version of the GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_binary_age ##### -->
+<para>
+This is the binary age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### VARIABLE glib_interface_age ##### -->
+<para>
+This is the interface age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### FUNCTION glib_check_version ##### -->
+<para>
+
+</para>
+
+@required_major: 
+@required_minor: 
+@required_micro: 
+@Returns: 
+
+
+<!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
+<para>
+The major version number of the GLib library.
+Like #glib_major_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
+</para>
+
+
+
+<!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
+<para>
+The minor version number of the GLib library.
+Like #gtk_minor_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
+</para>
+
+
+
+<!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
+<para>
+The micro version number of the GLib library.
+Like #gtk_micro_version, but from the headers used at
+application compile time, rather than from the library linked against
+at application run time.
+</para>
+
+
+
+<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
+<para>
+Checks the version of the GLib library.
+It returns %TRUE if the GLib library is the same or newer than the given
+version.
+
+<example>
+<title>Checking the version of the GLib library</title>
+<programlisting>
+  if (!GLIB_CHECK_VERSION (1, 2, 0))
+    g_error ("GLib version 1.2.0 or above is needed");
+</programlisting>
+</example>
+</para>
+
+@major: the major version number.
+@minor: the minor version number.
+@micro: the micro version number.
+
+

diff --git a/glib/gutils.c b/glib/gutils.c
index 4320375..07a09c1 100644 (file)
--- a/glib/gutils.c
+++ b/glib/gutils.c
@@ -96,6 +96,53 @@ const guint glib_micro_version = GLIB_MICRO_VERSION;
 const guint glib_interface_age = GLIB_INTERFACE_AGE;
 const guint glib_binary_age = GLIB_BINARY_AGE;
 
+/**
+ * glib_check_version:
+ * @required_major: the required major version.
+ * @required_minor: the required major version.
+ * @required_micro: the required major version.
+ *
+ * Checks that the GLib library in use is compatible with the
+ * given version. Generally you would pass in the constants
+ * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
+ * as the three arguments to this function; that produces
+ * a check that the library in use is compatible with
+ * the version of GLib the application or module was compiled
+ * against.
+ *
+ * Compatibility is defined by two things: first the version
+ * of the running library is newer than the version
+ * @required_major.required_minor.@required_micro. Second
+ * the running library must be binary compatible with the
+ * version @required_major.required_minor.@required_micro
+ * (same major version.)
+ *
+ * Return value: %NULL if the GLib library is compatible with the
+ *   given version, or a string describing the version mismatch.
+ *   The returned string is owned by GLib and must not be modified
+ *   or freed.
+ *
+ * Since: 2.6
+ **/
+const gchar *
+glib_check_version (guint required_major,
+                    guint required_minor,
+                    guint required_micro)
+{
+  gint glib_effective_micro = 100 * GLIB_MINOR_VERSION + GLIB_MICRO_VERSION;
+  gint required_effective_micro = 100 * required_minor + required_micro;
+
+  if (required_major > GLIB_MAJOR_VERSION)
+    return "GLib version too old (major mismatch)";
+  if (required_major < GLIB_MAJOR_VERSION)
+    return "GLib version too new (major mismatch)";
+  if (required_effective_micro < glib_effective_micro - GLIB_BINARY_AGE)
+    return "GLib version too new (micro mismatch)";
+  if (required_effective_micro > glib_effective_micro)
+    return "GLib version too old (micro mismatch)";
+  return NULL;
+}
+
 #if !defined (HAVE_MEMMOVE) && !defined (HAVE_WORKING_BCOPY)
 void 
 g_memmove (gpointer dest, gconstpointer src, gulong len)

diff --git a/glib/gutils.h b/glib/gutils.h
index 731cf1e..3307e8a 100644 (file)
--- a/glib/gutils.h
+++ b/glib/gutils.h
@@ -325,6 +325,10 @@ GLIB_VAR const guint glib_micro_version;
 GLIB_VAR const guint glib_interface_age;
 GLIB_VAR const guint glib_binary_age;
 
+const gchar * glib_check_version (guint required_major,
+                                  guint required_minor,
+                                  guint required_micro);
+
 #define GLIB_CHECK_VERSION(major,minor,micro)    \
     (GLIB_MAJOR_VERSION > (major) || \
      (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION > (minor)) || \