From cvs-return-4801-apmail-apr-cvs-archive=apr.apache.org@apr.apache.org Thu Feb 27 05:09:15 2003 Return-Path: Delivered-To: apmail-apr-cvs-archive@apr.apache.org Received: (qmail 29043 invoked by uid 500); 27 Feb 2003 05:09:14 -0000 Mailing-List: contact cvs-help@apr.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Reply-To: dev@apr.apache.org Delivered-To: mailing list cvs@apr.apache.org Received: (qmail 29030 invoked by uid 500); 27 Feb 2003 05:09:14 -0000 Delivered-To: apmail-apr-site-cvs@apache.org Date: 27 Feb 2003 05:09:13 -0000 Message-ID: <20030227050913.12395.qmail@icarus.apache.org> From: gstein@apache.org To: apr-site-cvs@apache.org Subject: cvs commit: apr-site versioning.html X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 @@
  • Binary Compatibility
  • Examples
  • Strategy
    • +
  • Version Checking
    • +
  • Parallel Installation
  • Other Notes
    • @@ -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. -

    +

    + 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. +

    +

    + 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. +

    New constants
    @@ -279,6 +299,182 @@
  • remove (deprecated) functions
  • fold together macro-ized function replacements
    • + +

    Version Checking

    +

    + 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. +

    + +

    Compile-time Checks

    +

    + Libraries should make their version number available as + compile-time constants. For example: +

    +
    + + #define FOO_MAJOR_VERSION 1 +
    + #define FOO_MINOR_VERSION 4 +
    + #define FOO_PATCH_VERSION 0 +     +
    +

    + The above symbols are the minimum required for this + specification. +

    +

    + 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). +

    +

    + 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. +

    + +

    Run-time Checks

    +

    + A library meeting this specification should support a way for an + application to determine the library's version at + run-time. This will usually be emboded as a simple + function which returns the MAJOR, MINOR, and + PATCH triplet in some form. +

    +

    + 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 "less + coupled" 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. +

    +

    + 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. +

    + +

    Parallel Installation

    +

    + Parallel installation 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 + Havoc + Pennington's document for futher details and the rationale + behind this form of parallel installation. +

    + +

    Library Naming

    +

    + On Unix-ish platforms, the library name should include the + MAJOR version number: +

    +
    + libFOO-MAJOR.so +
    +

    + 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 libFOO-2.so. If another application was built + against version 3 of the API, then it links against + libFOO-3.so. Since both libraries can reside on the + system at the same time, both applications' needs can be + satisfied. +

    + +

    + Typically, shared libraries on Unix-ish platforms will set up + symlinks from the .so library to specific versions of + that library. For example: +

    +
    + + libFOO-MAJOR.so -> libFOO-MAJOR.so.0 +
    + libFOO-MAJOR.so.0 -> libFOO-MAJOR.so.0.MINOR.PATCH +     +
    +

    + In this configuration, applications will be bound to the + .so.0 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 MINOR and the PATCH + values are relegated to the library name after the + .so.0 portion. +

    +

    + The implication here is that build systems for libraries should + arrange to generate .so libraries matching the above + pattern. +

    + +

    Include Directories

    +

    + The default installation directory for a library's include files + should specify the MAJOR version number, and should + normally be installed as a subdirectory in some standard + location. For example: +

    +
    + + f;usrf;includef;FOO-MAJORf; +
    +

    + An application can place the FOO-MAJOR directory on its + include path and include the files normally: +

    +
    + + #include <FOO-stuff.h> +
    + #include <FOO-more.h> +     +
    +

    + Depending upon the API that the application is designed to work + against, it can simply include different versions of the include + directory. +

    + +

    Other Files

    +

    + NOTE: + There is no recommendation at this time for the best and + proper handling of, say, FOO-config types of files. Or + non-code types of files (e.g. things that typically get + installed into areas like f;usrf;shared). +

    +

    + Further thought and exploration is needed here. +

    Other Notes