]>
Commit | Line | Data |
---|---|---|
1 | Binary Compatability and wxWidgets | |
2 | ================================== | |
3 | 0. Purpose | |
4 | ---------- | |
5 | ||
6 | This is broad technote covering all aspects of binary compatability with | |
7 | wxWidgets. | |
8 | ||
9 | 1. Releases | |
10 | ----------- | |
11 | ||
12 | General overview of releases can be found in tn0012.txt, but for | |
13 | completeness the wxWidgets release version number is as follows: | |
14 | ||
15 | 2.6.2 | |
16 | ||
17 | Where | |
18 | ||
19 | 2 6 2 | |
20 | Major Minor Release | |
21 | ||
22 | (I.E. Major.Minor.Release). | |
23 | ||
24 | All Release versions where the Minor is EVEN (2.4.x,2.6.x | |
25 | etc. ODD minors are development versions) are expected to be binary | |
26 | compatable. Note that this means FORWARD binary compatability only - | |
27 | new methods to classes are ok as long as they arn't virtual, etc. | |
28 | ||
29 | 2. What kind of changes are NOT binary compatable | |
30 | ------------------------------------------------- | |
31 | ||
32 | If its still up, the KDE guide is a good reference: | |
33 | http://developer.kde.org/documentation/other/binarycompatibility.html | |
34 | ||
35 | The changes that are NOT binary compatable: | |
36 | - Adding a virtual function | |
37 | - Changing the name of a any function or variable | |
38 | - Changing the signature of a virtual function (adding a parameter, | |
39 | even a default one) | |
40 | - Changing the order of the virtual functions in a class | |
41 | ["switching" them, etc.] | |
42 | - Changing access privalages to a function (protected to private etc.) | |
43 | [unlike KDE we need to support windows so this is not allowed] | |
44 | - Adding a member variable | |
45 | - Changing the order of non-static member variables | |
46 | ||
47 | ||
48 | 3. wxABI_VERSION and BACKWARD binary compatability | |
49 | -------------------------------------------------- | |
50 | ||
51 | As mentioned we do not support BACKWARD binary compatability. | |
52 | ||
53 | However, for this purpose we have the macro wxABI_VERSION. All | |
54 | new symbols added to binary compatable releases are to be ifed | |
55 | with wxABI_VERSION. | |
56 | ||
57 | The layout of wxABI_VERSION is as follows: | |
58 | ||
59 | 20602 | |
60 | ||
61 | where | |
62 | ||
63 | 2 06 02 | |
64 | Major Minor Release | |
65 | ||
66 | I.E. it corresponds to the wxWidgets release in {1}. | |
67 | ||
68 | An example of using wxABI_VERSION is as follows for symbols | |
69 | only in a 2.6.2 release: | |
70 | ||
71 | #if wxABI_VERSION >= 20602 /* 2.6.2+ only */ | |
72 | bool Load(const wxURI& location, const wxURI& proxy); | |
73 | ||
74 | wxFileOffset GetDownloadProgress(); | |
75 | wxFileOffset GetDownloadTotal(); | |
76 | ||
77 | bool ShowPlayerControls( | |
78 | wxMediaCtrlPlayerControls flags = | |
79 | wxMEDIACTRLPLAYERCONTROLS_DEFAULT); | |
80 | ||
81 | //helpers for the wxPython people | |
82 | bool LoadURI(const wxString& fileName) | |
83 | { return Load(wxURI(fileName)); } | |
84 | bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy) | |
85 | { return Load(wxURI(fileName), wxURI(proxy)); } | |
86 | #endif | |
87 | ||
88 | ||
89 | 4. Workarounds for adding virtual functions | |
90 | ------------------------------------------- | |
91 | ||
92 | Originally the idea for adding virtual functions to binary compatable | |
93 | releases was to pad out some empty "reserved" functions and then | |
94 | rename those later when someone needed to add a virtual function. | |
95 | ||
96 | However, after there was some actual testing of the idea a lot of | |
97 | controversy erupted. Eventually we decided against the idea, and | |
98 | instead devised a new method for doing so called wxShadowObject. | |
99 | ||
100 | wxShadowObject is a class derived from wxObject that provides a means | |
101 | of adding functions and/or member variables to a class internally | |
102 | to wxWidgets. It does so by storing these in a hash map inside of | |
103 | it, looking it up when the function etc. is called. wxShadowObject | |
104 | is generally stored inside a reserved member variable. | |
105 | ||
106 | wxShadowObject resides in include/wx/clntdata.h. | |
107 | ||
108 | To use wxShadowObject, you first call AddMethod or AddField with | |
109 | the first parameter being the name of the field and/or method | |
110 | you want, and the second parameter being the value of the | |
111 | field and/or method. | |
112 | ||
113 | In the case of fields this is a void*, and in the case of method | |
114 | is a wxShadowObjectMethod which is a typedef: | |
115 | typedef int (*wxShadowObjectMethod)(void*, void*); | |
116 | ||
117 | After you add a field, you can set it via SetField with the same | |
118 | params as AddField, the second param being the value to set | |
119 | the field to. You can get the field after you call AddField | |
120 | via GetField, with the parameters as the other two field functions, | |
121 | only in the case the second parameter is the fallback | |
122 | value for the field in the case of it not being found in the | |
123 | hash map. | |
124 | ||
125 | You can call a method after you add it via InvokeMethod, which | |
126 | returns a bool indicating whether or not the method was found | |
127 | in the hash map, and has 4 parameters. The first parameter is | |
128 | the name of the method you wish to call, the second is the first | |
129 | parameter passed to the wxShadowObjectMethod, the third is the | |
130 | second parameter passed to that wxShadowObjectMethod, and the | |
131 | fourth is the return value of the wxShadowObjectMethod. | |
132 | ||
133 | 5. version-script.in | |
134 | -------------------- | |
135 | ||
136 | For ld/libtool we use sun-style version scripts. Basically | |
137 | anything which fits the conditions of being ifed via wxABI_VERSION | |
138 | needs to go here also. | |
139 | ||
140 | See 'info ld scripts version' on a GNU system, it's online here: | |
141 | http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html | |
142 | ||
143 | Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available | |
144 | online here: | |
145 | http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html | |
146 | ||
147 | The file has the layout as follows: | |
148 | ||
149 | @WX_VERSION_TAG@.X | |
150 | ||
151 | Where X is the current Release as mentioned earlier, i.e. 2. This | |
152 | is following by an opening bracket "{", followed by "global:", | |
153 | followed by patterns matching added symbols, then followed by "}", and then | |
154 | the file is either followed by earlier Releases or ended by | |
155 | a @WX_VERSION_TAG@ block without the period or Release. | |
156 | ||
157 | The patterns used to specify added symbols are globbing patters and can | |
158 | contain wildcards such as '*'. | |
159 | ||
160 | For example for a new class member such as: | |
161 | wxFont wxGenericListCtrl::GetItemFont( long item ) const; | |
162 | ||
163 | the mangled symbol might be: | |
164 | _ZNK17wxGenericListCtrl11GetItemFontEl | |
165 | ||
166 | so a line like this could be added to version-script.in: | |
167 | *wxGenericListCtrl*GetItemFont*; | |
168 | ||
169 | Allow for the fact that the name mangling is going to vary from compiler to | |
170 | complier. | |
171 | ||
172 | When adding a class you can match all the symbols it adds with a single | |
173 | pattern, so long as that pattern is not likely to also match other symbols. | |
174 | For example for wxLogBuffer a line like this: | |
175 | *wxLogBuffer*; | |
176 | ||
177 | ||
178 | 5.5. Checking the version information in libraries and programs | |
179 | --------------------------------------------------------------- | |
180 | ||
181 | On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below | |
182 | are some examples. | |
183 | ||
184 | To see what versions of each library a program (or library) depends on: | |
185 | ||
186 | $ objdump -p widgets | sed -ne '/Version References/,/^$/p' | |
187 | Version References: | |
188 | required from libgcc_s.so.1: | |
189 | 0x0b792650 0x00 10 GCC_3.0 | |
190 | required from libwx_based-2.6.so.0: | |
191 | 0x0cca2546 0x00 07 WXD_2.6 | |
192 | required from libstdc++.so.6: | |
193 | 0x056bafd3 0x00 09 CXXABI_1.3 | |
194 | 0x08922974 0x00 06 GLIBCXX_3.4 | |
195 | required from libwx_gtk2d_core-2.6.so.0: | |
196 | 0x0a2545d2 0x00 08 WXD_2.6.2 | |
197 | 0x0cca2546 0x00 05 WXD_2.6 | |
198 | required from libc.so.6: | |
199 | 0x09691a75 0x00 04 GLIBC_2.2.5 | |
200 | ||
201 | To see what WXD_2.6.2 symbols a program uses: | |
202 | ||
203 | $ objdump -T widgets | grep 'WXD_2\.6\.2' | |
204 | 0000000000000000 g DO *ABS* 0000000000000000 WXD_2.6.2 WXD_2.6.2 | |
205 | 00000000004126d8 DF *UND* 0000000000000177 WXD_2.6.2 _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi | |
206 | ||
207 | To see what WXD_2.6.2 symbols a library defines: | |
208 | ||
209 | $ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS' | |
210 | 0000000000259a10 w DO .data 0000000000000018 WXD_2.6.2 _ZTI19wxMessageOutputBest | |
211 | 00000000002599e0 w DO .data 0000000000000028 WXD_2.6.2 _ZTV19wxMessageOutputBest | |
212 | 000000000010a98e w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD0Ev | |
213 | 0000000000114efb w DO .rodata 000000000000000e WXD_2.6.2 _ZTS11wxLogBuffer | |
214 | 0000000000255590 w DO .data 0000000000000018 WXD_2.6.2 _ZTI11wxLogBuffer | |
215 | 000000000011b550 w DO .rodata 0000000000000016 WXD_2.6.2 _ZTS19wxMessageOutputBest | |
216 | 00000000000bfcc8 g DF .text 00000000000000dd WXD_2.6.2 _ZN11wxLogBuffer5DoLogEmPKcl | |
217 | 000000000010a3a6 g DF .text 0000000000000153 WXD_2.6.2 _ZN19wxMessageOutputBest6PrintfEPKcz | |
218 | 00000000000c0b22 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD0Ev | |
219 | 00000000000bfc3e g DF .text 0000000000000089 WXD_2.6.2 _ZN11wxLogBuffer5FlushEv | |
220 | 00000000000c0ad6 w DF .text 000000000000004b WXD_2.6.2 _ZN11wxLogBufferD1Ev | |
221 | 00000000000b1130 w DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBufferC1Ev | |
222 | 00000000000c095c w DF .text 0000000000000029 WXD_2.6.2 _ZN19wxMessageOutputBestC1Ev | |
223 | 00000000000c08e8 w DF .text 000000000000003e WXD_2.6.2 _ZN19wxMessageOutputBestD1Ev | |
224 | 00000000002554c0 w DO .data 0000000000000038 WXD_2.6.2 _ZTV11wxLogBuffer | |
225 | 00000000000bfda6 g DF .text 0000000000000036 WXD_2.6.2 _ZN11wxLogBuffer11DoLogStringEPKcl | |
226 | 00000000000abe10 g DF .text 0000000000000088 WXD_2.6.2 _ZN14wxZipFSHandler7CleanupEv | |
227 | ||
228 | ||
229 | 6. Testing binary compatability between releases | |
230 | ------------------------------------------------ | |
231 | ||
232 | An easy way of testing binary compatability is just to build wxWidgets | |
233 | in dll/dynamic library mode and then switch out the current library | |
234 | in question with an earlier stable version of the library, then running | |
235 | the application in question again. If it runs OK then there is usually | |
236 | binary compatability between those releases. | |
237 | ||
238 | You can also break into your debugger or whatever program you want | |
239 | to use and check the memory layout of the class. If it is the same | |
240 | then it is binary compatable. | |
241 | ||
242 | Also remember to look at http://www.wxwidgets.org/bincompat.html page which | |
243 | summarizes the results of testing of all the samples built against old | |
244 | libraries headers with the new library binaries under Unix. | |
245 | ||
246 | ||
247 | === EOF === | |
248 | ||
249 | Author: RN | |
250 | Version: $Id$ |