[cctbxbb] Module versioning (was Re: Debian Package)

[Jeffrey Van Voorst]

On 9/1/12 4:35 AM, Radostan Riedel wrote:
> On Sat, 01. Sep 03:33, Luc Bourhis wrote:
>> Now going back to patch 0007-adding-shlib-versioning, is it correct that we would just need to do:
>> 	env.Append(SHLINKFLAGS= [ "--version-info=c.r.a" ]
>>   for the env that build a particular .so? Well, that would be for gcc and clang only of course. To be cross-platform  I would suggest adding a pseudo-builder SetVersionInfo(vers) that does the right thing on Unix and nothing on Windows (for the time being, as perhaps there is a similar mechanism with msvc).
> That's a good idea. I'll try to rework by patch to ease everything up.
>> But your well-written patch and that little sugar are the easy part as they are of the write once, reuse forever nature. We need a workflow here and the two extremes would be as follow.
>>
>> 1. Each and every cctbx developer becomes aware of so-versioning. Let's say a module is at 2.3.4, so we have
>> 	env.SetVersionInfo(vers="2.3.4")
>> and then a change is made to the C++ code. The developer responsible for that change should then figure out the new c.r.a and then add a comment
>> 	env.SetVersionInfo(vers="2.3.4", #next release# vers="c.r.a")
>> It would then be easy to automate an edit en-masse before release that would change that line and all its sisters to
>> 	env.SetVersionInfo(vers="c.r.a")
>> That's basically a formalised version of your proposition in your answer to Johan earlier.
>>
>> 2. Cctbx developers would not care about so-versioning and before a Debian release, the cctbx Debian maintainers would go through each call to SetVersionInfo to set the right c.r.a, based on a careful examination of the commits, complemented by asking questions to the core cctbx developers (or simply open questions on this forum).
> I'd of course like the first extreme better. For starters  it would be great if
> everyone feels responsible for the "current" number. I'm not a c++ developer and
> I don't know if thats easy?
I could be wrong, but here is my understanding + 2 cents.  The version 
info is really for the API and not for code changes that do not affect 
the API.  Therefore, updating an implementation based on a more 
effective algorithm will not change the version info unless it requires 
a new API.  In other words, improving a refinement method would not 
require a change to the .so number provided the "public" interface to 
the method was not altered (of course a version bump to the cctbx 
package itself would be probably be desirable).

If someone is really excited about this or finds it very important, I 
think the model presented by the sqlite library is simple enough. It 
distills to: here is the external API (it will be static unless there is 
a good reason to change it); all other C function prototypes may change 
at any time.  I know that designing an API takes a significant effort, 
but if done sufficiently well, it allows for significant hacking of the 
code without having to break existing programs that depend on the 
library.  Also, cctbx much more complicated and has quite a few warts 
when compared with sqlite, and versioning works rather well for 
procedure based programming, but possibly less so for languages that 
support constructs such as iterators.

The existence of such an API would not preclude hacks to get cctbx to 
interface with Phenix or other code.  However, if such a documented API 
existed and some set of rules were followed, it would allow students and 
other smaller groups to design C or C++ code that would not depend on a 
specific version of cctbx.

With respect to Python, it is my opinion that it only becomes a problem 
if something is removed from the API.  However, I am less knowledgeable 
about how to handle Python as the general consensus is to have a virtual 
environment (virtualenv) for each project as Python on Linux and Mac OS 
X is rather a mess (several different versions of Python 2 and 3 + 
Cython, Boost.Python, SIP, SWIG, etc.)

--Jeff Van Voorst