12 <concept xml:lang="en" id="GUID-F9455FE8-5247-58D5-ACEF-52753B88444F"><title>How to control binary compatibility</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Overview</title> <p>It is important for users that the software they buy and use should continue to run on new releases of Symbian platform, and that it should be transferable to new devices containing the latest releases of the operating system. </p> <p>Ensuring that a current software release does not break existing software is known as maintaining binary compatibility (BC). There is a related compatibility issue for data — ensuring that new software versions remain data compatible with previous versions. Data incompatibilities can be just as galling for software users, making existing documents obsolete, but don't intrinsically affect the software itself. </p> <p>BC is most obviously a concern for the systems developers responsible for the evolution of the operating system. However, it is relevant for any Symbian developer whose software provides services to client software. Symbian developers whose software uses such services should understand a problem that potentially they may encounter. </p> <p>A related concern is where a program is <i>first</i> developed using a version of some system component or a third part service. Symbian developers may need to know whether their programs will also work with <i>older</i> versions of that system component or third part service. This form of compatibility is an added bonus but, generally, backward compatibility is the overriding requirement. </p> </section> <section><title>The interface as contract</title> <p>When a software component is changed, the changes impact all dependent software components — including the ones which have not yet been written. This means that rather than relying on testing, the safety of changes must somehow be guaranteed. </p> <p>A component which defines an interface through which it may be used should be regarded as making a contract with the rest of the world. Its interface is its contact. Other components which build against its interface must be guaranteed that when they later run against its interface, nothing will have changed. The BC requirement is that guarantee. </p> <p>Although in principle there are many different mechanisms through which software can offer an interface to clients, in the Symbian software platform, BC is a DLL related problem. </p> </section> <section><title>Source compatibility, link compatibility, binary compatibility</title> <p>BC is stronger than both link and source compatibility. Maintaining BC also implies that both link and source compatibility are maintained. </p> <p>Source compatibility describes the situation where an interface we are using has changed between building against it and running against it, in such a way that we can only recover by rebuilding against the changed interface. Our source need not change, but we must rebuild. </p> <p>Because source level interfaces are defined in the published header <codeph>#include</codeph> files, it is easy to see whether changes are compatible — examine the changes to the header file. </p> <p>Link compatibility describes the situation where to recover from an interface change we must relink our component against a component we originally built against. Our source need not be rebuilt, but we must relink. </p> <p>Link level interfaces are defined by the published <keyword>import</keyword> library. Again it is not too hard to see whether a change is compatible — ensure that all <keyword>exported</keyword> functions are unchanged. </p> <p>Binary compatibility guarantees a constant interface between our building and running against another component. </p> <p>The BC level interface is not so easy to define and may include quite general behaviour of the changed component. Because it is hard to define it is hard to check for changes which potentially break it. Potential BC breaking changes include: </p> <ul><li id="GUID-308FA053-1D48-55BE-95D5-F80057F97B48"><p>Virtual member functions are for life — you can't add or remove virtual member functions </p> </li> <li id="GUID-545ECFCF-32C5-53C1-841B-A40623F2B5D3"><p>or change the virtuality of a function </p> </li> <li id="GUID-637E8C8E-48BA-5638-A9CB-D7A34121FAC7"><p>or change their declaration order </p> </li> <li id="GUID-51B5A996-F810-5192-B3E3-D808735283EA"><p>or override an existing function that was previously inherited </p> </li> <li id="GUID-517E1BC2-1152-556A-B129-42294683534E"><p>You cannot add a UID if was originally omitted from the DLL </p> </li> </ul> <p>Safe changes which preserve <i>backward</i> binary compatibility include: </p> <ul><li id="GUID-48431968-E4C6-55CA-A089-87EE30BB6660"><p>Any name can be changed <b>but</b> — this requires clear documentation because dependent components must change source code, and usually also requires editing the frozen <filepath>.def</filepath> files </p> </li> <li id="GUID-3DAF9CAD-AB42-5AFE-81B9-8C08F0893B07"><p>Adding services — classes, global functions, static and <i>non-virtual</i> member functions can all be added to a shared library </p> </li> <li id="GUID-E62F3737-D3B9-5E2E-ACF4-D930033B5683"><p>Changing access specification — any member can be made more widely accessible. The reverse is <b>not</b> allowed. Similarly, friendship can be bestowed but not withdrawn </p> </li> <li id="GUID-ECE8BEE0-E11A-54A1-A65B-30DC1DDA2C3C"><p>You can do what you like with private data and non-virtual function members <b>except</b> — when it would change the class size, or when effectively public data would move in the class </p> </li> <li id="GUID-97A41CBA-D5E6-5F06-B050-8085433A6586"><p>Parameters and return values — valid inputs must retain their interpretation and existing output values must retain their meaning </p> </li> <li id="GUID-C723CE0A-FD69-507D-BE85-9701B9C66608"><p>Inputs can be widened: e.g. less derived pointer, extended enum, adding a const qualifier or outputs can be narrowed: e.g. more derived pointer, fewer error code values, removing a const qualifier </p> </li> <li id="GUID-D61A91E3-66BA-5F79-BC53-5F06865C4554"><p>Pointer and reference types can be exchanged </p> </li> </ul> <p>To help maintain BC only release what you need to release — you don't have to support what you don't release </p> </section> <section><title>Controlling binary compatibility with build time tools</title> <p>Some potentially BC breaking changes are introduced not by Symbian developers but by the build system. Symbian platform provides tools which help to control BC by blocking accidental build-time changes. </p> <p>When a DLL is loaded it supplies a table of addresses, one for each exported symbol and one for the entry point of each exported function. This is the DLL's public interface. To preserve BC the index of each export must remain constant from one release to another. </p> <p>Symbian platform uses export definitions (<filepath>.def</filepath>) files to manage this requirement. Each exported symbol is listed in the exports section of the file with its ordinal, which is calculated as index + ordinal base. Symbian platform uses an ordinal base of 1. By the definition of source compatibility implied by BC, every export defined in an earlier release will be defined in the new release. Exports introduced in a new release must come after those defined in earlier releases. </p> <p>For DLL builds, the build tools automatically create the <filepath>.def</filepath> file within the build tree for the specified target. Once these have been generated for a build, they can be archived with the project source and used in future builds to <keyword>freeze</keyword> the exports against change. </p> <p>This is done by copying the <filepath>.def</filepath> files into a default location and including the directive </p> <p> <codeph>DEFFILE projectname.def</codeph> </p> <p>in the project <filepath>.mmp</filepath> file. </p> <p>In any subsequent <b>command-line</b> build of the project the exports will be guaranteed compatible with the current version. If new exports are added, the new def files should once again be copied from the build directory and archived with the new release. Only command-line builds should be released. </p> <p>The creation and translation of <filepath>.def</filepath> files is managed by the Symbian platform build process, see <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The Symbian build process</xref>. </p> </section> </conbody></concept> |
|