WCSLIB version numbers

The full WCSLIB/PGSBOX version number is composed of three integers in fields separated by periods:

• Major: the first number changes only when the ABI changes, a rare occurence (and the API never changes). Typically, the ABI changes when the contents of a struct change. For example, the contents of the linprm struct changed between 4.25.1 and 5.0.

  In practical terms, this number becomes the major version number of the WCSLIB sharable library, libwcs.so.<major>. To avoid possible segmentation faults or bus errors that may arise from the altered ABI, the dynamic (runtime) linker will not allow an application linked to a sharable library with a particular major version number to run with that of a different major version number.

  Application code must be recompiled and relinked to use a newer version of the WCSLIB sharable library with a new major version number.

• Minor: the second number changes when existing code is changed, whether due to added functionality or bug fixes. This becomes the minor version number of the WCSLIB sharable library, libwcs.so.<major>.<minor>.

  Because the ABI remains unchanged, older applications can use the new sharable library without needing to be recompiled, thus obtaining the benefit of bug fixes, speed enhancements, etc.

  Application code written subsequently to use the added functionality would, of course, need to be recompiled.

• Patch: the third number, which is often omitted, indicates a change to the build procedures, documentation, or test suite. It may also indicate changes to the utility applications (wcsware, HPXcvt, etc.), including the addition of new ones.

  However, the library itself, including the definitions in the header files, remains unaltered, so there is no point in recompiling applications.

The following describes what happens (or should happen) when WCSLIB's installation procedures are used on a typical Linux system using the GNU gcc compiler and GNU linker.

The sharable library should be installed as libwcs.so.<major>.<minor>, say libwcs.so.5.4 for concreteness, and a number of symbolic links created as follows:

  libwcs.so     -> libwcs.so.5
  libwcs.so.5   -> libwcs.so.5.4
  libwcs.so.5.4

When an application is linked using '-lwcs', the linker finds libwcs.so and the symlinks lead it to libwcs.so.5.4. However, that library's SONAME is actually 'libwcs.so.5', by virtue of linker options used when the sharable library was created, as can be seen by running

  readelf -d libwcs.so.5.4

Thus, when an application that was compiled and linked to libwcs.so.5.4 begins execution, the dynamic linker, ld.so, will attempt to bind it to libwcs.so.5, as can be seen by running

  ldd <application>

Later, when WCSLIB 5.15 is installed, the library symbolic links will become

  libwcs.so     -> libwcs.so.5
  libwcs.so.5   -> libwcs.so.5.5
  libwcs.so.5.4
  libwcs.so.5.5

Thus, even without being recompiled, existing applications will link automatically to libwcs.so.5.5 at runtime. In fact, libwcs.so.5.4 would no longer be used and could be deleted.

If WCSLIB 6.0 were to be installed at some later time, then the libwcs.so.6 libraries would be used for new compilations. However, the libwcs.so.5 libraries must be left in place for existing executables that still require them:

  libwcs.so     -> libwcs.so.6
  libwcs.so.6   -> libwcs.so.6.0
  libwcs.so.6.0
  libwcs.so.5   -> libwcs.so.5.5
  libwcs.so.5.5