cheng/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Backwards Compatibility programming guide.

Browse Source 
No real changes, basically just update wxWidgets versions used
to more recent ones.

(cherry picked from commit cf43c97f7d4e61f0931b503b3a06e73c9cc1484a)
This commit is contained in:
PB 2022-11-01 18:18:31 +01:00 committed by Vadim Zeitlin
parent 173c8f9d5c
commit 8ad526cf04
1 changed files with 31 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/doxygen/overviews/backwardcompatibility.h
View File

@ -11,15 +11,9 @@
@tableofcontents
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
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.
reasonably stable over time.
@ -33,20 +27,20 @@ major.minor.release.sub-release
@endverbatim
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,
3.2.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
example, you can expect later 3.2.x releases, such as 3.2.1 and 3.2.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 @e minor, for
example 2.7.x. Releases from this branch are known as development snapshots.
example 3.3.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: 2.8.0. And the process begins again. This is how the tension between
example: 3.4.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
@ -59,43 +53,43 @@ require no changes or only small changes to work with the new version.
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.
example, if you develop your application using wxWidgets 3.2.0 then it should
also compile fine with all later 3.2.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 2.6.1 your program will
compile fine with wxWidgets 2.8.0 providing you don't use any 2.8.1 specific
the earlier version. For example if you develop using 3.3.1 your program will
compile fine with wxWidgets 3.2.0 providing you don't use any 3.3.1 specific
features.
For some platforms binary compatibility is also supported, see
@ref overview_backwardcompat_libbincompat below.
Between minor versions, for example between 2.4.x, 2.6.x and 2.8.x, there will
Between minor versions, for example between 2.8.x, 3.0.x and 3.2.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_6
#if WXWIN_COMPATIBILITY_3_0
// deprecated feature
...
#endif
@endcode
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.
stable branch, for example in 3.2.x, @c WXWIN_COMPATIBILITY_3_0 = 1. For the
next earlier stable branch the default is 0, so @c WXWIN_COMPATIBILITY_2_8 = 0
for 3.2.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-compat26 and @c \--enable-compat24 options to
configure.
them using the @c \--disable-compat30 and @c \--enable-compat28 options to
configure. Their values can also be changed with CMake.
They can be useful in two ways:
@li Changing @c WXWIN_COMPATIBILITY_2_6 to 0 can be useful to find uses of
@li Changing @c WXWIN_COMPATIBILITY_3_0 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.
@li Changing @c WXWIN_COMPATIBILITY_2_8 to 1 can be useful to compile a program
developed using 2.8.x that no longer compiles with 3.2.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.
@ -111,11 +105,11 @@ shared libraries, also known as dynamic link libraries (DLLs) on Windows or
dynamic shared libraries on macOS.
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
wxWidgets 3.2.0, 3.2.1 and 3.2.2. Since 3.2.2 is backward compatible with the
earlier versions, it should be enough to install just wxWidgets 3.2.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.
compatibility is not supported, then all the required versions 3.2.0, 3.2.1 and
3.2.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
@ -134,12 +128,12 @@ 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. 2.6.1, continue to work with shared
libraries of a later binary compatible version, for example 2.6.2. The converse
with one version of wxWidgets, e.g. 3.2.1, continue to work with shared
libraries of a later binary compatible version, for example 3.2.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
later version, e.g. 3.2.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.
with, for example 3.2.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
@ -150,7 +144,7 @@ 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.
component, for example @c wxABI_VERSION=30200 for 3.2.0.
Setting @c wxABI_VERSION should prevent the application from implicitly
depending on a later version of wxWidgets, and also disables any new features
@ -160,7 +154,7 @@ 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.
numbers. It won't, for example, help you write code compatible with 3.0.x using
wxWidgets 3.2.x.
*/