libcrystalhd major version

[Anssi Hannula]

Hi all!

I've noticed that the major version of libcrystalhd has been raised twice
already this year (from 1 to 2 to 3).

Bump to 2 was on 2010-03-26, and bump to 3 was on 2010-07-24.

However, when I looked in the history of the header files, I noticed that
neither of those bumps was accompanied with backward-compatibility breaking
changes.

I noticed only one such incompatible change, but that was on 2010-06-06:
BC_MSUBTYPE_DIVX311 was added in the middle of enum BC_MEDIA_SUBTYPE, so while
value 10 previously stood for BC_MSUBTYPE_OTHERS, it now stands for
BC_MSUBTYPE_DIVX311. Interestingly, there are no references to
BC_MSUBTYPE_OTHERS in the code. Is it used? If not, should it not be removed?

The major version should only be raised when there is a backwards-incompatible
ABI change. If you change it more often than that, it requires all
applications to be recompiled against the newer version for no reason. (If you
don't raise it when an ABI break happens, the applications using old ABI may
break)

Was there some reason for the changes in the major version that I did not see?
If not, I'd appreciate it if you stopped changing the major version when it is
not needed. For backward-compatible changes, minor should be raised instead.

Also, it is not a good idea to add values to the middle of an enum list if the
following values are part of the library ABI, as those will shift by one. If
you have to do that for some reason, you also need to raise the major version.

--
Anssi Hannula
Mandriva Linux package maintainer

[Naren (Narendra) Sankar]

The reason it was changed is because we merged functionality to the windows code base and there are certain "coming soon" applications that depended on the version number (the major) to be 3 so that they could have common code base between windows and linux and osx.

Going forward we do not expect this to change and also the enums to be stable.

The linux code base had gone stale over a period of time and this major change was needed to keep it aligned to our main firmware tree and windows tree.

Agree with your points about backwards compatibility and other changes.

But since this is a one time event, please let it slide and we will make sure this stays stable in the future as we constantly keep the various codebases aligned

Thanks

Naren
BRCM

--
To post to this group, send email to
crystalhd-...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/crystalhd-development?hl=en

[Anssi Hannula]

It sounds like you may be using the same number for two different things.
Maybe there should be a separate linux library major/minor version so that it
can be changed or not changed at proper times?

This is actually how linux libraries commonly do it, i.e. they library
filename is completely separate from the project version number.

To pick a random example, e.g. libvoikko version 3.0 has the library name
libvoikko.so.1.11.0, meaning that APIs have been added 11 times, but none have
been ever removed/broken, i.e. it is still ABI compatible with programs
compiled for the original libvoikko.so.1.0.0.

For another example, SDL_gfx library version 2.0.21 has the library name
libSDL_gfx.so.13.5.2.

--
Anssi Hannula

[Scott D. Davilla]

>It sounds like you may be using the same number for two different things.
>Maybe there should be a separate linux library major/minor version so that it
>can be changed or not changed at proper times?
>
>This is actually how linux libraries commonly do it, i.e. they library
>filename is completely separate from the project version number.
>
>To pick a random example, e.g. libvoikko version 3.0 has the library name
>libvoikko.so.1.11.0, meaning that APIs have been added 11 times, but none have
>been ever removed/broken, i.e. it is still ABI compatible with programs
>compiled for the original libvoikko.so.1.0.0.
>
>For another example, SDL_gfx library version 2.0.21 has the library name
>libSDL_gfx.so.13.5.2.

As Naren has already explained, this bump is to align versions over
the three platforms (OSX, Linux and Windows) that the CrystalHD API
supports. This is more important in the long run for platform
Application parity than any short term issue it might create on a
single platform.

[Anssi Hannula]

Yes, but the library soname should still be handled independently from the
crystalhd version. Having the library named libcrystalhd.so.2.x doesn't
prevent the version number from being 3.5.

The advise from libtool documentation applies here (even though we are not
really using libtool in crystalhd, but this is the same situation):
"Never try to set the interface numbers so that they correspond to the release
number of your package. This is an abuse that only fosters misunderstanding of
the purpose of library versions."

Meaning that crystalhd library name shouldn't be libcrystalhd.so.3.5 just
because the crystalhd version is 3.5.

--
Anssi Hannula

[Naren (Narendra) Sankar]

Anssi

I completely agree with the spirit of what you are saying. And this is how we intend to work going forward. There is a separate library version that will be incremented as need be.

The file versions will not require changes going forward.

However what is not obvious from the timeline of development is how significant are the changes in the API structures.

When we added support for the BCM70015, we had to change a lot of the API implementations and these do impact applications, though in not obvious ways, since the API definitions themselves did not change most of the time.

One example is that in the past we only supported AVC Annex B streams and it was the application responsibility to convert bitstream data to bytestream. Now that work is done in the library layer so all applications can have the same API structure and usage.

There are lots of other similar changes, some HW specific that were incorporated.

So while the ABI/API did not exactly "change", backwards application compatibility was completely broken.

Hence when we cleaned up the code on Linux, I wanted to indicate to every application user that this library is completely different than what went before and hence the file version bump to match up with what the other OS/platforms are using.

This should not happen going forward and hence the rules as you desire them to be will be followed.

Again, this was just a onetime event to sync up all OS and HW platforms to the same code base.

Naren Sankar (+1 408 218 6327)
Architect/PLM
Media PC, Broadband Communications Group
Broadcom Corp.

--
Anssi Hannula

--

[Anssi Hannula]

Thanks for the replies and information.

And in case I left a wrong impression... This didn't actually cause any
serious problems for us (crystalhd is just one lib, after all, and not linked
against by too many applications), I just wanted to inform you of the usual
practices regarding library filenames/sonames :)

--
Anssi Hannula

[Naren (Narendra) Sankar]

No problem. I understand your concerns going forward and it is good to make sure that we all follow the same rules to make everyone's life easier overall.

Thanks

--
Anssi Hannula

--
Anssi Hannula

--