docs/tech/tn0020.txt

   1                     Binary Compatibility and wxWidgets
   2                     ==================================
   3 0. Purpose
   4 ----------
   5
   6 This is a broad technote covering all aspects of binary compatibility 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 versions with EVEN minor version component (e.g. 2.4.x, 2.6.x etc.)
  25 are expected to be binary compatible (ODD minors are development versions
  26 and the compatibility constraints don't apply to them). Note that by
  27 preserving binary compatibility we mean BACKWARDS compatibility only,
  28 meaning that applications built with old wxWidgets headers should continue
  29 to work with new wxWidgets (shared/dynamic) libraries without the need to
  30 rebuild. There is no requirement to preserve compatibility in the other
  31 direction (i.e. make new headers compatible with old libraries) as this
  32 would preclude any additions whatsoever to the stable branch. But see
  33 also section (4).
  34
  35
  36 2. What kind of changes are NOT binary compatible
  37 -------------------------------------------------
  38
  39 If its still up, the KDE guide is a good reference:
  40 http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++
  41
  42 The changes that are NOT binary compatible:
  43 - Adding a virtual function
  44 - Changing the name of a any function or variable
  45 - Changing the signature of a virtual function (adding a parameter,
  46 even a default one)
  47 - Changing the order of the virtual functions in a class
  48 ["switching" them, etc.]
  49 - Changing access privileges of a function: some compilers (among which MSVC)
  50   use the function access specifier in its mangled name. Moreover, while
  51   changing a private function to public should be compatible (as the old
  52   symbol can't be referenced from outside the library anyhow), changing a
  53   virtual private function to public is NOT compatible because the old symbol
  54   is referenced by the virtual tables in the executable code and so an old
  55   program compiled with MSVC wouldn't start up with a new DLL even if it
  56   doesn't use the affected symbol at all!
  57 - Adding a member variable
  58 - Changing the order of non-static member variables
  59
  60
  61 3. Changes which are compatible
  62 -------------------------------
  63
  64 - Adding a new class
  65 - Adding a new non-virtual method to an existing class
  66 - Adding a new constructor to an existing class
  67 - Overriding the implementation of an existing virtual function
  68 [this is considered to be backwards binary compatible until we find a
  69  counter example; currently it's known to work with Apple gcc at least]
  70 - Anything which doesn't result in ABI change at all, e.g. adding new
  71   macros, constants and, of course, private changes in the implementation
  72
  73
  74 4. wxABI_VERSION and "forward" binary compatibility
  75 --------------------------------------------------
  76
  77 As mentioned we do not support "forward" binary compatibility, that is the
  78 ability to run applications compiled with new wxWidgets headers on systems
  79 with old wxWidgets libraries.
  80
  81 However, for the developers who want to ensure that their application works
  82 with some fixed old wxWidgets version and doesn't (inadvertently) require
  83 features added in later releases, we provide the macro wxABI_VERSION which
  84 can be defined to restrict the API exported by wxWidgets headers to that of
  85 a fixed old release.
  86
  87 For this to work, all new symbols added to binary compatible releases must
  88 be #if'ed with wxABI_VERSION.
  89
  90 The layout of wxABI_VERSION is as follows:
  91
  92 20602
  93
  94 where
  95
  96  2     06     02
  97 Major Minor Release
  98
  99 I.E. it corresponds to the wxWidgets release in (1).
 100
 101 An example of using wxABI_VERSION is as follows for symbols
 102 only in a 2.6.2 release:
 103
 104 #if wxABI_VERSION >= 20602 /* 2.6.2+ only */
 105 bool Load(const wxURI& location, const wxURI& proxy);
 106
 107 wxFileOffset GetDownloadProgress();
 108 wxFileOffset GetDownloadTotal();
 109
 110 bool    ShowPlayerControls(
 111   wxMediaCtrlPlayerControls flags =
 112     wxMEDIACTRLPLAYERCONTROLS_DEFAULT);
 113
 114 //helpers for the wxPython people
 115 bool LoadURI(const wxString& fileName)
 116 {   return Load(wxURI(fileName));       }
 117 bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy)
 118 {   return Load(wxURI(fileName), wxURI(proxy));       }
 119 #endif
 120
 121
 122 5. Workarounds for adding virtual functions
 123 -------------------------------------------
 124
 125 Originally the idea for adding virtual functions to binary compatible
 126 releases was to pad out some empty "reserved" functions and then
 127 rename those later when someone needed to add a virtual function.
 128
 129 However, after there was some actual testing of the idea a lot of
 130 controversy erupted.  Eventually we decided against the idea, and
 131 instead devised a new method for doing so called wxShadowObject.
 132
 133 wxShadowObject is a class derived from wxObject that provides a means
 134 of adding functions and/or member variables to a class internally
 135 to wxWidgets.  It does so by storing these in a hash map inside of
 136 it, looking it up when the function etc. is called. wxShadowObject
 137 is generally stored inside a reserved member variable.
 138
 139 wxShadowObject resides in include/wx/clntdata.h.
 140
 141 To use wxShadowObject, you first call AddMethod or AddField with
 142 the first parameter being the name of the field and/or method
 143 you want, and the second parameter being the value of the
 144 field and/or method.
 145
 146 In the case of fields this is a void*, and in the case of method
 147 is a wxShadowObjectMethod which is a typedef:
 148 typedef int (*wxShadowObjectMethod)(void*, void*);
 149
 150 After you add a field, you can set it via SetField with the same
 151 parameters as AddField, the second parameter being the value to set
 152 the field to.  You can get the field after you call AddField
 153 via GetField, with the parameters as the other two field functions,
 154 only in the case the second parameter is the fallback
 155 value for the field in the case of it not being found in the
 156 hash map.
 157
 158 You can call a method after you add it via InvokeMethod, which
 159 returns a bool indicating whether or not the method was found
 160 in the hash map, and has 4 parameters.  The first parameter is
 161 the name of the method you wish to call, the second is the first
 162 parameter passed to the wxShadowObjectMethod, the third is the
 163 second parameter passed to that wxShadowObjectMethod, and the
 164 fourth is the return value of the wxShadowObjectMethod.
 165
 166 6. version-script.in
 167 --------------------
 168
 169 For ld/libtool we use sun-style version scripts.  Basically
 170 anything which fits the conditions of being #if'ed via wxABI_VERSION
 171 needs to go here also.
 172
 173 See 'info ld scripts version' on a GNU system, it's online here:
 174 http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html
 175
 176 Or see chapter 5 of the 'Linker and Libraries Guide' for Solaris, available
 177 online here:
 178 http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWdev/LLM/p1.html
 179
 180 The file has the layout as follows:
 181
 182 @WX_VERSION_TAG@.X
 183
 184 Where X is the current Release as mentioned earlier, i.e. 2.  This
 185 is following by an opening bracket "{", followed by "global:",
 186 followed by patterns matching added symbols, then followed by "}", and then
 187 the file is either followed by earlier Releases or ended by
 188 a @WX_VERSION_TAG@ block without the period or Release.
 189
 190 The patterns used to specify added symbols are globbing patters and can
 191 contain wildcards such as '*'.
 192
 193 For example for a new class member such as:
 194     wxFont wxGenericListCtrl::GetItemFont( long item ) const;
 195
 196 the mangled symbol might be:
 197     _ZNK17wxGenericListCtrl11GetItemFontEl
 198
 199 so a line like this could be added to version-script.in:
 200     *wxGenericListCtrl*GetItemFont*;
 201
 202 Allow for the fact that the name mangling is going to vary from compiler to
 203 complier.
 204
 205 When adding a class you can match all the symbols it adds with a single
 206 pattern, so long as that pattern is not likely to also match other symbols.
 207 For example for wxLogBuffer a line like this:
 208     *wxLogBuffer*;
 209
 210
 211 7. Checking the version information in libraries and programs
 212 -------------------------------------------------------------
 213
 214 On Sun there is a tool for this, see pvs(1). On GNU you can use objdump, below
 215 are some examples.
 216
 217 To see what versions of each library a program (or library) depends on:
 218
 219 $ objdump -p widgets | sed -ne '/Version References/,/^$/p'
 220 Version References:
 221   required from libgcc_s.so.1:
 222     0x0b792650 0x00 10 GCC_3.0
 223   required from libwx_based-2.6.so.0:
 224     0x0cca2546 0x00 07 WXD_2.6
 225   required from libstdc++.so.6:
 226     0x056bafd3 0x00 09 CXXABI_1.3
 227     0x08922974 0x00 06 GLIBCXX_3.4
 228   required from libwx_gtk2d_core-2.6.so.0:
 229     0x0a2545d2 0x00 08 WXD_2.6.2
 230     0x0cca2546 0x00 05 WXD_2.6
 231   required from libc.so.6:
 232     0x09691a75 0x00 04 GLIBC_2.2.5
 233
 234 To see what WXD_2.6.2 symbols a program uses:
 235
 236 $ objdump -T widgets | grep 'WXD_2\.6\.2'
 237 0000000000000000 g    DO *ABS*  0000000000000000  WXD_2.6.2   WXD_2.6.2
 238 00000000004126d8      DF *UND*  0000000000000177  WXD_2.6.2   _ZN19wxTopLevelWindowGTK20RequestUserAttentionEi
 239
 240 To see what WXD_2.6.2 symbols a library defines:
 241
 242 $ objdump -T libwx_based-2.6.so | grep 'WXD_2\.6\.2' | grep -v 'UND\|ABS'
 243 0000000000259a10  w   DO .data  0000000000000018  WXD_2.6.2   _ZTI19wxMessageOutputBest
 244 00000000002599e0  w   DO .data  0000000000000028  WXD_2.6.2   _ZTV19wxMessageOutputBest
 245 000000000010a98e  w   DF .text  000000000000003e  WXD_2.6.2   _ZN19wxMessageOutputBestD0Ev
 246 0000000000114efb  w   DO .rodata        000000000000000e  WXD_2.6.2   _ZTS11wxLogBuffer
 247 0000000000255590  w   DO .data  0000000000000018  WXD_2.6.2   _ZTI11wxLogBuffer
 248 000000000011b550  w   DO .rodata        0000000000000016  WXD_2.6.2   _ZTS19wxMessageOutputBest
 249 00000000000bfcc8 g    DF .text  00000000000000dd  WXD_2.6.2   _ZN11wxLogBuffer5DoLogEmPKcl
 250 000000000010a3a6 g    DF .text  0000000000000153  WXD_2.6.2   _ZN19wxMessageOutputBest6PrintfEPKcz
 251 00000000000c0b22  w   DF .text  000000000000004b  WXD_2.6.2   _ZN11wxLogBufferD0Ev
 252 00000000000bfc3e g    DF .text  0000000000000089  WXD_2.6.2   _ZN11wxLogBuffer5FlushEv
 253 00000000000c0ad6  w   DF .text  000000000000004b  WXD_2.6.2   _ZN11wxLogBufferD1Ev
 254 00000000000b1130  w   DF .text  0000000000000036  WXD_2.6.2   _ZN11wxLogBufferC1Ev
 255 00000000000c095c  w   DF .text  0000000000000029  WXD_2.6.2   _ZN19wxMessageOutputBestC1Ev
 256 00000000000c08e8  w   DF .text  000000000000003e  WXD_2.6.2   _ZN19wxMessageOutputBestD1Ev
 257 00000000002554c0  w   DO .data  0000000000000038  WXD_2.6.2   _ZTV11wxLogBuffer
 258 00000000000bfda6 g    DF .text  0000000000000036  WXD_2.6.2   _ZN11wxLogBuffer11DoLogStringEPKcl
 259 00000000000abe10 g    DF .text  0000000000000088  WXD_2.6.2   _ZN14wxZipFSHandler7CleanupEv
 260
 261
 262 8. Testing binary compatibility between releases
 263 ------------------------------------------------
 264
 265 An easy way of testing binary compatibility is just to build wxWidgets
 266 in dll/dynamic library mode and then switch out the current library
 267 in question with an earlier stable version of the library, then running
 268 the application in question again.  If it runs OK then there is usually
 269 binary compatibility between those releases.
 270
 271 You can also break into your debugger or whatever program you want
 272 to use and check the memory layout of the class.  If it is the same
 273 then it is binary compatible.
 274 (In GDB the command x/d will show addresses as pointers to functions if
 275 possible so you can see if the order of the functions in vtbl doesn't change.)
 276
 277 Another way to check for binary compatibility is to build wxWidgets in shared mode
 278 and use the 'abicheck.sh --generate' script before doing your changes to generate
 279 the current ABI (if the 'expected_abi' file is not already in the repo).
 280 Then rebuild wxWidgets with your changes and use 'abicheck.sh' to compare the
 281 resulting ABI with the expected one.
 282 Note that the abicheck.sh script is in the "lib" folder.
 283
 284
 285 === EOF ===
 286
 287 Author:  RN
 288 Version: $Id$