glib/gversion.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1998  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /*
  21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GLib Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "gversion.h"
  30
  31 /**
  32  * SECTION:version
  33  * @Title: Version Information
  34  * @Short_description: variables and functions to check the GLib version
  35  *
  36  * GLib provides version information, primarily useful in configure
  37  * checks for builds that have a configure script. Applications will
  38  * not typically use the features described here.
  39  *
  40  * The GLib headers annotate deprecated APIs in a way that produces
  41  * compiler warnings if these deprecated APIs are used. The warnings
  42  * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
  43  * before including the glib.h header.
  44  *
  45  * GLib also provides support for building applications against
  46  * defined subsets of deprecated or new GLib APIs. Define the macro
  47  * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
  48  * you want to receive warnings about deprecated APIs. Define the
  49  * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
  50  * GLib whose API you want to use.
  51  */
  52
  53 /**
  54  * glib_major_version:
  55  *
  56  * The major version of the GLib library.
  57  *
  58  * An integer variable exported from the library linked
  59  * against at application run time.
  60  */
  61
  62 /**
  63  * GLIB_MAJOR_VERSION:
  64  *
  65  * The major version number of the GLib library.
  66  *
  67  * Like #glib_major_version, but from the headers used at
  68  * application compile time, rather than from the library
  69  * linked against at application run time.
  70  */
  71
  72 /**
  73  * glib_minor_version:
  74  *
  75  * The minor version number of the GLib library.
  76  *
  77  * An integer variable exported from the library linked
  78  * against at application run time.
  79  */
  80
  81 /**
  82  * GLIB_MINOR_VERSION:
  83  *
  84  * The minor version number of the GLib library.
  85  *
  86  * Like #gtk_minor_version, but from the headers used at
  87  * application compile time, rather than from the library
  88  * linked against at application run time.
  89  */
  90
  91 /**
  92  * glib_micro_version:
  93  *
  94  * The micro version number of the GLib library.
  95  *
  96  * An integer variable exported from the library linked
  97  * against at application run time.
  98  */
  99
 100 /**
 101  * GLIB_MICRO_VERSION:
 102  *
 103  * The micro version number of the GLib library.
 104  *
 105  * Like #gtk_micro_version, but from the headers used at
 106  * application compile time, rather than from the library
 107  * linked against at application run time.
 108  */
 109
 110 /**
 111  * GLIB_CHECK_VERSION:
 112  * @major: the major version to check for
 113  * @minor: the minor version to check for
 114  * @micro: the micro version to check for
 115  *
 116  * Checks whether the version of the GLib library that is being compiled
 117  * against is greater than or equal to the given one.
 118  *
 119  * See glib_check_version() for a runtime check.
 120  *
 121  * Returns: %TRUE if the version of the GLib header files
 122  * is the same as or newer than the passed-in version.
 123  */
 124
 125 /**
 126  * glib_binary_age:
 127  *
 128  * The binary age of the GLib library.
 129  * Defines how far back backwards compatibility reaches.
 130  *
 131  * An integer variable exported from the library linked
 132  * against at application run time.
 133  */
 134
 135 /**
 136  * glib_interface_age:
 137  *
 138  * The interface age of the GLib library.
 139  * Defines how far back the API has last been extended.
 140  *
 141  * An integer variable exported from the library linked
 142  * against at application run time.
 143  */
 144
 145 const guint glib_major_version = GLIB_MAJOR_VERSION;
 146 const guint glib_minor_version = GLIB_MINOR_VERSION;
 147 const guint glib_micro_version = GLIB_MICRO_VERSION;
 148 const guint glib_interface_age = GLIB_INTERFACE_AGE;
 149 const guint glib_binary_age = GLIB_BINARY_AGE;
 150
 151 /**
 152  * glib_check_version:
 153  * @required_major: the required major version
 154  * @required_minor: the required minor version
 155  * @required_micro: the required micro version
 156  *
 157  * Checks that the GLib library in use is compatible with the
 158  * given version.
 159  *
 160  * Generally you would pass in the constants %GLIB_MAJOR_VERSION,
 161  * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments
 162  * to this function; that produces a check that the library in use
 163  * is compatible with the version of GLib the application or module
 164  * was compiled against.
 165  *
 166  * Compatibility is defined by two things: first the version
 167  * of the running library is newer than the version
 168  * `@required_major.required_minor.@required_micro`. Second
 169  * the running library must be binary compatible with the
 170  * version `@required_major.@required_minor.@required_micro`
 171  * (same major version.)
 172  *
 173  * Returns: (transfer none) (nullable): %NULL if the GLib library is
 174  *   compatible with the given version, or a string describing the
 175  *   version mismatch. The returned string is owned by GLib and must
 176  *   not be modified or freed.
 177  *
 178  * Since: 2.6
 179  */
 180 const gchar *
 181 glib_check_version (guint required_major,
 182                     guint required_minor,
 183                     guint required_micro)
 184 {
 185   gint glib_effective_micro = 100 * GLIB_MINOR_VERSION + GLIB_MICRO_VERSION;
 186   gint required_effective_micro = 100 * required_minor + required_micro;
 187
 188   if (required_major > GLIB_MAJOR_VERSION)
 189     return "GLib version too old (major mismatch)";
 190   if (required_major < GLIB_MAJOR_VERSION)
 191     return "GLib version too new (major mismatch)";
 192   if (required_effective_micro < glib_effective_micro - GLIB_BINARY_AGE)
 193     return "GLib version too new (micro mismatch)";
 194   if (required_effective_micro > glib_effective_micro)
 195     return "GLib version too old (micro mismatch)";
 196   return NULL;
 197 }