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
parent
a7ea35b011
commit
a61b8ecbba
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 topics.tex
|
||||
\input portnote.tex
|
||||
\input backwardcompat.tex
|
||||
% Deprecated classes
|
||||
%\input proplist.tex
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user