stdcxx-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From se...@apache.org
Subject svn commit: r568772 - /incubator/stdcxx/site/versions.html
Date Wed, 22 Aug 2007 23:44:13 GMT
Author: sebor
Date: Wed Aug 22 16:44:13 2007
New Revision: 568772

URL: http://svn.apache.org/viewvc?rev=568772&view=rev
Log:
2007-08-22  Martin Sebor  <sebor@nebula.bco.roguewave.com>

	* versions.html: First draft of the stdcxx compatibility
	and versioning policy.

Added:
    incubator/stdcxx/site/versions.html   (with props)

Added: incubator/stdcxx/site/versions.html
URL: http://svn.apache.org/viewvc/incubator/stdcxx/site/versions.html?rev=568772&view=auto
==============================================================================
--- incubator/stdcxx/site/versions.html (added)
+++ incubator/stdcxx/site/versions.html Wed Aug 22 16:44:13 2007
@@ -0,0 +1,224 @@
+<html>
+    <head>
+        <title>STDCXX Compatibility and Versioning Policy</title>
+    </head>
+    <body>
+
+        <h1><center>STDCXX Compatibility and Versioning Policy</center></h1>
+        <h2><center>First Draft</center></h2>
+	<center>Last Updated: $Id:$</center>
+        <hr>
+
+        <h1>Compatibility</h1>
+        <p>
+
+The compatibility of  two software products is the  ability to replace one with
+the other  without affecting the  behavior of  the dependent software.  Most
+often, the issue  of compatibility is  concerned with different releases of the
+same product. Compatibility may also concern two functionally equivalent
+software products based on two independent projects. This type of compatibility
+is not the subject of this paper since  it typically  is not  reflected in
+versioning policies  of the products.
+
+        </p>
+        <p>
+
+Compatibility in software can be important at different levels. At the highest
+level, <i>functional  compatibility</i> determines whether two software
+components  behave  similarly  enough to  produce  the  same results  given the
+same input,  i.e., whether  they  are functionally equivalent.  An example of
+this  may be the compatibility of the POSIX <a
+href="http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html"><tt>pax</tt></a>
+and                                                                  <a
+href="http://www.opengroup.org/onlinepubs/007908799/xcu/tar.html"><tt>tar</tt></a>
+commands.
+
+        </p>
+        <p>
+
+<i>Source  compatibility</i>,  important  at  the source  code  level,
+determines whether  two software components  in their source  form are similar
+enough  so that any well-formed  program that uses  one of the components
+remains well-formed when the component is replaced with the other.    An
+example   of  source   compatible  components   are  two implementations  of
+the  C   Standard  library,  or   two  different implementations of the same
+Java specification.
+
+        </p>
+        <p>
+
+Beyond     functional    and    source     compatibility,    <i>binary
+compatibility</i> provides  additional guarantees especially important to
+programs that rely on shared libraries.
+
+        </p>
+        <p>
+
+For  the purposes  of compatibility,  a versioning  policy  is usually
+established by  the operating system.  The  policy precisely specifies how
+source  code changes must be  reflected in the  versions of shared libraries in
+order  for the latter to be  correctly interpreted by the operating system
+software and in order for each release of the library to  behave predictably
+when  linked  with and  used  by its  software clients.
+
+        </p>
+        <p>
+
+Even though  most releases of popular shared  libraries are versioned, not all
+libraries  necessarily need to be, and not  all of them always follow the
+established versioning policy. Different releases of shared libraries that do
+not use versioning often behave  as releases of the same product  based on
+independent projects  (which may or  may not be compatible), but may also
+behave as releases of completely independent and incompatible products.
+
+        </p>
+        <p>
+
+Releases of shared libraries that  do not follow the versioning policy do  not
+behave  consistently  with  those that  do,  and  may  behave unexpectedly to
+software that uses them with  the implicit assumption of using a properly
+versioned library.
+
+        </p>
+        <p>
+
+Software components  other than  shared libraries (such  as executable
+programs) often adopt the same policy as shared libraries, as a matter of
+convenience,  although the impact  of deviating from the  policy is often less
+dramatic than it is for shared libraries.
+
+        </p>
+
+        <h2>Binary Compatibility</h2>
+        <p>
+
+Binary compatibility  is the  compatibility of two  software products,
+typically shared  libraries, such  that one can  be replaced  with the other
+without  requiring any changes to the  dependent software. Thus, binary
+compatibility  provides  a  stronger guarantee  than  ordinary compatibility.
+
+        </p>
+        <p>
+
+The  binary compatibility  of  two  releases of  a  shared library  is
+determined by the binary size and layout of symbols such as functions, types,
+and objects,  exposed directly  or indirectly  as part  of the application
+programming            interface            (<a
+href="http://www.hyperdictionary.com/dictionary/Application+Program+Interface">API</a>)
+of  the  library.    Binary  compatibility  also  includes  functional
+compatibility,  i.e., the  compatibility of  the behavior  of  the new release
+with  the old release.  A  release of a product  whose API, at the     binary
+level     (sometimes    referred     to     as    <a
+href="http://www.hyperdictionary.com/dictionary/Application+Binary+Interface">ABI</a>)
+is a  superset of  that of  another release of  the same  product, and whose
+behavior is  compatible with that of the  other release, is said to be  binary
+compatible  with the other  release. Note that  with C++ features such  as
+templates and  inline functions, it is  possible for binary incompatible
+changes  to have no effect on  the symbols exposed by the shared library binary.
+
+        </p>
+
+        <h3>Forward Compatibility</h3>
+        <p>
+
+Some  changes in a  release of  a shared  library, such  as efficiency
+improvements  (or  regressions)  or  code refactoring,  that  have  no
+programmatically detectable effects in  behavior have no effect on the
+compatibility  of  that  release  of  the library  with  the  previous
+release. A  release of  a shared library  containing only such  and no other
+changes is said to  be forward compatible with the prior release of the same
+library.
+
+        </p>
+        <p>
+
+Note  that  adding  new  features  to  a library  is  not  a   forward
+compatible change since software written  to take advantage of the new features
+will  not function  correctly or at  all when the  library is replaced with
+another (not necessarily prior)  release not containing the  features.   Shared
+libraries  are  usually not  designed  to  be forward compatible.
+
+        </p>
+
+        <h3>Backward Compatibility</h3>
+        <p>
+
+Changes in a  release of shared library involving  the addition of new features
+such  as new functions, classes,  or objects, as  well as the removal of
+undefined behavior, i.e.,  changes that have no  effect on the  compatibility
+of  the  new  release of  the  shared library  with software that was built
+with a  prior release of the library, are said to  be backward (or  sometimes
+upward)  compatible. Software  built to rely on a  version of the shared
+library  containing these changes may not be  able to work  correctly or at
+all with other releaared
+library binary, are not backward compatible changes. Shared  libraries often,
+and system  libraries almost always, are designed to be backward compatible.
+
+        </p>
+        <p>
+
+Note that  frequently, even in technical literature,  the term forward
+Compatibility is  misused in contexts where  Backward Compatibility is really
+meant.
+
+        </p>
+
+        <h2>Source Compatibility</h2>
+        <p>
+
+Source compatible changes to software are such that do not require any
+modification to the  source code that depends on  the software. Source
+compatibility also implies  functional compatibility, although it does not
+imply binary compatibility.  Thus, source compatibility provides a weaker
+guarantee than binary compatibility.<br>
+
+        </p>
+        <p>
+
+Note  that source  compatible changes  to the  shared library  API are possible
+such that the binary layout of the data structures exposed by the library API
+changes, thus making such changes binary incompatible.
+
+        </p>
+
+        <h2>Functional Compatibility</h2>
+        <p>
+
+Functional compatibility is usually  not considered alone, but instead it is
+subsumed  by one of the other  compatibilities, typically binary compatibility.
+
+        </p>
+
+        <h1>Versioning Policy</h1>
+        <p>
+
+The  version  identifier  is defined  as  the  string
+<tt>&lt;major>.&lt;minor>.&lt;micro></tt>     with    the
   following
+semantics.
+
+        </p>
+        <p>
+
+The <i>major</i> number starts at 1 and is incremented by one for each new
+release  of a library that  is source or  binary incompatible with the previous
+release. Incrementing the  major number resets  both the minor and micro
+numbers to 0.
+
+        </p>
+        <p>
+
+The <i>minor</i> number starts at 0 and is incremented by one for each new
+release of  a library that is backward  but not forward compatible with the
+previous release. Incrementing  the minor number  resets the micro number to 0.
+
+        </p>
+        <p>
+
+The <i>micro</i> number starts at 0 and is incremented by one for each release
+of a  library  that  contains source  code  changes that  are forward
+compatible  with the  previous release. Incrementing the minor number resets
+the micro number to 0.
+
+        </p>
+    </body>
+</html>

Propchange: incubator/stdcxx/site/versions.html
------------------------------------------------------------------------------
    svn:keywords = Id



Mime
View raw message