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