Re: version checking pod RFC

[muppet <scott asofyet org>]

On Monday, February 23, 2004, at 08:28 PM, Ross McFarland wrote:

> following up last night's commit here's some potential pod doc about 
> how to check versions. this would go in Glib.pm, something similar or 
> a pointer to this should go in Gtk2.
>
> http://www.neces.com/gtk2-perl/version_pod.patch
>
> unless there are major problems i'll commit it tomorrow sometime. i 
> don't know no english so i'm sure it sucks as far as grammer and 
> spelling go.

i think the prose is a little dense; a more conversational tone would 
lighten it up a bit.

the x.yyz format we use is actually not standard, it is a silly 
convention (that i made up) that works in the standard framework, which 
is "a floating point number".  three-part version numbers will be 
included in perl 5.10.0, but that won't help us, because we need to 
retain compatibility with 5.8.0 (without requiring non-standard 
modules).

i think we *should* explain the rationale, because it's really not that 
difficult.  examples help, and concrete rather than abstract examples 
are more useful for people who are just Perl developers, not bindings 
maintainers.  (think about people who don't know C but are very good 
with Perl.)

here's my attempt (which could probably use some work, itself):


-=-=-

=head1 VERSIONS

Both the Glib module and the GLib C library are works-in-progress, and 
their interfaces grow over time.  As more features are added to each, 
and your code uses those new features, you will introduce 
version-specific dependencies, and naturally, you'll want to be able to 
code around them.  Enter the versioning API.

For simple Perl modules, a single version number is sufficient; 
however, Glib is a binding to another software library, and this 
introduces some complexity.  We have three versions that fully specify 
the API available to you.

=over

=item Perl Bindings Version

Perl modules use a version number, and Glib is no exception.  
I<$Glib::VERSION> is the version of the current Glib module.  By ad hoc 
convention, gtk2-perl modules generally use version numbers in the form 
x.yyz, where even yy values denote stable releases and z is a 
patchlevel.

  $Glib::VERSION
  use Glib 1.040; # require at least version 1.040

=item Compile-time ("Bound") Library Version

This is the version of the GLib C library that was available when the 
Perl module was compiled and installed.  These version constants are 
equivalent to the version macros provided in the GLib C headers.  GLib 
uses a major.minor.micro convention, where even minor versions are 
stable.  (gtk2-perl does not officially support unstable versions.)

  Glib::MAJOR_VERSION
  Glib::MINOR_VERSION
  Glib::MICRO_VERSION
  Glib->CHECK_VERSION($maj,$min,$mic)

=item Run-time ("Linked") Library Version

This is the version of the GLib C library that is available at run 
time; it may be newer than the compile-time version, but should never 
be older.  These are equivalent to the version variables exported by 
the GLib C library.

  Glib::major_version
  Glib::minor_version
  Glib::micro_version

=back

=head2 Which one do I use when?

Where do you use which version?  It depends entirely on what you're 
doing.  Let's explain by example:

=over

=item o Use the Perl module version for bindings support issues

You need to register a new enum for use as the type of an object 
property.  This is something you can do with all versions of the 
underlying C library, but which wasn't supported in the Glib Perl 
module until $Glib::VERSION >= 1.040.

=item o Use the bound version for library features

[This example is for Gtk2, which works the same way, because there are 
no relevant and similarly illustrative examples in Glib.]

You want to use the Gtk2::FileChooser.  GtkFileChooser (the underlying 
widget) was added in version 2.4.0 of gtk+, and support for it was 
introduced into the Gtk2 Perl module in Gtk2 version 1.040.  However, 
you can build the Perl module against any stable 2.x.x version of gtk+! 
 Thus, you need to check two things to see if the FileChooser is 
available:

  if ($Gtk2::VERSION >= 1.040 && Gtk2->CHECK_VERSION (2,4,0)) {
      # the Gtk2::FileChooser is available.
  }

Now what happens if you installed the Perl module when your system had 
gtk+ 2.2.4, and you upgraded gtk+ to 2.4.1?  Wouldn't the FileChooser 
be available?  Well, it's there, under the hood, but the bindings were 
compiled when it wasn't there, so you won't be able to call any of its 
methods!  That's why we check the "bound" version.  By the way, to 
enable support for the new widgets, you'd need to reinstall (or 
upgrade) the Perl module.

=item o Use the linked version for runtime work-arounds

Suppose there's a function whose API did not change, but whose 
implementation had a bug in one version that was fixed in another 
version.  To determine whether you need to apply a workaround, you 
would check the version that is actually being used at runtime.

  if (Glib::major_version == 2 &&
      Glib::minor_version == 2 &&
      Glib::micro_version == 1) {
     # work around bug that exists only in glib 2.2.1.
  }

In practice, such situations are very rare.

=back




--
Walk softly, and carry a BFG-9000.
  -- unknown