More doxygen topic overview cleanup.

[wxWidgets.git] / docs / doxygen / overviews / backwardcompatibility.h

diff --git a/docs/doxygen/overviews/backwardcompatibility.h b/docs/doxygen/overviews/backwardcompatibility.h
index df594745e5faed578c15cd850a6ee6f517dfa390..49b5984db64ea8c16107b2b1b98bc5f08b8f8d48 100644 (file)
--- a/docs/doxygen/overviews/backwardcompatibility.h
+++ b/docs/doxygen/overviews/backwardcompatibility.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        backwardcompatibility
+// Name:        backwardcompatibility.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -7,104 +7,122 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /*!
 /////////////////////////////////////////////////////////////////////////////
 
 /*!

- 
- @page backwardcompatibility_overview Backward compatibility
- 
+
+ @page overview_backwardcompat Backward compatibility
+

  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.
  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.
  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.

- @ref versionnumbering_overview
- @ref sourcecompatibility_overview
- @ref libbincompatibility_overview
- @ref appbincompatibility_overview
- 
- 
- @section versionnumbering The version numbering scheme
- 
+
+ @li @ref overview_backwardcompat_versionnumbering
+ @li @ref overview_backwardcompat_sourcecompat
+ @li @ref overview_backwardcompat_libbincompat
+ @li @ref overview_backwardcompat_appbincompat
+
+
+ <hr>
+
+
+ @section overview_backwardcompat_versionnumbering The version numbering scheme
+

  wxWidgets version numbers can have up to four components, with trailing
  zeros sometimes omitted:
  wxWidgets version numbers can have up to four components, with trailing
  zeros sometimes omitted:

- 
+

  @code
  major.minor.release.sub-release
  @endcode
  @code
  major.minor.release.sub-release
  @endcode

- 
+

  A stable release of wxWidgets will have an even number for @c minor, e.g. @c 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 @c 2.6.x.x releases, such as @c 2.6.1
  and @c 2.6.2 to be backward compatible with their predecessor.
  A stable release of wxWidgets will have an even number for @c minor, e.g. @c 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 @c 2.6.x.x releases, such as @c 2.6.1
  and @c 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 development
  branch of wxWidgets. This development branch will have an odd number
  for @c minor, for example @c 2.7.x.x. Releases from this branch are
  known as development snapshots.
  When it becomes necessary to make changes which are not wholly backward
  compatible, the stable branch is forked, creating a new development
  branch of wxWidgets. This development branch will have an odd number
  for @c minor, for example @c 2.7.x.x. Releases from this branch are
  known as 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 @c 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.
  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 @c 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 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.
  You can expect the versions with the same major and 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.

- 
- @section sourcecompatibility Source level compatibility
- 
+
+
+ @section overview_backwardcompat_sourcecompat Source level compatibility
+

  Later releases from a stable branch are backward compatible with earlier
  releases from the same branch at the source level.
  This means that, for example, if you develop your application using
  Later releases from a stable branch are backward compatible with earlier
  releases from the same branch at the source level.
  This means that, for example, if you develop your application using

- 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
+ 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

  features not present in the earlier version. For example if you develop
  using @c 2.6.1 your program will compile fine with wxWidgets @c 2.6.0
  providing you don't use any @c 2.6.1 specific features.
  features not present in the earlier version. For example if you develop
  using @c 2.6.1 your program will compile fine with wxWidgets @c 2.6.0
  providing you don't use any @c 2.6.1 specific features.

+

  For some platforms binary compatibility is also supported, see 'Library
  binary compatibility' below.
  For some platforms binary compatibility is also supported, see 'Library
  binary compatibility' below.

- 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
- of doing something is kept alongside the new for a time wrapped inside:
- 
+
+ 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 of doing something 
+ is kept alongside the new for a time wrapped inside:
+

  @code
  #if WXWIN_COMPATIBILITY_2_4
  @code
  #if WXWIN_COMPATIBILITY_2_4

-         /* deprecated feature */
-         ...
-     #endif
+    // deprecated feature
+    ...
+ #endif

  @endcode
  @endcode

- 
+

  By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
  to 1 for the previous stable branch, for example
  in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
  stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
  for @c 2.6.x. Earlier than that, obsolete features are removed.
  By default the @c WXWIN_COMPATIBILITY@e _X_X macro is set
  to 1 for the previous stable branch, for example
  in @c 2.6.x @c WXWIN_COMPATIBILITY_2_4 = 1. For the next earlier
  stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_2 = 0
  for @c 2.6.x. Earlier than that, obsolete features are removed.

+

  These macros can be changed in @c setup.h. Or on UNIX-like systems you can
  set them using the @c --disable-compat24 and @c --enable-compat22
  options to @c configure.
  These macros can be changed in @c setup.h. Or on UNIX-like systems you can
  set them using the @c --disable-compat24 and @c --enable-compat22
  options to @c configure.

+

  They can be useful in two ways:
  They can be useful in two ways:

- 
- 
-  Changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
- find uses of deprecated features in your program.
-  Changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
- compile a program developed using @c 2.2.x that no longer compiles
- with @c 2.6.x.
- 
+
+ @li changing @c WXWIN_COMPATIBILITY_2_4 to 0 can be useful to
+     find uses of deprecated features in your program.
+ @li changing @c WXWIN_COMPATIBILITY_2_2 to 1 can be useful to
+     compile a program developed using @c 2.2.x that no longer compiles
+     with @c 2.6.x.

  
  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.
  
  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.

+
+

  
  

- @section libbincompatibility Library binary compatibility
+ @section overview_backwardcompat_libbincompat Library binary compatibility

  
  For some platforms, releases from a stable branch are not only source level
  compatible but can also be binary compatible.
  
  For some platforms, releases from a stable branch are not only source level
  compatible but can also be 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.
  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 @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
  backward compatible with the earlier versions, it should be enough to
  For example, suppose several applications are installed on a system requiring
  wxWidgets @c 2.6.0, @c 2.6.1 and @c 2.6.2. Since @c 2.6.2 is
  backward compatible with the earlier versions, it should be enough to


@@ -112,19 +130,24 @@
  should be able to use them. If binary compatibility is not supported, then all
  the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
  installed side by side.
  should be able to use them. If binary compatibility is not supported, then all
  the required versions @c 2.6.0, @c 2.6.1 and @c 2.6.2 must be
  installed side by side.

+

  Achieving 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 supported for all
  platforms, and not for all versions of wxWidgets. To date it has mainly
  been supported by wxGTK for UNIX-like platforms.
  Achieving 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 supported 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
  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
+ 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.
  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.

+
+

  
  

- @section appbincompatibility Application binary compatibility
+ @section overview_backwardcompat_appbincompat Application binary compatibility

  
  The most important aspect of binary compatibility is that applications
  compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work
  
  The most important aspect of binary compatibility is that applications
  compiled with one version of wxWidgets, e.g. @c 2.6.1, continue to work


@@ -133,25 +156,28 @@
  developer using a later version, e.g. @c 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 @c 2.6.0.
  developer using a later version, e.g. @c 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 @c 2.6.0.

+

  To do this the developer must, of course, avoid any features not available
  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
+ 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.
  though the same code would compile fine against an earlier version.

+

  To help with this, a preprocessor symbol @c 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 @c wxABI_VERSION=20600 for @c 2.6.0.
  To help with this, a preprocessor symbol @c 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 @c wxABI_VERSION=20600 for @c 2.6.0.

+

  Setting @c 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.
  Setting @c 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 @c 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 even minor version numbers. It won't, for example, help you write
  code compatible with @c 2.4.x using wxWidgets @c 2.6.x.
  Uses of @c 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 even minor version numbers. It won't, for example, help you write
  code compatible with @c 2.4.x using wxWidgets @c 2.6.x.

- 
- */
- 
- 
+
+*/
+