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