I am going to number Rafael's possibilities to facilitate further comment.
On 2004-05-17 16:59+0200 Rafael Laboissiere wrote:
> (1) The externally visible functions in the shared library libplplot.so.
> This definition is the most "natural" one, because programs linking
> against libplplot would be broken if the interface for any of the
> functions exported by libplplot is changed. However, there are way too
> many functions exported (especially the plP_* ones) and this is an
> impractical definition of the API. BTW, this excess of external symbols
> is due to the fact that many of the source files src/*.c do not define
> internal functions as "static" (e.g. plP_gzbackw defined in plot3d.c and
> called in plbox.c).
> (2) The functions and constants declared in plplot.h
> This is a quite good solution. Notice, however, that we distribute
> other *.h files as well and users may be tempted to believe that changes
> in plplotP.h (for instance) would also imply backwards
> (3) The functions described in the Docbook manual
> This is a good solution too, because users are expected to use what is
> clearly documented. As today, this definition would exclude plimage
> from the API, for instance. If we go for this solution, then we must
> update the manual before the release.
> (4) The functions used in the x*c.c demos
> This is a necessary, but not sufficient definition. However, I very
> much like this idea, because it gives me a practical regression test.
> The last alternative above brings me to the second point I would like to
> discuss. During the release process it is quite difficult to decide whether
> the library is or is not backwards incompatible. Clearly, we need a
> regression test, preferably something that can be automated. It could go
> like this: (1) Install the previous released version of PLplot. (2) Compile
> all the C examples. (3) Install the new version with the same soversion as
> the previous one. (4) Try to run the examples. If no backwards
> incompatibilites were introduced, then the examples would link and run
> I have to make some decisions now and your comments on the above are
Note our current documentation purports to document everything in plplot.h,
but it currently falls far short of that (in general only the "common" API
subset is documented) and will probably always be behind what is in plplot.h
so I would drop (3) as a possibility, and instead limit our choices to (1),
(2), or (4).
Also note our examples are grossly incomplete. For example, very few of the
plg* family of functions are represented in the examples. I do believe
Rafael's idea of automatic testing of API changes is an excellent one and
should be implemented regardless (just in case somebody made a backwards
incompatible API change affecting the examples without realizing it), but
that is clearly a necessary but not sufficient test. I think what we really
need is a clear decision between options (1) and (2) for defining what is
meant by our API.
I lean toward using a rigourous model (e.g. option 1) for defining what is
meant by our API. I agree few users will actually include plplotP.h and use
functions defined in there, but I am sure some will and they should expect
that our soversion reflects our rigourous API, not a subset of it as in (2).
Whenever I have read any discussion of soname, there has been no compromise
on what is meant by the API, and I think we should make no compromise on
that definition as well.
What started this discussion with Rafael is I recently had to change
argument lists for routines in plplotP.h. I did it as added API cont_storel
and plP_gzbackw and left the now unused (by us) cont_store and plP_gzback so
we wouldn't have backwards incompatible changes in the rigourous API that
forced us to change our soname.
In any case, I don't think we should have a constant dribble of backwards
incompatible changes. Instead, I think we should follow what most major
software projects (e.g., KDE) do in this regard. That is have a constant
soname (and necessary bloating of the rigourous API to keep from having
backwards incompatible changes) for several releases, and then say once per
year or two have a release where we allow changing the soname and
introducing backwards incompatible API changes (such as renaming cont_storel
and plP_gzbackw to cont_store and plP_gzback) to get rid of the API bloat
that has accumulated.
Alan W. Irwin
Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).
Programming affiliations with the PLplot scientific plotting software
package (plplot.org), the Yorick front-end to PLplot (yplot.sf.net), the
Loads of Linux Links project (loll.sf.net), and the Linux Brochure Project