You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by gs...@apache.org on 2003/02/27 06:09:13 UTC
cvs commit: apr-site versioning.html
gstein 2003/02/26 21:09:12
Modified: . versioning.html
Log:
Three big areas:
- commentary on adding functions in minor releases and the
install-time implications
- information about compile- and run-time version checking
- information about parallel installations
Revision Changes Path
1.6 +198 -2 apr-site/versioning.html
Index: versioning.html
===================================================================
RCS file: /home/cvs/apr-site/versioning.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- versioning.html 13 Aug 2002 17:42:06 -0000 1.5
+++ versioning.html 27 Feb 2003 05:09:12 -0000 1.6
@@ -24,6 +24,8 @@
<li><a href="#binary">Binary Compatibility</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#strategy">Strategy</a></li>
+ <li><a href="#vsncheck">Version Checking</a></li>
+ <li><a href="#parallel">Parallel Installation</a></li>
<li><a href="#notes">Other Notes</a></li>
</ul>
@@ -183,7 +185,25 @@
signatures. Once an application begins to use a new function,
however, they will be unable to work against older minor
versions.
- <p></p>
+ <p>
+ It is tempting to say that introducing new functions might
+ create incompatibility across minor releases. If an
+ application takes advantage of an API that was introduced in
+ version 2.3 of a library, then it is not going to work
+ against version 2.2. However, we have stated that an any
+ application built against version 2.2 will continue to work
+ for all 2.x releases. Thus, an application that states
+ "requires 2.3 or later" is perfectly acceptable -- the user
+ or administrator simply upgrades the installed library to
+ 2.3. This is a safe operation and will not break any other
+ application that was using the 2.2 library.
+ </p>
+ <p>
+ In other words, yes an incompatibility arises by mandating
+ that a specific version needs to be installed. But in
+ practice, this will not be a problem since upgrading to
+ newer versions is always safe.
+ </p>
</dd>
<dt>New constants</dt>
@@ -279,6 +299,182 @@
<li>remove (deprecated) functions</li>
<li>fold together macro-ized function replacements</li>
</ul>
+
+ <h2><a name="vsncheck">Version Checking</a></h2>
+ <p>
+ In many cases, the user of a library will need to check the
+ version that they are compiling against, or that is being used
+ at runtime. Because of the strict rules of source and binary
+ compatibility, these checks can be simpler and more complicated
+ depending on what is needed.
+ </p>
+
+ <h3>Compile-time Checks</h3>
+ <p>
+ Libraries should make their version number available as
+ compile-time constants. For example:
+ </p>
+ <blockquote>
+ <tt>
+ #define FOO_MAJOR_VERSION 1
+ <br>
+ #define FOO_MINOR_VERSION 4
+ <br>
+ #define FOO_PATCH_VERSION 0
+ </tt>
+ </blockquote>
+ <p>
+ The above symbols are the minimum required for this
+ specification.
+ </p>
+ <p>
+ An application that desires, at compile-time, to decide on
+ whether and how to use a particular library feature needs to
+ only check two values: the major and the minor version. Since,
+ by definition, there are no API changes across patch versions,
+ that symbol can be safely ignored. Note that any kind of a check
+ for a minimum version will then pin that application to at least
+ that version. The application's installation mechanism should
+ then ensure that that minimal version has been installed (for
+ example, using RPM dependency checks).
+ </p>
+ <p>
+ If the feature changes across minor versions are source
+ compatible, but are (say) simply different choices of values to
+ pass into the library, then an application can support a wider
+ variety of installed libraries if it avoids compile-time checks.
+ </p>
+
+ <h3>Run-time Checks</h3>
+ <p>
+ A library meeting this specification should support a way for an
+ application to determine the library's version at
+ <em>run-time</em>. This will usually be emboded as a simple
+ function which returns the <tt>MAJOR</tt>, <tt>MINOR</tt>, and
+ <tt>PATCH</tt> triplet in some form.
+ </p>
+ <p>
+ Run-time checks are preferable in all cases. This type of check
+ enables an application to run against a wider variety of minor
+ releases of a library (the application is "<em>less
+ coupled</em>" to a particular library release). Of course, if an
+ application requires a function that was introduced in a later,
+ minor release, then the application will require that, at least,
+ that release is installed on the target system.
+ </p>
+ <p>
+ Run-time checks are particurly important if the application is
+ trying to determine if the library has a particular bug that may
+ need to be worked around, but has been fixed in a later
+ release. If the bug is fixed in a patch release, then the only
+ avenue for an application is to perform a runtime check. This is
+ because an application cannot require a specific patch level of
+ the library to be installed -- those libraries are perfectly
+ forward and backwards compatible, and the administrator is free
+ to choose any patch release, knowing that all applications will
+ continue to function properly. If the bug was fixed in a minor
+ release, then it is possible to use a compile-time check, but
+ that would create a tighter coupling to the library.
+ </p>
+
+ <h2><a name="parallel">Parallel Installation</a></h2>
+ <p>
+ <em>Parallel installation</em> refers to the ability to install
+ multiple versions of a library simultaneously -- they exist in
+ parallel. This document will not discuss the full rationale for
+ why this is important, but will instead detail how this
+ versioning specification maps onto those concepts. Please refer
+ to
+ <a href="http://www106.pair.com/rhp/parallel.html">Havoc
+ Pennington's document</a> for futher details and the rationale
+ behind this form of parallel installation.
+ </p>
+
+ <h3>Library Naming</h3>
+ <p>
+ On Unix-ish platforms, the library name should include the
+ <tt>MAJOR</tt> version number:
+ </p>
+ <blockquote>
+ <tt>libFOO-MAJOR.so</tt>
+ </blockquote>
+ <p>
+ This strategy allows an application to explicitly state which
+ version of the library that it wants to link against. If the
+ application was built for version 2 of the API, then it can link
+ against <tt>libFOO-2.so</tt>. If another application was built
+ against version 3 of the API, then it links against
+ <tt>libFOO-3.so</tt>. Since both libraries can reside on the
+ system at the same time, both applications' needs can be
+ satisfied.
+ </p>
+
+ <p>
+ Typically, shared libraries on Unix-ish platforms will set up
+ symlinks from the <tt>.so</tt> library to specific versions of
+ that library. For example:
+ </p>
+ <blockquote>
+ <tt>
+ libFOO-MAJOR.so -> libFOO-MAJOR.so.0
+ <br>
+ libFOO-MAJOR.so.0 -> libFOO-MAJOR.so.0.MINOR.PATCH
+ </tt>
+ </blockquote>
+ <p>
+ In this configuration, applications will be bound to the
+ <tt>.so.0</tt> library. The minor version does not come into
+ play here because we want applications to dynamically load and
+ link to the new library when a new minor version is
+ installed. Thus, the <tt>MINOR</tt> and the <tt>PATCH</tt>
+ values are relegated to the library name after the
+ <tt>.so.0</tt> portion.
+ </p>
+ <p>
+ The implication here is that build systems for libraries should
+ arrange to generate <tt>.so</tt> libraries matching the above
+ pattern.
+ </p>
+
+ <h3>Include Directories</h3>
+ <p>
+ The default installation directory for a library's include files
+ should specify the <tt>MAJOR</tt> version number, and should
+ normally be installed as a subdirectory in some standard
+ location. For example:
+ </p>
+ <blockquote>
+ <!-- stupid xemacs mode getting confused by forward slashes... -->
+ <tt>f;usrf;includef;FOO-MAJORf;</tt>
+ </blockquote>
+ <p>
+ An application can place the <tt>FOO-MAJOR</tt> directory on its
+ include path and include the files normally:
+ </p>
+ <blockquote>
+ <tt>
+ #include <FOO-stuff.h>
+ <br>
+ #include <FOO-more.h>
+ </tt>
+ </blockquote>
+ <p>
+ Depending upon the API that the application is designed to work
+ against, it can simply include different versions of the include
+ directory.
+ </p>
+
+ <h3>Other Files</h3>
+ <p>
+ <strong>NOTE:</strong>
+ There is no recommendation at this time for the best and
+ proper handling of, say, <tt>FOO-config</tt> types of files. Or
+ non-code types of files (e.g. things that typically get
+ installed into areas like <tt>f;usrf;shared</tt>).
+ </p>
+ <p>
+ Further thought and exploration is needed here.
+ </p>
<h2><a name="notes">Other Notes</a></h2>
<p>