1Glib::version(3)      User Contributed Perl Documentation     Glib::version(3)
2
3
4

NAME

6       Glib::version -  Library Versioning Utilities
7

SYNOPSIS

9         # require at least version 1.021 of the Glib module
10         use Glib '1.021';
11
12         # g_set_application_name() was introduced in GLib 2.2.0, and
13         # first supported by version 1.040 of the Glib Perl module.
14         if ($Glib::VERSION >= 1.040 and Glib->CHECK_VERSION (2,2,0)) {
15            Glib::set_application_name ('My Cool Program');
16         }
17

DESCRIPTION

19       Both the Glib module and the GLib C library are works-in-progress, and
20       their interfaces grow over time.  As more features are added to each,
21       and your code uses those new features, you will introduce version-
22       specific dependencies, and naturally, you'll want to be able to code
23       around them.  Enter the versioning API.
24
25       For simple Perl modules, a single version number is sufficient;
26       however, Glib is a binding to another software library, and this
27       introduces some complexity.  We have three versions that fully specify
28       the API available to you.
29
30       Perl Bindings Version
31           Perl modules use a version number, and Glib is no exception.
32           $Glib::VERSION is the version of the current Glib module.  By ad
33           hoc convention, gtk2-perl modules generally use version numbers in
34           the form x.yyz, where even yy values denote stable releases and z
35           is a patchlevel.
36
37              $Glib::VERSION
38              use Glib 1.040; # require at least version 1.040
39
40       Compile-time ("Bound") Library Version
41           This is the version of the GLib C library that was available when
42           the Perl module was compiled and installed.  These version
43           constants are equivalent to the version macros provided in the GLib
44           C headers.  GLib uses a major.minor.micro convention, where even
45           minor versions are stable.  (gtk2-perl does not officially support
46           unstable versions.)
47
48              Glib::MAJOR_VERSION
49              Glib::MINOR_VERSION
50              Glib::MICRO_VERSION
51              Glib->CHECK_VERSION($maj,$min,$mic)
52
53       Run-time ("Linked") Library Version
54           This is the version of the GLib C library that is available at run
55           time; it may be newer than the compile-time version, but should
56           never be older.  These are equivalent to the version variables
57           exported by the GLib C library.
58
59              Glib::major_version
60              Glib::minor_version
61              Glib::micro_version
62
63   Which one do I use when?
64       Where do you use which version?  It depends entirely on what you're
65       doing.  Let's explain by example:
66
67       o Use the Perl module version for bindings support issues
68           You need to register a new enum for use as the type of an object
69           property.  This is something you can do with all versions of the
70           underlying C library, but which wasn't supported in the Glib Perl
71           module until $Glib::VERSION >= 1.040.
72
73       o Use the bound version for library features
74           You want to call Glib::set_application_name to set a human-readable
75           name for your application (which is used by various parts of Gtk2
76           and Gnome2).  g_set_application_name() (the underlying C function)
77           was added in version 2.2.0 of glib, and support for it was
78           introduced into the Glib Perl module in Glib version 1.040.
79           However, you can build the Perl module against any stable 2.x.x
80           version of glib, so you might not have that function available even
81           if your Glib module is new enough!
82             Thus, you need to check two things to see if the this function is
83           available:
84
85              if ($Glib::VERSION >= 1.040 && Glib->CHECK_VERSION (2,2,0)) {
86                  # it's available, and we can call it!
87                  Glib::set_application_name ('My Cool Application');
88              }
89
90           Now what happens if you installed the Perl module when your system
91           had glib 2.0.6, and you upgraded glib to 2.4.1?  Wouldn't
92           g_set_application_name() be available?  Well, it's there, under the
93           hood, but the bindings were compiled when it wasn't there, so you
94           won't be able to call it!  That's why we check the "bound" or
95           compile-time version.  By the way, to enable support for the new
96           function, you'd need to reinstall (or upgrade) the Perl module.
97
98       o Use the linked version for runtime work-arounds
99           Suppose there's a function whose API did not change, but whose
100           implementation had a bug in one version that was fixed in another
101           version.  To determine whether you need to apply a workaround, you
102           would check the version that is actually being used at runtime.
103
104              if (Glib::major_version == 2 &&
105                  Glib::minor_version == 2 &&
106                  Glib::micro_version == 1) {
107                 # work around bug that exists only in glib 2.2.1.
108              }
109
110           In practice, such situations are very rare.
111

METHODS

113   boolean = Glib->CHECK_VERSION ($required_major, $required_minor,
114       $required_micro)
115       •   $required_major (integer)
116
117       •   $required_minor (integer)
118
119       •   $required_micro (integer)
120
121       Provides a mechanism for checking the version information that Glib was
122       compiled against. Essentially equvilent to the macro
123       GLIB_CHECK_VERSION.
124
125   (MAJOR, MINOR, MICRO) = Glib->GET_VERSION_INFO
126       Shorthand to fetch as a list the glib version for which Glib was
127       compiled.  See "Glib::MAJOR_VERSION", etc.
128
129   integer = Glib::MAJOR_VERSION
130       Provides access to the version information that Glib was compiled
131       against.  Essentially equivalent to the #define's GLIB_MAJOR_VERSION.
132
133   integer = Glib::MICRO_VERSION
134       Provides access to the version information that Glib was compiled
135       against.  Essentially equivalent to the #define's GLIB_MICRO_VERSION.
136
137   integer = Glib::MINOR_VERSION
138       Provides access to the version information that Glib was compiled
139       against.  Essentially equivalent to the #define's GLIB_MINOR_VERSION.
140
141   integer = Glib::major_version
142       Provides access to the version information that Glib is linked against.
143       Essentially equivalent to the global variable glib_major_version.
144
145   integer = Glib::micro_version
146       Provides access to the version information that Glib is linked against.
147       Essentially equivalent to the global variable glib_micro_version.
148
149   integer = Glib::minor_version
150       Provides access to the version information that Glib is linked against.
151       Essentially equivalent to the global variable glib_minor_version.
152

SEE ALSO

154       Glib
155
157       Copyright (C) 2003-2011 by the gtk2-perl team.
158
159       This software is licensed under the LGPL.  See Glib for a full notice.
160
161
162
163perl v5.34.0                      2021-07-22                  Glib::version(3)
Impressum