Which Ice versions are binary compatible?

Ice version numbers use the scheme <major>.<minor>.<patch>. For example. Ice 3.7.1 is major version 3, minor version 7, and patch release 1.

Patch releases of Ice are binary compatible: you can always run a binary that was compiled with an earlier patch release with a later patch release of the Ice run time. For example, if you have a deployed application that was compiled with Ice 3.7.0, you can upgrade that application to use the Ice 3.7.1 run time simply by installing the new Ice libraries.

Exactly how to upgrade an existing Ice installation depends on the operating system and language mapping. Below are a few examples. Please see the release notes for your Ice installation for more detailed information.

On this page:

Binary Compatibility for C++ (Linux)

For Linux and C++, Ice uses symbolic links that that point at each shared library; the symbolic links do not include the patch release. For example, for Ice 3.7.0, Ice uses a symbolic link as follows:

libIce.so.37 -> libIce.so.3.7.0

The Ice libraries are built with -Wl,-h,libIce.so.37. This sets the dependent library name to libIce.so.37, so when you link your application against the library, the application has a dependency on libIce.so.37, not on libIce.so.3.7.0 or libIce.so.

When you upgrade Ice from an RPM installation, the installer automatically changes the symbolic links for the libraries to point at the new version. For example, when upgrading to Ice 3.7.1, the RPM updates the symbolic link to:

libIce.so.37 -> libIce.so.3.7.1

This means applications that used to use libIce.so.3.7.0 now automatically run with libIce.so.3.7.1 after the upgrade.

Binary Compatibility for C++ (macOS)

For a macOS brew installation, Ice uses symbolic links that that point at each shared library; the symbolic links do not include the patch release. For example, for Ice 3.7.0, Ice uses a symbolic link as follows:

libIce.37.dylib -> ../Cellar/ice37/3.7.0/lib/libIce.37.dylib

The install name of the Ice libraries installed with Brew is for example /usr/local/lib/libIce.37.dylib. So when you link your application against the library, the application has a dependency on this file, not on /usr/local/lib/libIce.3.7.0.dylib or /usr/local/lib/libIce.dylib.

When you upgrade Ice from a Brew installation, Brew automatically changes the symbolic links for the libraries to point at the new version. For example, when upgrading to Ice 3.7.1, Brew updates the symbolic link to:

libIce.37.dylib -> ../Cellar/ice37/3.7.1/lib/libIce.37.dylib

This means applications that used to use libIce.so.3.7.0 now automatically run with libIce.so.3.7.1 after the upgrade.

Binary Compatibility for C++ (Windows)

For Windows and C++, the library name excludes the patch release, so both Ice 3.7.0 and 3.7.1 libraries are installed as ice37.dll. You can upgrade an application compiled with Ice 3.7.0 to use Ice 3.7.1 by copying the new run-time libraries over the old ones.

Binary Compatibility for Java

For Java, you can upgrade an application by copying the new JAR archive over the old one, or by installing the new JAR file in a different location and changing the application's CLASSPATH accordingly.

Binary Compatibility for .NET

For .NET, the Ice run time libraries are usually installed in the Global Assembly Cache (GAC). For patch releases, the distribution includes policy files that redirect existing applications to the new run time. You can install these policy files in the GAC, so applications built against an earlier version of the Ice run time automatically use the newer version.