search

AcademySoftwareFoundation / MaterialX

MaterialX is an open standard for the exchange of rich material and look-development content across applications and renderers.
http://www.materialx.org/
Apache License 2.0
1.86k stars 352 forks source link

Clarify ABI compatibility rules in MaterialX #1789

Open christian-heusel opened 6 months ago

christian-heusel commented 6 months ago

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 commented 6 months ago

@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 commented 6 months ago

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

jstone-lucasfilm commented 6 months ago

@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 commented 6 months ago

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 commented 6 months ago

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:

https://github.com/AcademySoftwareFoundation/MaterialX/blob/97505091af01390b888905237ff6aef432bff2dc/source/MaterialXCore/CMakeLists.txt#L23