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 [email protected]
