Ryan's binary compatibility technote (patch 1242898)
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@34959 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
@@ -20,6 +20,7 @@ tn0016.txt How to add new files and libraries to wxWidgets build system (Bakef
|
||||
tn0017.txt How to write unit tests for wxWidgets classes
|
||||
tn0018.txt How to add a new font encoding/charset to wxWidgets
|
||||
tn0019.txt Special notes about writing wxMSW code
|
||||
tn0020.txt Binary Compatability and wxWidgets
|
||||
|
||||
|
||||
Version: $Id$
|
||||
|
||||
176
docs/tech/tn0020.txt
Normal file
176
docs/tech/tn0020.txt
Normal file
@@ -0,0 +1,176 @@
|
||||
Binary Compatability and wxWidgets
|
||||
==================================
|
||||
0. Purpose
|
||||
----------
|
||||
|
||||
This is broad technote covering all aspects of binary compatability with
|
||||
wxWidgets.
|
||||
|
||||
1. Releases
|
||||
-----------
|
||||
|
||||
General overview of releases can be found in tn0012.txt, but for
|
||||
completeness the wxWidgets release version number is as follows:
|
||||
|
||||
2.6.2
|
||||
|
||||
Where
|
||||
|
||||
2 6 2
|
||||
Major Minor Release
|
||||
|
||||
(I.E. Major.Minor.Release).
|
||||
|
||||
All Release versions where the Minor is EVEN (2.4.x,2.6.x
|
||||
etc. ODD minors are development versions) are expected to be binary
|
||||
compatable. Note that this means FORWARD binary compatability only -
|
||||
new methods to classes are ok as long as they arn't virtual, etc.
|
||||
|
||||
2. What kind of changes are NOT binary compatable
|
||||
-------------------------------------------------
|
||||
|
||||
If its still up, the KDE guide is a good reference:
|
||||
http://developer.kde.org/documentation/other/binarycompatibility.html
|
||||
|
||||
The changes that are NOT binary compatable:
|
||||
- Adding a virtual function
|
||||
- Changing the name of a any function or variable
|
||||
- Changing the signature of a virtual function (adding a parameter,
|
||||
even a default one)
|
||||
- Changing the order of the virtual functions in a class
|
||||
["switching" them, etc.]
|
||||
- Changing access privalages to a function (protected to private etc.)
|
||||
[unlike KDE we need to support windows so this is not allowed]
|
||||
- Adding a member variable
|
||||
- Changing the order of non-static member variables
|
||||
|
||||
|
||||
3. wxABI_VERSION and BACKWARD binary compatability
|
||||
--------------------------------------------------
|
||||
|
||||
As mentioned we do not support BACKWARD binary compatability.
|
||||
|
||||
However, for this purpose we have the macro wxABI_VERSION. All
|
||||
new symbols added to binary compatable releases are to be ifed
|
||||
with wxABI_VERSION.
|
||||
|
||||
The layout of wxABI_VERSION is as follows:
|
||||
|
||||
20602
|
||||
|
||||
where
|
||||
|
||||
20 60 2
|
||||
Major Minor Release
|
||||
|
||||
I.E. it corresponds to the wxWidgets release in {1}.
|
||||
|
||||
An example of using wxABI_VERSION is as follows for symbols
|
||||
only in a 2.6.2 release:
|
||||
|
||||
#if wxABI_VERSION >= 20602 /* 2.6.2+ only */
|
||||
bool Load(const wxURI& location, const wxURI& proxy);
|
||||
|
||||
wxFileOffset GetDownloadProgress();
|
||||
wxFileOffset GetDownloadTotal();
|
||||
|
||||
bool ShowPlayerControls(
|
||||
wxMediaCtrlPlayerControls flags =
|
||||
wxMEDIACTRLPLAYERCONTROLS_DEFAULT);
|
||||
|
||||
//helpers for the wxPython people
|
||||
bool LoadURI(const wxString& fileName)
|
||||
{ return Load(wxURI(fileName)); }
|
||||
bool LoadURIWithProxy(const wxString& fileName, const wxString& proxy)
|
||||
{ return Load(wxURI(fileName), wxURI(proxy)); }
|
||||
#endif
|
||||
|
||||
|
||||
4. Workarounds for adding virtual functions
|
||||
-------------------------------------------
|
||||
|
||||
Originally the idea for adding virtual functions to binary compatable
|
||||
releases was to pad out some empty "reserved" functions and then
|
||||
rename those later when someone needed to add a virtual function.
|
||||
|
||||
However, after there was some actual testing of the idea a lot of
|
||||
controversy erupted. Eventually we decided against the idea, and
|
||||
instead devised a new method for doing so called wxShadowObject.
|
||||
|
||||
wxShadowObject is a class derived from wxObject that provides a means
|
||||
of adding functions and/or member variables to a class internally
|
||||
to wxWidgets. It does so by storing these in a hash map inside of
|
||||
it, looking it up when the function etc. is called. wxShadowObject
|
||||
is generally stored inside a reserved member variable.
|
||||
|
||||
wxShadowObject resides in include/wx/clntdata.h.
|
||||
|
||||
To use wxShadowObject, you first call AddMethod or AddField with
|
||||
the first parameter being the name of the field and/or method
|
||||
you want, and the second parameter being the value of the
|
||||
field and/or method.
|
||||
|
||||
In the case of fields this is a void*, and in the case of method
|
||||
is a wxShadowObjectMethod which is a typedef:
|
||||
typedef int (*wxShadowObjectMethod)(void*, void*);
|
||||
|
||||
After you add a field, you can set it via SetField with the same
|
||||
params as AddField, the second param being the value to set
|
||||
the field to. You can get the field after you call AddField
|
||||
via GetField, with the parameters as the other two field functions,
|
||||
only in the case the second parameter is the fallback
|
||||
value for the field in the case of it not being found in the
|
||||
hash map.
|
||||
|
||||
You can call a method after you add it via InvokeMethod, which
|
||||
returns a bool indicating whether or not the method was found
|
||||
in the hash map, and has 4 parameters. The first parameter is
|
||||
the name of the method you wish to call, the second is the first
|
||||
parameter passed to the wxShadowObjectMethod, the third is the
|
||||
second parameter passed to that wxShadowObjectMethod, and the
|
||||
fourth is the return value of the wxShadowObjectMethod.
|
||||
|
||||
5. version-script.in
|
||||
--------------------
|
||||
|
||||
For ld/libtool we use sun-style version scripts. Basically
|
||||
anything which fits the conditions of being ifed via wxABI_VERSION
|
||||
needs to go here also.
|
||||
|
||||
The file has the layout as follows:
|
||||
|
||||
@WX_VERSION_TAG@.X
|
||||
|
||||
Where X is the current Release as mentioned earlier, i.e. 2. This
|
||||
is following by an opening bracket "{", followed by "global:",
|
||||
followed by the added symbols, then followed by "}", and then
|
||||
the file is either followed by earlier Releases or ended by
|
||||
a @WX_VERSION_TAG@ block without the period or Release.
|
||||
|
||||
Added symbols have the form
|
||||
*CLASSNAME*METHODNAME*PARAM1*PARAM2*...
|
||||
|
||||
Where CLASSNAME is the name of the class or blank (along with
|
||||
omitted *) in the case of a global function. METHODNAME is the name
|
||||
of the class method or global function. This is followed by another
|
||||
star "*" and then the type of each subsequent parameter for the function,
|
||||
such as *wxString etc..
|
||||
|
||||
6. Testing binary compatability between releases
|
||||
------------------------------------------------
|
||||
|
||||
An easy way of testing binary compatability is just to build wxWidgets
|
||||
in dll/dynamic library mode and then switch out the current library
|
||||
in question with an earlier stable version of the library, then running
|
||||
the application in question again. If it runs OK then there is usually
|
||||
binary compatability between those releases.
|
||||
|
||||
You can also break into your debugger or whatever program you want
|
||||
to use and check the memory layout of the class. If it is the same
|
||||
then it is binary compatable.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
Author: RN
|
||||
Version: $Id$
|
||||
Reference in New Issue
Block a user