Re: [pdf-devel] Binary compatibility

[Juan Pedro Bolivar Puente]

Alfred M. Szmidt wrote:
>    How are we going to address the binary-compatibility issue? I think
>    that this kind of library must be binary-compatible along wide
>    version ranges to ease distribution maintainers and third-party
>    client developer's life.
> 
>    The problem is that as all structures are defined in the public
>    header files, we can't assure that the compiler will generate
>    binary compatible code or that the library clients will make a
>    binary-compatible use of it.
> 
> I am not sure what you mean with binary compatible now.  Binary
> compatibility is between the program and the library, the compiler is
> not involved at all.  It is when your program expects a int, but the
> library upgrade its interface to using a float.
> 
> As long as the compiler and linker can talk to each other, it does not
> matter what you put into a header or a library.  What matters is what
> symbols the binary you run uses, and how they correspond to the
> symbols in a library.
> 
> Binary compatibility can be solved using using linker scripts, see
> `(ld) VERSION' for details.
> 
> So I am quite curious what you mean with binary compatibility, it does
> not correspond to what is generally meant with that word.


Well, all the compatibility is not related to the symbols. The compiler
is the one that gives "meaning" to some memory chunks, in concrete, the
structures. By binary-compatibility issues I mean the problem that
arises when you change the content of a structure that is stack
allocated, or a structure that you access directly. The programs
compiled and linked against the old version of the library will stop
working. For example:

- Library version 1:
   struct A { int member };
   void a_func (struct A*);

- Library version 2:
   struct A { int member1, member2 };
   void a_func (struct A*);

- Client:
   my_client_func ()
   {
     struct A aobj;
     int var;
     a_func (&aobj);
   }

In your point of view of binary-compatibility, that client code would
always link correctly. Actually that code has "source-level"
encapsulation (structure A is never manipullated directly, only by
functions), but the code is not "compilation-encapsulated" because the
compiler *must* know the size of A to allocate space for it in the stack
and associate stack possitions to 'aobj' and 'var'.

The problem with that code is that if the client code was compiled using
the version 1 of the library, then it will not work when linked agains
version 2. In version two the variable 'aobj' would probably overlap
with 'var' and if 'a_func ()' messes with A.member2 probably 'var'
content would be overwritten.

The solutions for this are:
  1) Not to touch structures among different versions. The problem is
that you often need that to add nice functionallity or just to solve bugs.
  2) "Hide" the structures to the library user: Which means several
things, as stated before:
     a) Use heap-allocated objects, so the client code is not the one
who needs to know the size and composition of the structures.
     b) Never allow the user to access structures directly (forbid the
operator . or ->), because for that compiler must know how the structure
is organized, something that is often break when changed. Use accessor
functions.
     c) Totally hide the structure to the compiler, by just giving to it
a forward-declaration and the defining it in the .c that actually
creates the instances, so we don't tempt it to make weird optimizations
based on his knowledge about the structure or the user to see it (the
distributed .h headers would no contain any information about the
structure).
  Actually this is the Pimpl pattern [1].

JP

[1] http://en.wikipedia.org/wiki/Opaque_pointer#C