20th June 2003 by Derek Kite

This Week...

K3b, one of the Kde CD writing applications, has started work on dvd writing. Continued fixes and improvements to Kwin. And more bug fixes.
Every so often one sees the acronym BIC or BC included in a cvs commit. They refer to Binary Incompatible, or Binary Compatible. What this means is that the library binary interface is stable or compatible, so that you could update kdelibs to get the new Khtml, and bug fixes, without recompiling or breaking an application that depends on the libraries. This also means a binary application written for Kde 3.0 would run under Kde 3.2. But what if the libraries aren't finished when a major release comes along? Or, from use a programmer finds the interface lacking, and wants to make it better? Peppered throughout the Kde code base are notes of things to fix for Kde 4.0, which will break binary compatibility. But in the meantime, bc is maintained. So when a change was made to kdelibs/kabc (kaddress book libraries) which broke binary compatibility, quite a discussion ensued. It was found that there were a few other incompatibilities introduced along the way. What follows outlines some of the issues involved.
Cornelius Schumacher, who is one of the Kaddressbook maintainers said:
KABC::Resource and its subclasses are internal to libkabc. They aren't meant for public use yet. We install the headers because there is some code outside kdelibs using it, but they are clearly marked as internal, so the binary compatibility rules don't apply here.


There are many ways to write applications which break when upgrading kdelibs, no matter how good we are with maintaining binary compatibility. I don't think we have to care for companies writing code which relies on undocumented classes marked as internal without contacting the author of these classes whose email address is clearly stated in the header of the class.
Let's just say, not everyone agreed. Bo Thorsen said:
BIC isn't about KDE stuff since kde{pim,network,base...} are shipped with kdelibs. It's about apps outside KDE.

And inheriting isn't the problem. If you instantiate this class with code built against the old version of it, you get a crash.
And Dirk Mueller repeated for emphasis:
well, if there is some code outside kdelibs using it, then that code will crash when kdelibs is updated, right?
And Simon Hausmann made the same point:
I don't think the main problem is about being afraid of third party developers using the 'internal' interfaces in public header files, the problem is that the _users_ will run into the crashes because a non-third party developer used the interfaces.

My understanding of the non-written binary compatibility policy for kdelibs is that you can safely upgrade kdelibs without _having_ to upgrade other packages as well. (say for example because you want the latest & greatest khtml)
Marking things internal makes for great fun. There is something irresistable about an undocumented or internal interface. They become useful, even necessary for some reason. But a programmer needs to get a release done, knows that things will change and improve the next iteration. He doesn't want anyone depending on something that is intended to change. And, with free and open source software, the code is available, allowing a recompile. This is actually a 'feature', and has the added side benefit of unsubtly discouraging closed source binaries. On the other hand, Ian Reinhart Geiser spoke from experience:
...They have luckily learned their lesson and we are moving away from KAB for a more stable Mozilla/LDAP based system. But still... We cannot keep proving our imaturity as an API every release.

Unless we decide we want to keep BC/SC in KDE libs, then IMHO they have no business in there.

Just my 2c as someone who mistakenly recommended KAB to a client.
And with further explanation:
Well at the time in KDE 3.0 they where not internal, and lack of documentation has NEVER stopped KDE in the past. Since we used them in the KDE SDK plugin. Like I said it seemed like a good idea at the time. Since KAB has a habit of using its "internal" apis in some very public non kab apps, you only ensure people will use them. Otherwise we need to maybe audit KPilot and the other addressbook plugins.

Note I'm not trying to be hypercritical here, its just KAB is to the point that its useful enough to start using in the real world... but not stable enough to rely on.
Zack Rusin who volunteered to fix the mess said:
I don't think it's fair. Marking it as internal, installing it and using it outside kabc fall in no category under the term "internal". What I'm planning to do is to rename the new Resource class to StdResource and move it to stdresource.{h,cpp} and then revert resource.{h,cpp} to KDE_3_1_BRANCH and mark constructors with KDE_DEPRECATED. My opinion is this: every class in an installed header has to keep BC, marking it as internal doesn't solve the problem. Opinions? I don't want to be doing Resource->StdResource stuff unless I have support of other developers since it's definitely not the most exciting or easiest jobs.
Cornelius Schumacher then requested:
I think we should really clarify what we guarantee in terms of binary, source, behaviour, whatever compatibility for our libraries. It has always been hard to use the KDE framework for third-party developers. If we want to attract users of the API from outside of the project, in particular commercial users, we can't rely on assumptions like "this undocumented API is safe because it is used in other modules".

No commits found