apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gst...@apache.org
Subject cvs commit: apr-site versioning.html
Date Thu, 27 Feb 2003 05:09:13 GMT
gstein      2003/02/26 21:09:12

  Modified:    .        versioning.html
  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>
  @@ -183,7 +185,25 @@
   	signatures. Once an application begins to use a new function,
   	however, they will be unable to work against older minor
  -	<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>
         <dt>New constants</dt>
  @@ -279,6 +299,182 @@
         <li>remove (deprecated) functions</li>
         <li>fold together macro-ized function replacements</li>
  +    <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>,
  +      <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>&#2f;usr&#2f;include&#2f;FOO-MAJOR&#2f;</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 &lt;FOO-stuff.h&gt;
  +        <br>
  +        #include &lt;FOO-more.h&gt;
  +      </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>&#2f;usr&#2f;shared</tt>).
  +    </p>
  +    <p>
  +      Further thought and exploration is needed here.
  +    </p>
       <h2><a name="notes">Other Notes</a></h2>

View raw message