Opened 5 years ago

Last modified 4 years ago

#3771 reviewing enhancement

add versioning for shared libraries

Reported by: fdupont Owned by: marcin
Priority: low Milestone: Outstanding Tasks
Component: Unclassified Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

We really need a version control system for KEA: today when an API is changed, for instance the number of arguments of a function is modified, nothing prevents someone to use a wrong library.
There are well documented solutions, BTW bind9 had the same problem so we have good examples too.
Note the #3764 uses a per shared library include file name "api.h" which can be reused (but the idea is not to depend on #3764, just to share some ideas from it).

Subtickets

Change History (21)

comment:1 Changed 5 years ago by fdupont

Libtool doc: http://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
Bind9: per lib version (string), interface, revision, age (numbers). They are exported values (under Windows) generated by configure from a per lib api file. I remember to have seen a lot of messages saying one of these must be bumped after a change.

comment:2 Changed 5 years ago by jreed

Let's discuss this at a weekly meeting or at all-hands.

We had some definitions about it in the wiki already
http://kea.isc.org/wiki/LibraryVersioning

The release engineering steps have step to check this for sanity checks but we don't really follow it yet since we never got to a 1.0 release yet. We need to decide now how we will proceed prior to that though.

comment:3 Changed 5 years ago by hschempf

  • Milestone changed from Kea-proposed to Kea0.9.2

comment:4 Changed 5 years ago by fdupont

I can take it when the visibility (#3764) support will be ready if the implied dependency is not a problem...

comment:5 Changed 4 years ago by tomek

  • Priority changed from medium to low

Decreasing priority to 0.9.2 as discussed on 2015-06-10 kea call.

comment:6 Changed 4 years ago by fdupont

I believed this ticket was for after 0.9.2? Note we can wait until the release process...

comment:7 Changed 4 years ago by tomek

  • Milestone changed from Kea0.9.2 to Kea0.9.2-final

comment:8 Changed 4 years ago by fdupont

I am afraid there are some misunstanding about this ticket: what is its exact goal?

comment:9 Changed 4 years ago by fdupont

  • Owner set to fdupont
  • Status changed from new to accepted

My proposal:

  • a script to produce api, api.h and version.cc files and patch Makefile.am
  • applies the script to all shared library directories
  • modify Makefiles.am (the script can't do everything)
  • add versioning support in configure.ac

I suggest to start with something like 3:0:0.
BTW my model in bind9, i.e., what has been good for bind9 since many years should be good for Kea (even if C++ is far less sensible to API changes than C, i.e., it failed to link or dynamic link vs. crash).

comment:10 Changed 4 years ago by fdupont

  • Owner changed from fdupont to UnAssigned
  • Status changed from accepted to reviewing

Done at a336befa6a72a3073dd9bd951adb49c2828f8aaa commit. Already available for review but I have still to:

  • complete the versioning documentation
  • fix some missing dependencies.

comment:11 Changed 4 years ago by fdupont

Pushed the missing dependencies. Commit ce72fb10ff1f863649fb2112a38663efcea6ab1d.
Still the documentation to update (outside the review scope?)

comment:12 Changed 4 years ago by fdupont

Linked the LibraryVersioning as reference into the Designs and added LibraryVersioningImpl new document to describe this implementation.

comment:13 in reply to: ↑ description ; follow-up: Changed 4 years ago by jreed

Replying to fdupont:

We really need a version control system for KEA: today when an API is changed, for instance the number of arguments of a function is modified, nothing prevents someone to use a wrong library.

I am still confused about that initial problem statement. Our libraries already have versioning, for example: libkea-dns++.so.2.0.0, libkea-dhcp++.so.2.0.0, libkea-cfgclient.so.0.1.0, libkea-asiolink.so.0.1.0, libkea-dhcpsrv.so.3.0.0, and libkea-log.so.1.0.0.

Yes, some developers and release engineers may neglect to update the -version-info flag, but sometimes do remember.

How does the more complex solution help us versus the existing technique?

comment:14 in reply to: ↑ 13 ; follow-up: Changed 4 years ago by fdupont

Replying to jreed:

I am still confused about that initial problem statement.

=> use versioning in an uniform and systematic way.

Our libraries already have versioning,

=> yes some have but not all and there is no complete policy or procedure.

for example: libkea-dns++.so.2.0.0, libkea-dhcp++.so.2.0.0, libkea-cfgclient.so.0.1.0, libkea-asiolink.so.0.1.0, libkea-dhcpsrv.so.3.0.0, and libkea-log.so.1.0.0.

=> note your examples are very system specific, i.e., the libel versioning is not the system library numbering (cf the libtool doc for details).

Yes, some developers and release engineers may neglect to update the -version-info flag, but sometimes do remember.

=> I proposed to move to the bind9 procedures (and mechanisms) as they are known to work well.

How does the more complex solution help us versus the existing technique?

=> the benefits will be on the long term of course. Note I opened this ticket because I was asked to, and it was added to 0.9.2 so I believe there is a rough agreement about to do something (to summary you are a bit late :-).

comment:15 in reply to: ↑ 14 ; follow-up: Changed 4 years ago by marcin

Replying to fdupont:

Replying to jreed:

I am still confused about that initial problem statement.

=> use versioning in an uniform and systematic way.

Our libraries already have versioning,

=> yes some have but not all and there is no complete policy or procedure.

for example: libkea-dns++.so.2.0.0, libkea-dhcp++.so.2.0.0, libkea-cfgclient.so.0.1.0, libkea-asiolink.so.0.1.0, libkea-dhcpsrv.so.3.0.0, and libkea-log.so.1.0.0.

=> note your examples are very system specific, i.e., the libel versioning is not the system library numbering (cf the libtool doc for details).

Yes, some developers and release engineers may neglect to update the -version-info flag, but sometimes do remember.

=> I proposed to move to the bind9 procedures (and mechanisms) as they are known to work well.

How does the more complex solution help us versus the existing technique?

=> the benefits will be on the long term of course. Note I opened this ticket because I was asked to, and it was added to 0.9.2 so I believe there is a rough agreement about to do something (to summary you are a bit late :-).

So I spent a while trying to figure out how the introduction of the "api" file, from which the api.h and version.cc is generated, helps in avoiding the crash, and causing the link failure instead? After a while I figured that this change doesn't really help resolving it, because bumping up the version numbers in each Makefile.am, using the --version-info, parameter already resolves the problem.

So, am I correct that this change is mostly about providing an "alternative" way to manage version numbers in a sense that instead of modifying the --version-info in the Makefile.am directly I'd need to modify the contents of the "api" file?

To be clear, I am not opposed to this change, as it may be a bit cleaner approach. However, the amount of manual work here is the same as in case of bumping up the version numbers in Makefile.am directly.

One more improvement is the sanity check in the configure.ac file that all libs have version information specified.

comment:16 Changed 4 years ago by marcin

  • Milestone changed from Kea0.9.2 to Kea1.0

Moving to 1.0 low as per ticket crub on 07/31/2015

comment:17 in reply to: ↑ 15 Changed 4 years ago by fdupont

So I spent a while trying to figure out how the introduction of the "api" file, from which the api.h and version.cc is generated, helps in avoiding the crash, and causing the link failure instead? After a while I figured that this change doesn't really help resolving it, because bumping up the version numbers in each Makefile.am, using the --version-info, parameter already resolves the problem.

=> yes, any versioning solves the problem.

So, am I correct that this change is mostly about providing an "alternative" way to manage version numbers in a sense that instead of modifying the --version-info in the Makefile.am directly I'd need to modify the contents of the "api" file?

=> not "alternative" but cleaner way. Note I copied the way the same problem (versioning) was handled by bind9. And the api* files are required for visibility stuff too so it is not overkilling.

To be clear, I am not opposed to this change, as it may be a bit cleaner approach. However, the amount of manual work here is the same as in case of bumping up the version numbers in Makefile.am directly.

=> unfortunately if we want the 3 versioning values per library the amount of manual work will have a minimum...

One more improvement is the sanity check in the configure.ac file that all libs have version information specified.

=> do you propose to have an api.in file per library so configure will break if one is not present? (I am trying to understand your statement).

comment:18 Changed 4 years ago by marcin

Quick note: we're going to discuss whether we want to use visibility or not on the next Kea call on August 19th. I'll continue with the review after that discussion.

comment:19 Changed 4 years ago by marcin

  • Owner changed from UnAssigned to marcin

comment:20 Changed 4 years ago by stephen

  • Milestone changed from Kea1.0 to DHCP Outstanding Tasks

As per Kea planning meeting in October, remove from 1.0.

comment:21 Changed 4 years ago by tomek

  • Milestone changed from DHCP Outstanding Tasks to Outstanding Tasks

Milestone renamed

Note: See TracTickets for help on using tickets.