Versioning of APIs

We are trying to make changes in backwards compatible ways, this is why sometimes we don't modify an existing API but add a new one, like foo_v2. Such changes, as well as bug fixes (which do not affect the API, just the internal workings) will not affect developers of EosSdk applications and will be indicated by a patch version number increase (libeos.so.1.2.3 -> libeos.so.1.2.4).

If a developer wants to use the new foo_v2 feature and build an application that might run on older switches, he could check the running version (see eos/version.h) and conditionally use that feature (in order to prevent a runtime issue).

Sometimes (hopefully rarely) changes cannot be done in a binary backwards compatible way. In this cases, the application has to be recompiled against the new headers. This case is indicated by a bump in the minor version number (libeos.so.1.2.3 -> libeos.so.1.3.0).

In cases the API has to change so dramatically that the application's code has to be modified, then we increase the major version number (libeos.so.1.2.3 -> libeos.2.0.0). This happened once so far, and was required because of legal issues, will never happen again (!knock on wood!).

In other words, we adhere to "semantic versioning".

On the switch, you will find:

-bash-4.2# ls -l /usr/lib64/libeos.so*
lrwxrwxrwx 1 root root      16 Jun 17 06:42 /usr/lib64/libeos.so -> libeos.so.2.22.1
lrwxrwxrwx 1 root root      16 Jun 17 06:42 /usr/lib64/libeos.so.2 -> libeos.so.2.22.1
lrwxrwxrwx 1 root root      16 Jun 17 06:42 /usr/lib64/libeos.so.2.22 -> libeos.so.2.22.1
-rwxr-xr-x 1 root root 5619256 Jun 17 06:42 /usr/lib64/libeos.so.2.22.1
-bash-4.2# objdump -x /usr/lib64/libeos.so.2.22.1 | grep SONAME
  SONAME               libeos.so.2.22
-bash-4.2#

If you use build.sh (in EosSdk-stubs-2.22.1.tar.gz) to build the stubbed libeos.so you will need to link your application, then the SONAME of libeos.so will be libeos.so.<major>.<minor>. So if your application is built against this stubbed libeos.so, when the application wants to run, it will look for libeos.so.2.22, not libeos.so or libeos.so.2.22.1 and so it will find whatever patch version is installed on that switch since libeos.so.2.22 points to that, which is fine since they are all binary compatible.

As you can see from the demo application that gets built at the same time as your stubbed libeos.so:

> ldd .libs/HelloWorld  | grep libeos
        libeos.so.2.22 => /lib/libeos.so.2.22 (0xf736c000)

Also, if you download your application onto a switch that is still running EosSdk 2.21, then the linker will not find what it is looking for when asked to start your application and it will fail hard (instead of crashing miserably some time later). So all this versioning and SONAME stuff is used to prevent binary incompatibilities (it does rely on the SONAME, which not all build system handle right according to the rules of semantic versioning, so do use build.sh).