Replaced /*! with /** in remaining Doxygen headers, and removed intentation of overviews [a-c].
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52448 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -6,178 +6,168 @@
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/*!
|
||||
/**
|
||||
|
||||
@page overview_backwardcompat Backward compatibility
|
||||
@page overview_backwardcompat Backwards 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.
|
||||
|
||||
@li @ref overview_backwardcompat_versionnumbering
|
||||
@li @ref overview_backwardcompat_sourcecompat
|
||||
@li @ref overview_backwardcompat_libbincompat
|
||||
@li @ref overview_backwardcompat_appbincompat
|
||||
@li @ref overview_backwardcompat_versionnumbering
|
||||
@li @ref overview_backwardcompat_sourcecompat
|
||||
@li @ref overview_backwardcompat_libbincompat
|
||||
@li @ref overview_backwardcompat_appbincompat
|
||||
|
||||
|
||||
<hr>
|
||||
<hr>
|
||||
|
||||
|
||||
@section overview_backwardcompat_versionnumbering The version numbering scheme
|
||||
@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
|
||||
@vertatim
|
||||
major.minor.release.sub-release
|
||||
@endverbatim
|
||||
|
||||
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 @e minor, e.g.
|
||||
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 2.6.x releases, such as 2.6.1 and 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 @e minor, for
|
||||
example 2.7.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: 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 overview_backwardcompat_sourcecompat 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
|
||||
wxWidgets @c 2.6.0 then it should also compile fine with all later @c 2.6.x versions.
|
||||
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 2.8.0 then it should
|
||||
also compile fine with all later 2.8.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.
|
||||
The converse is also true providing you avoid any new features not present in
|
||||
the earlier version. For example if you develop using 2.6.1 your program will
|
||||
compile fine with wxWidgets 2.8.0 providing you don't use any 2.8.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
|
||||
@ref overview_backwardcompat_libbincompat 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 2.4.x, 2.6.x and 2.8.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_6
|
||||
// deprecated feature
|
||||
...
|
||||
#endif
|
||||
@endcode
|
||||
#endif
|
||||
@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_X_X macro is set to 1 for the previous
|
||||
stable branch, for example in 2.8.x, @c WXWIN_COMPATIBILITY_2_6 = 1. For the
|
||||
next earlier stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_4 = 0
|
||||
for 2.8.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-compat26 and @c --enable-compat24 options to
|
||||
configure.
|
||||
|
||||
They can be useful in two ways:
|
||||
They can be useful in two ways:
|
||||
|
||||
@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.
|
||||
@li Changing @c WXWIN_COMPATIBILITY_2_6 to 0 can be useful to find uses of
|
||||
deprecated features in your program that should eventually be removed.
|
||||
@li Changing @c WXWIN_COMPATIBILITY_2_4 to 1 can be useful to compile a program
|
||||
developed using 2.4.x that no longer compiles with 2.8.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.
|
||||
|
||||
|
||||
|
||||
@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.
|
||||
@section overview_backwardcompat_libbincompat Library Binary Compatibility
|
||||
|
||||
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 some platforms, releases from a stable branch are not only source level
|
||||
compatible but can also be binary compatible.
|
||||
|
||||
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
|
||||
install just wxWidgets @c 2.6.2 shared libraries, and all the applications
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
For example, suppose several applications are installed on a system requiring
|
||||
wxWidgets 2.6.0, 2.6.1 and 2.6.2. Since 2.6.2 is backward compatible with the
|
||||
earlier versions, it should be enough to install just wxWidgets 2.6.2 shared
|
||||
libraries, and all the applications should be able to use them. If binary
|
||||
compatibility is not supported, then all the required versions 2.6.0, 2.6.1 and
|
||||
2.6.2 must be installed side by side.
|
||||
|
||||
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
|
||||
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.
|
||||
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 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.
|
||||
|
||||
|
||||
|
||||
@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
|
||||
with shared libraries of a later binary compatible version, for example @c 2.6.2.
|
||||
The converse can also be useful however. That is, it can be useful for a
|
||||
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.
|
||||
@section overview_backwardcompat_appbincompat Application Binary Compatibility
|
||||
|
||||
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
|
||||
though the same code would compile fine against an earlier version.
|
||||
The most important aspect of binary compatibility is that applications compiled
|
||||
with one version of wxWidgets, e.g. 2.6.1, continue to work with shared
|
||||
libraries of a later binary compatible version, for example 2.6.2. The converse
|
||||
can also be useful however. That is, it can be useful for a developer using a
|
||||
later version, e.g. 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 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.
|
||||
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 though the same
|
||||
code would compile fine against an earlier version.
|
||||
|
||||
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.
|
||||
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 2.6.0.
|
||||
|
||||
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.
|
||||
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 2.6.x using
|
||||
wxWidgets 2.8.x.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user