Rogier Wolff wrote:
> On Mon, Jun 18, 2012 at 02:10:10PM +0200, Thomas Jarosch wrote:
> > On Monday, 11. June 2012 22:21:58 Thomas Jarosch wrote:
> > > I propose the following changes for libftdi 1.x
> > > ------------------------------------------------------------
> > > - libftdi-config -> libftdi-1.0-config
> > > - ftdi.h -> /usr/include/ftdi-1.0.h
> > > - libftdi.pc -> libftdi-1.0.pc (pkgconfig file). Also "libftdipp-1.0.pc"
> > > - we can't do much about possible man page clashes.
> > > You can't prefix them in doxygen, just redirect
> > > the output to a non-default directory
> > > - Rename "libftdi.spec" to "libftdi-1.0.spec"
> > > ------------------------------------------------------------
> > >
> > > Now the big question: Should we also change the library name to
> > > "libftdi-1.0"? IMHO it's a good idea since broken linker flags might
> > > point to the previous libftdi 0.1 and result in very bogus error
> > > messages.
> >
> > So, any opinion on this, especially the last one?
>
> IMHO, 95% of the use cases don't care what version of a library is
> available. Even though the version number is bumped because of an
> incompatible application-interface, not all users will be affected.
>
> So I write an app. I check the changes, find nothing changes for me so
> I dutifully adapt my includes to:
>
> #include <ftdi-1.0.h>
>
> Two years from now, my app still runs without any maintenance
> required. It's something simple, so no bugs found, not many users but
> those that use it are happy. A new version of libftdi comes out. 2.0!
> So for the apps that still use libftdi-1.0, the headers, and libraries
> are kept around. Anohter two years go by. Still my app is unmaintained
> because it simply works. And it's simple: The API changes don't affect
> it. But now the distributions are bored from keeping the old stuff
> around. So libftdi-1.0 is dropped.
>
> Now I HAVE to go in and change the source to say:
>
> #include <libftdi-2.0.h>
>
> Not happy.
.. (suggestions snipped)
Agreed. I'd go one further and say that we should be strive to keep
API compatibility whenever possible. The linker (with sonames, symbol
versioning, etc) can handle ABI changes and parallel installed
versions, so it's really a matter of just being careful when making
incompatible changes to the API, and bumping the soname when changing
the ABI.
What APIs were broken between libftdi-0.x and libftdi-1.x? Can they
be fixed? Even if not, we should strive to maintain compatibility in
the future so we don't just run into this problem again. For example,
adding a version or size field to struct ftdi_context would let us
determine in the library which API the binary was compiled against.
For functions with a changed implementation, the old implementation
should be maintained as-is or with a compatibility shim, and the new
implemtation should be given a new name.
Some thoughts on maintaining good compatibility between library
versions can be found in:
Ulrich Drepper's Good Practices in library design, implementation, and
maintenance:
http://www.akkadia.org/drepper/goodpractice.pdf
Ulrich Drepper's How to write shared libraries:
http://www.akkadia.org/drepper/dsohowto.pdf
Mike Hearn's Writing shared libraries:
http://plan99.net/~mike/writing-shared-libraries.html
With the right design and care on the library end, the API can be made
stable enough that a user application can simply include the system's
single /usr/include/ftdi.h and be confident that the code will still
continue to compile and run correctly even if a new version of libftdi
is installed.
-jim
--
libftdi - see http://www.intra2net.com/en/developer/libftdi for details.
To unsubscribe send a mail to libftdi+unsubscribe@xxxxxxxxxxxxxxxxxxxxxxx
|
