Add chapter on backward compatibility
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@34816 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Michael Wetherell
175
docs/latex/wx/backwardcompat.tex
Normal file
175
docs/latex/wx/backwardcompat.tex
Normal file
@@ -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}.
|
||||||
@@ -669,6 +669,7 @@ That's all there is to it!
|
|||||||
\input category.tex
|
\input category.tex
|
||||||
\input topics.tex
|
\input topics.tex
|
||||||
\input portnote.tex
|
\input portnote.tex
|
||||||
|
\input backwardcompat.tex
|
||||||
% Deprecated classes
|
% Deprecated classes
|
||||||
%\input proplist.tex
|
%\input proplist.tex
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user