]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/backwardcompatibility.h
fixed wxListCtrl::RefreshItem(s) - it didn't update anything before
[wxWidgets.git] / docs / doxygen / overviews / backwardcompatibility.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
e0a47918 2// Name: backwardcompatibility.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/*!
36c9828f 10
e0a47918 11 @page overview_backwardcompat Backward compatibility
36c9828f 12
15b6757b
FM
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.
e0a47918 17
15b6757b
FM
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.
36c9828f 22
e0a47918
FM
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>
36c9828f 30
e0a47918
FM
31
32 @section overview_backwardcompat_versionnumbering The version numbering scheme
36c9828f 33
15b6757b
FM
34 wxWidgets version numbers can have up to four components, with trailing
35 zeros sometimes omitted:
36c9828f 36
15b6757b
FM
37 @code
38 major.minor.release.sub-release
39 @endcode
36c9828f 40
15b6757b
FM
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.
e0a47918 46
15b6757b
FM
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.
e0a47918 52
15b6757b
FM
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.
e0a47918 59
15b6757b
FM
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.
36c9828f 65
e0a47918
FM
66
67 @section overview_backwardcompat_sourcecompat Source level compatibility
36c9828f 68
15b6757b
FM
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
e0a47918
FM
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
15b6757b
FM
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.
e0a47918 78
15b6757b
FM
79 For some platforms binary compatibility is also supported, see 'Library
80 binary compatibility' below.
e0a47918
FM
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:
36c9828f 85
15b6757b
FM
86 @code
87 #if WXWIN_COMPATIBILITY_2_4
e0a47918
FM
88 // deprecated feature
89 ...
90 #endif
91 @endcode
36c9828f 92
e0a47918
FM
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*/
36c9828f 183