docs/latex/wx/backwardcompat.tex

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