docs/doxygen/overviews/backwardcompatibility.h

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