docs/tech/tn0020.txt

   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$