Re: [Plplot-devel] Definition of backward compatibility

[Rafael L. <rla...@us...>]

* Alan W. Irwin <ir...@be...> [2004-05-18 12:46]:

> So our choices now boil down to accepting an additional "no-brainer"
> maintenance issue of the SYMFILE approach for cutting down our exported
> symbols or not doing the SYMFILE approach at all and living with the
> consequences.  If we accept the standard definition of API as symbols
> exported from the library than the lack of SYMFILE approach simply means we
> have to work a little harder (as I have just done in plplotP.h) to avoid
> backwards incompatible API changes between our releases when we change the
> library soname.

To make the discussion more concrete, I tried to implement the SYMFILE idea
(the famous show-me-the-code-or-get-out-of-my-way approach).  Attached below
are two files: the first one is a SYMFILE candidate containing all the
symbols exported by libplplot.so that are referenced in plplot.h.
Unfortunately, building of PLplot with such a SYMFILE and the appropriate
-export-symbols libtool flag does not work.  The reason is because there are
other symbols outside those listed there that are needed in other parts of
PLplot.

The symbols listed in the second file attached below are needed by either
plserver, the f77 binding or the dynamically loaded drivers.  One can see
lots of pdf_* and plP_* symbols along with the embarrassing difilt symbol,
which pollutes too much the user's name sapace.

When I use the concatenation of this two files as the SYMFILE, then PLplot
builds and works correctly.

This exercise was quite disappointing.  Although the use of SYMFILE does a
good job by cutting down the number of externally visible symbols to around
two thirds, it cannot be a good way to define the external API.  Clearly,
there are two classes of symbols involved.  The first one (in the first
file) are the symbols that we really want to declare as external and that
users should use in their application.  The second one (the second file) are
symbols that are needed only internally to PLplot.

My concrete proposal is the following: let us forget about the SYMFILE and
make the clear statement that our external API is what is in plplot.h.
Changing the interfaces of the remainingfunctions exported by libplplot.so
would only affect the building of PLplot itself, and we are in total control
of that.  To give an example, changes in plP_gzback would have no impact in
user's application, in the sense that old application would not be broken
with a new version of plP_gzback in the library.

If there were users who used symbols outside plplot.h, I would consider them
as "power users", who can recompile their applications in the case where the
non-API interface changed and the soversion is kept the same.

I will document my proposal above soon and CVS commit it, such that you can
appreciate if this scheme is acceptable before the next release.

-- 
Rafael