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  20    60      2
  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 The file has the layout as follows:
 141
 142 @WX_VERSION_TAG@.X
 143
 144 Where X is the current Release as mentioned earlier, i.e. 2.  This
 145 is following by an opening bracket "{", followed by "global:",
 146 followed by the added symbols, then followed by "}", and then
 147 the file is either followed by earlier Releases or ended by
 148 a @WX_VERSION_TAG@ block without the period or Release.
 149
 150 Added symbols have the form
 151 *CLASSNAME*METHODNAME*PARAM1*PARAM2*...
 152
 153 Where CLASSNAME is the name of the class or blank (along with
 154 omitted *) in the case of a global function.  METHODNAME is the name
 155 of the class method or global function.  This is followed by another
 156 star "*" and then the type of each subsequent parameter for the function,
 157 such as *wxString etc..
 158
 159 6. Testing binary compatability between releases
 160 ------------------------------------------------
 161
 162 An easy way of testing binary compatability is just to build wxWidgets
 163 in dll/dynamic library mode and then switch out the current library
 164 in question with an earlier stable version of the library, then running
 165 the application in question again.  If it runs OK then there is usually
 166 binary compatability between those releases.
 167
 168 You can also break into your debugger or whatever program you want
 169 to use and check the memory layout of the class.  If it is the same
 170 then it is binary compatable.
 171
 172 Also remember to look at http://www.wxwidgets.org/bincompat.html page which
 173 summarizes the results of testing of all the samples built against old
 174 libraries headers with the new library binaries under Unix.
 175
 176
 177 === EOF ===
 178
 179 Author:  RN
 180 Version: $Id$