diff --git a/docs/latex/wx/backwardcompat.tex b/docs/latex/wx/backwardcompat.tex new file mode 100644 index 0000000000..c81e913a5a --- /dev/null +++ b/docs/latex/wx/backwardcompat.tex @@ -0,0 +1,175 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: backwardcompat.tex +%% Purpose: Explains how much and what kind of backward compatibility users +%% can expect +%% Author: M.J.Wetherell +%% RCS-ID: $Id$ +%% Copyright: 2005 M.J.Wetherell +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Backward compatibility}\label{backwardcompatibility} +\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}% +\setfooter{\thepage}{}{}{}{}{\thepage}% + +Many of the GUIs and platforms supported by wxWidgets are continuously +evolving, and some of the new platforms wxWidgets now supports were quite +unimaginable even a few years ago. In this environment wxWidgets must also +evolve in order to support these new features and platforms. + +However the goal of wxWidgets is not only to provide a consistent +programming interface across many platforms, but also to provide an +interface that is reasonably stable over time, to help protect its users +from some of the uncertainty of the future. + +{\large {\bf The version numbering scheme}}\label{versionnumbering} + +wxWidgets version numbers can have up to four components, with trailing +zeros sometimes omitted: + +\begin{verbatim} + major.minor.release.sub-release +\end{verbatim} + +A {\em stable} release of wxWidgets will have an even number for {\tt +minor}, e.g. {\tt 2.6.0}. + +Stable, in this context, means that the API is not changing. In truth, some +changes are permitted, but only those that are backward compatible. For +example, you can expect later {\tt 2.6.x.x} releases, such as {\tt 2.6.1} +and {\tt 2.6.2} to be backward compatible with their predecessor. + +When it becomes necessary to make changes which are not wholly backward +compatible, the stable branch is forked, creating a new {\em development} +branch of wxWidgets. This development branch will have an odd number +for {\tt minor}, for example {\tt 2.7.x.x}. Releases from this branch are +known as {\em development snapshots}. + +The stable branch and the development branch will then be developed in +parallel for some time. When it is no longer useful to continue developing +the stable branch, the development branch is renamed and becomes a new +stable branch, for example {\tt 2.8.0}. And the process begins again. + +This is how the tension between keeping the interface stable, and allowing +the library to evolve is managed. + +You can expect the versions with the same major and {\em even} minor +version number to be compatible, but between minor versions there will be +incompatibilities. Compatibility is not broken gratuitously however, so +many applications will require no changes or only small changes to work +with the new version. + +{\large {\bf Source level compatibility}}\label{sourcecompatibility} + +Later releases from a stable branch are backward compatible with earlier +releases from the same branch at the {\em source} level. + +This means that, for example, if you develop your application using +wxWidgets {\tt 2.6.0} then it should also compile fine with all later {\tt +2.6.x} versions. The converse is also true providing you avoid any new +features not present in the earlier version. For example if you develop +using {\tt 2.6.1} your program will compile fine with wxWidgets {\tt 2.6.0} +providing you don't use any {\tt 2.6.1} specific features. + +For some platforms binary compatibility is also supported, see 'Library +binary compatibility' below. + +Between minor versions, for example between {\tt 2.2.x}, {\tt 2.4.x} and {\tt +2.6.x}, there will be some incompatibilities. Wherever possible the old way +of doing something is kept alongside the new for a time wrapped inside: + +\begin{verbatim} + #if WXWIN_COMPATIBILITY_2_4 + /* deprecated feature */ + ... + #endif +\end{verbatim} + +By default the {\tt WXWIN\_COMPATIBILITY{\it \_X\_X}} macro is set +to 1 for the previous stable branch, for example +in {\tt 2.6.x} {\tt WXWIN\_COMPATIBILITY\_2\_4 = 1}. For the next earlier +stable branch the default is 0, so {\tt WXWIN\_COMPATIBILITY\_2\_2 = 0} +for {\tt 2.6.x}. Earlier than that, obsolete features are removed. + +These macros can be changed in {\tt setup.h}. Or on UNIX-like systems you can +set them using the {\tt --disable-compat24} and {\tt --enable-compat22} +options to {\tt configure}. + +They can be useful in two ways: + +\begin{enumerate} +\item Changing {\tt WXWIN\_COMPATIBILITY\_2\_4} to 0 can be useful to +find uses of deprecated features in your program. +\item Changing {\tt WXWIN\_COMPATIBILITY\_2\_2} to 1 can be useful to +compile a program developed using {\tt 2.2.x} that no longer compiles +with {\tt 2.6.x}. +\end{enumerate} + +A program requiring one of these macros to be 1 will become +incompatible with some future version of wxWidgets, and you should consider +updating it. + +{\large {\bf Library binary compatibility}}\label{libbincompatibility} + +For some platforms, releases from a stable branch are not only source level +compatible but can also be {\em binary compatible}. + +Binary compatibility makes it possible to get the maximum benefit from +using shared libraries, also known as dynamic link libraries (DLLs) on +Windows or dynamic shared libraries on OS X. + +For example, suppose several applications are installed on a system requiring +wxWidgets {\tt 2.6.0}, {\tt 2.6.1} and {\tt 2.6.2}. Since {\tt 2.6.2} is +backward compatible with the earlier versions, it should be enough to +install just wxWidgets {\tt 2.6.2} shared libraries, and all the applications +should be able to use them. If binary compatibility is not supported, then all +the required versions {\tt 2.6.0}, {\tt 2.6.1} and {\tt 2.6.2} must be +installed side by side. + +Archiving this, without the user being required to have the source code +and recompile everything, places many extra constraints on the changes +that can be made within the stable branch. So it is not support for all +platforms, and not for all versions of wxWidgets. To date it has mainly +been supported by wxGTK for UNIX-like platforms. + +Another practical consideration is that for binary compatibility to work, +all the applications and libraries must have been compiled with compilers +that are capable of producing compatible code; that is, they must use the +same ABI (Application Binary Interface). Unfortunately most different C++ +compilers do not produce code compatible with each other, and often even +different versions of the same compiler are not compatible. + +{\large {\bf Application binary compatibility}}\label{appbincompatibility} + +The most important aspect of binary compatibility is that applications +compiled with one version of wxWidgets, e.g. {\tt 2.6.1}, continue to work +with shared libraries of a later binary compatible version, for example {\tt +2.6.2}. + +The converse can also be useful however. That is, it can be useful for a +developer using a later version, e.g. {\tt 2.6.2} to be able to create binary +application packages that will work with all binary compatible versions of +the shared library starting with, for example {\tt 2.6.0}. + +To do this the developer must, of course, avoid any features not available +in the earlier versions. However this is not necessarily enough; in some +cases an application compiled with a later version may depend on it even +though the same code would compile fine against an earlier version. +% thinks: a situation we should try to avoid. + +To help with this, a preprocessor symbol {\tt wxABI\_VERSION} can be defined +during the compilation of the application (this would usually be done in the +application's makefile or project settings). It should be set to the lowest +version that is being targeted, as a number with two decimal digits for each +component, for example {\tt wxABI\_VERSION=20600} for {\tt 2.6.0}. + +Setting {\tt wxABI\_VERSION} should prevent the application from implicitly +depending on a later version of wxWidgets, and also disables any new features +in the API, giving a compile time check that the source is compatible with +the versions of wxWidgets being targeted. + +Uses of {\tt wxABI\_VERSION} are stripped out of the wxWidgets sources when +each new development branch is created. Therefore it is only useful to help +achieve compatibility with earlier versions with the same major +and {\em even} minor version numbers. It won't, for example, help you write +code compatible with {\tt 2.4.x} using wxWidgets {\tt 2.6.x}. diff --git a/docs/latex/wx/manual.tex b/docs/latex/wx/manual.tex index d821104044..2bf4ccffc1 100644 --- a/docs/latex/wx/manual.tex +++ b/docs/latex/wx/manual.tex @@ -669,6 +669,7 @@ That's all there is to it! \input category.tex \input topics.tex \input portnote.tex +\input backwardcompat.tex % Deprecated classes %\input proplist.tex