Clarify ABI compatibility rules in MaterialX

[christian-heusel]

It seems like the recently released version broke some ABI:

blender: symbol lookup error: /usr/lib/libusd_ms.so: undefined symbol: _ZTIN17MaterialX_v1_38_97ElementE

---

This was first reported on https://gitlab.archlinux.org/archlinux/packaging/packages/blender/-/issues/17
CC @svenstaro

[jstone-lucasfilm]

@christian-heusel We could use some additional context on this one, as it's not an issue that we've yet heard about from other teams integrating MaterialX and USD!

[christian-heusel]

@jstone-lucasfilm sure! What information would be of use for you?

[jstone-lucasfilm]

@christian-heusel Is this an issue that requires the full Blender application for a repro, or are there ways to trigger this using MaterialX or USD/MaterialX alone? And with respect to ABI compatibility, we usually expect only API compatibility between versions of USD and MaterialX, so I could use more context on the situation where ABI compatibility for these two projects is important.

[svenstaro]

The general way that most software projects handle this is that if either API or ABI become incompatible, there's a soname version bump and at least a minor version increase. This sends a clear signal to distribution maintainers and so we can rebuild accordingly. A patch version increase is a sign of "it's only a fix without any API/ABI changes" so it'd be safe to push without rebuilding dependents.

I'd prefer if you adopted that way of using semver as this would ease our maintenance burden somewhat.

[jstone-lucasfilm]

Ah, I see what you mean, @svenstaro.

As far as I know, neither the USD nor MaterialX projects provide ABI compatibility between released versions, but we can likely do a better job of signaling this through our VERSION and SOVERSION settings.

Because the major and minor versions of each MaterialX codebase must match those of the associated MaterialX specification, we have slightly less freedom with regard to semver conventions, and we document our current approach here:

https://github.com/AcademySoftwareFoundation/MaterialX/blob/main/documents/DeveloperGuide/MainPage.md#materialx-versioning

We're open to ideas on how to better signal that we don't provide ABI compatibility between MaterialX versions, and here is the current logic that we use to set the VERSION and SOVERSION properties in our CMake process:

MaterialX/source/MaterialXCore/CMakeLists.txt

Line 23 in 9750509

VERSION "${MATERIALX_LIBRARY_VERSION}"