docs/doxygen/overviews/backwardcompatibility.h

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