1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: backwardcompat.tex 3%% Purpose: Explains how much and what kind of backward compatibility users 4%% can expect 5%% Author: M.J.Wetherell 6%% RCS-ID: $Id: backwardcompat.tex 35184 2005-08-13 20:47:26Z MW $ 7%% Copyright: 2005 M.J.Wetherell 8%% License: wxWindows license 9%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 10 11\section{Backward compatibility}\label{backwardcompatibility} 12 13Many of the GUIs and platforms supported by wxWidgets are continuously 14evolving, and some of the new platforms wxWidgets now supports were quite 15unimaginable even a few years ago. In this environment wxWidgets must also 16evolve in order to support these new features and platforms. 17 18However the goal of wxWidgets is not only to provide a consistent 19programming interface across many platforms, but also to provide an 20interface that is reasonably stable over time, to help protect its users 21from some of the uncertainty of the future. 22 23\subsection{The version numbering scheme}\label{versionnumbering} 24 25wxWidgets version numbers can have up to four components, with trailing 26zeros sometimes omitted: 27 28\begin{verbatim} 29 major.minor.release.sub-release 30\end{verbatim} 31 32A {\em stable} release of wxWidgets will have an even number for {\tt 33minor}, e.g. {\tt 2.6.0}. 34 35Stable, in this context, means that the API is not changing. In truth, some 36changes are permitted, but only those that are backward compatible. For 37example, you can expect later {\tt 2.6.x.x} releases, such as {\tt 2.6.1} 38and {\tt 2.6.2} to be backward compatible with their predecessor. 39 40When it becomes necessary to make changes which are not wholly backward 41compatible, the stable branch is forked, creating a new {\em development} 42branch of wxWidgets. This development branch will have an odd number 43for {\tt minor}, for example {\tt 2.7.x.x}. Releases from this branch are 44known as {\em development snapshots}. 45 46The stable branch and the development branch will then be developed in 47parallel for some time. When it is no longer useful to continue developing 48the stable branch, the development branch is renamed and becomes a new 49stable branch, for example {\tt 2.8.0}. And the process begins again. 50 51This is how the tension between keeping the interface stable, and allowing 52the library to evolve is managed. 53 54You can expect the versions with the same major and {\em even} minor 55version number to be compatible, but between minor versions there will be 56incompatibilities. Compatibility is not broken gratuitously however, so 57many applications will require no changes or only small changes to work 58with the new version. 59 60\subsection{Source level compatibility}\label{sourcecompatibility} 61 62Later releases from a stable branch are backward compatible with earlier 63releases from the same branch at the {\em source} level. 64 65This means that, for example, if you develop your application using 66wxWidgets {\tt 2.6.0} then it should also compile fine with all later {\tt 672.6.x} versions. The converse is also true providing you avoid any new 68features not present in the earlier version. For example if you develop 69using {\tt 2.6.1} your program will compile fine with wxWidgets {\tt 2.6.0} 70providing you don't use any {\tt 2.6.1} specific features. 71 72For some platforms binary compatibility is also supported, see 'Library 73binary compatibility' below. 74 75Between minor versions, for example between {\tt 2.2.x}, {\tt 2.4.x} and {\tt 762.6.x}, there will be some incompatibilities. Wherever possible the old way 77of doing something is kept alongside the new for a time wrapped inside: 78 79\begin{verbatim} 80 #if WXWIN_COMPATIBILITY_2_4 81 /* deprecated feature */ 82 ... 83 #endif 84\end{verbatim} 85 86By default the {\tt WXWIN\_COMPATIBILITY{\it \_X\_X}} macro is set 87to 1 for the previous stable branch, for example 88in {\tt 2.6.x} {\tt WXWIN\_COMPATIBILITY\_2\_4 = 1}. For the next earlier 89stable branch the default is 0, so {\tt WXWIN\_COMPATIBILITY\_2\_2 = 0} 90for {\tt 2.6.x}. Earlier than that, obsolete features are removed. 91 92These macros can be changed in {\tt setup.h}. Or on UNIX-like systems you can 93set them using the {\tt --disable-compat24} and {\tt --enable-compat22} 94options to {\tt configure}. 95 96They can be useful in two ways: 97 98\begin{enumerate} 99\item Changing {\tt WXWIN\_COMPATIBILITY\_2\_4} to 0 can be useful to 100find uses of deprecated features in your program. 101\item Changing {\tt WXWIN\_COMPATIBILITY\_2\_2} to 1 can be useful to 102compile a program developed using {\tt 2.2.x} that no longer compiles 103with {\tt 2.6.x}. 104\end{enumerate} 105 106A program requiring one of these macros to be 1 will become 107incompatible with some future version of wxWidgets, and you should consider 108updating it. 109 110\subsection{Library binary compatibility}\label{libbincompatibility} 111 112For some platforms, releases from a stable branch are not only source level 113compatible but can also be {\em binary compatible}. 114 115Binary compatibility makes it possible to get the maximum benefit from 116using shared libraries, also known as dynamic link libraries (DLLs) on 117Windows or dynamic shared libraries on OS X. 118 119For example, suppose several applications are installed on a system requiring 120wxWidgets {\tt 2.6.0}, {\tt 2.6.1} and {\tt 2.6.2}. Since {\tt 2.6.2} is 121backward compatible with the earlier versions, it should be enough to 122install just wxWidgets {\tt 2.6.2} shared libraries, and all the applications 123should be able to use them. If binary compatibility is not supported, then all 124the required versions {\tt 2.6.0}, {\tt 2.6.1} and {\tt 2.6.2} must be 125installed side by side. 126 127Achieving this, without the user being required to have the source code 128and recompile everything, places many extra constraints on the changes 129that can be made within the stable branch. So it is not supported for all 130platforms, and not for all versions of wxWidgets. To date it has mainly 131been supported by wxGTK for UNIX-like platforms. 132 133Another practical consideration is that for binary compatibility to work, 134all the applications and libraries must have been compiled with compilers 135that are capable of producing compatible code; that is, they must use the 136same ABI (Application Binary Interface). Unfortunately most different C++ 137compilers do not produce code compatible with each other, and often even 138different versions of the same compiler are not compatible. 139 140\subsection{Application binary compatibility}\label{appbincompatibility} 141 142The most important aspect of binary compatibility is that applications 143compiled with one version of wxWidgets, e.g. {\tt 2.6.1}, continue to work 144with shared libraries of a later binary compatible version, for example {\tt 1452.6.2}. 146 147The converse can also be useful however. That is, it can be useful for a 148developer using a later version, e.g. {\tt 2.6.2} to be able to create binary 149application packages that will work with all binary compatible versions of 150the shared library starting with, for example {\tt 2.6.0}. 151 152To do this the developer must, of course, avoid any features not available 153in the earlier versions. However this is not necessarily enough; in some 154cases an application compiled with a later version may depend on it even 155though the same code would compile fine against an earlier version. 156% thinks: a situation we should try to avoid. 157 158To help with this, a preprocessor symbol {\tt wxABI\_VERSION} can be defined 159during the compilation of the application (this would usually be done in the 160application's makefile or project settings). It should be set to the lowest 161version that is being targeted, as a number with two decimal digits for each 162component, for example {\tt wxABI\_VERSION=20600} for {\tt 2.6.0}. 163 164Setting {\tt wxABI\_VERSION} should prevent the application from implicitly 165depending on a later version of wxWidgets, and also disables any new features 166in the API, giving a compile time check that the source is compatible with 167the versions of wxWidgets being targeted. 168 169Uses of {\tt wxABI\_VERSION} are stripped out of the wxWidgets sources when 170each new development branch is created. Therefore it is only useful to help 171achieve compatibility with earlier versions with the same major 172and {\em even} minor version numbers. It won't, for example, help you write 173code compatible with {\tt 2.4.x} using wxWidgets {\tt 2.6.x}. 174