Unity 6 iOS | Unable to load dynamic library '/realm-wrappers'

[samclothier]

What happened?

We have been having the following error in our iOS builds when building from a Unity project with Realm.NET 10.19 after updating from Unity 2021.3.42f1 to Unity 6. (see stack trace) It builds successfully in Xcode but has this error in the console when the game is run on an iOS device.

Realm runs perfectly on the Windows, Mac, and Linux builds from this project.

I first checked Xcode for problems with embedding and linking the realm-wrappers.framework, but it is included in the final archive:

Notably, this is different from the Frameworks folder we had in the archive before Unity 6:

The .meta files used to be present and the realm-wrappers file was automatically detected as UNIX executable. Now with Unity 6 it would have to be made executable with chmod +x realm-wrappers, but doing this before Xcode starts archiving results in the same error in the build above.

The output directly from Unity (before Xcode touches it) looks similar. Before Unity 6:

And after:

Additionally, under Library > PackageCache > io.realm.unity, the meta files appear to be present and the realm-wrappers is not an executable:

Inside Unity itself (before any build export has taken place) we noticed that the iOS realm-wrappers file was the only one that didn't have its platform ticked, although this also appeared to be the case in Unity 2021.3.42f1:

The equivalent on Android, for example, looks like this:

We don't know if the difference in the Frameworks folder is the actual issue or if it's just a symptom of a problem elsewhere.

We have tried deleting the package cache, reinstalling Realm into the project, and clearing the Library folder between builds. We have also tried updating Realm to the latest version but that caused other issues.

Note: using IL2CPP and .NET Standard 2.1

Repro steps

Using Realm.NET 10.19, currently trying to build an empty Unity 6 project with a debug window, ran directly from Xcode on a tethered device. It's proving very difficult to test.

Version

10.19

What Atlas Services are you using?

Local Database only

What type of application is this?

Unity

Client OS and version

iOS all versions

Code snippets

No response

Stacktrace of the exception/crash you're getting

DllNotFoundException: Unable to load DLL 'realm-wrappers'. Tried the load the following dynamic libraries: Unable to load dynamic library '/realm-wrappers' because of 'Failed to open the requested dynamic library (0x06000000) dlerror() = dlopen(/realm-wrappers, 0x0005): tried: '/realm-wrappers' (no such file), '/private/preboot/Cryptexes/OS/realm-wrappers' (no such file), '/realm-wrappers' (no such file)
Realms.SharedRealmHandle+NativeMethods.open (Realms.Native.Configuration configuration, Realms.Native.SchemaObject[] objects, System.Int32 objects_length, Realms.Native.SchemaProperty[] properties, System.Byte[] encryptionKey, Realms.NativeException& ex) (at <00000000000000000000000000000000>:0)
Realms.SharedRealmHandle.Open (Realms.Native.Configuration configuration, Realms.Schema.RealmSchema schema, System.Byte[] encryptionKey) (at <00000000000000000000000000000000>:0)
Realms.RealmConfiguration.CreateHandle (Realms.Schema.RealmSchema schema) (at <00000000000000000000000000000000>:0)
Realms.RealmConfigurationBase.CreateRealm () (at <00000000000000000000000000000000>:0)
RealmManager.InitialiseRealm () (at <00000000000000000000000000000000>:0)
RealmManager+<InitialiseServiceAsync>d__28.MoveNext () (at <00000000000000000000000000000000>:0)
UnityEngine.SetupCoroutine.InvokeMoveNext (System.Collections.IEnumerator enumerator, System.IntPtr returnValueAddress) (at <00000000000000000000000000000000>:0)

Relevant log output

[nirinchev]

So for previous Unity versions we needed to add a hacky workaround for the lack of support for xcframeworks. Unity 6 seems to add .xcframework support, which is why I'm guessing this is now broken and not behaving as intended. Since the Realm SDKs are now community supported, my suggestion would be to try and fix the issue and submit a PR (I'd be happy to review and provide feedback). To make it easier to iterate, it's probably best to first update to Realm 20.1.0 as that is the community version that doesn't include Atlas Device Sync, so it's a bit simpler. Then, you'd want to unarchive the io.realm.unity-20.1.0.tgz and import it as a filesystem package. Then, delete the Editor/Realm.UnityWeaver.dll file and replace it with the source code from the Realm.UnityWeaver + Realm.Weaver folders. Then, you can edit UnityWeaver.cs and check the Unity version and avoid applying the workaround in case it's Unity 6+.

[samclothier]

So for previous Unity versions we needed to add a hacky workaround for the lack of support for xcframeworks. Unity 6 seems to add .xcframework support, which is why I'm guessing this is now broken and not behaving as intended. Since the Realm SDKs are now community supported, my suggestion would be to try and fix the issue and submit a PR (I'd be happy to review and provide feedback). To make it easier to iterate, it's probably best to first update to Realm 20.1.0 as that is the community version that doesn't include Atlas Device Sync, so it's a bit simpler. Then, you'd want to unarchive the io.realm.unity-20.1.0.tgz and import it as a filesystem package. Then, delete the Editor/Realm.UnityWeaver.dll file and replace it with the source code from the Realm.UnityWeaver + Realm.Weaver folders. Then, you can edit UnityWeaver.cs and check the Unity version and avoid applying the workaround in case it's Unity 6+.

Thanks very much for the quick reply.
To clarify, do you think doing as you described (update to 20.1 and avoid applying the workaround) would fix the error, or would this just get me into the position where the problem could be looked at? Unfortunately I'd have no idea where to start with changing this to work as an .xcframework or with how to prevent the workaround being applied. Was this just a .framework pre-Unity 6?

[samclothier]

Update: Got Realm working with Unity 6 iOS exports. Turns out there is a compatibility issue between Realm's framework creation in Unity 6 with Xcode 15.4. All I had to do was update to Xcode 16.2 and all is well with Realm in Unity 6!

Long story short for iOS exports:

• Realm + Unity 2021/2 + Xcode 15.4 works
• Realm + Unity 6 + Xcode 15.4 does not work
• Realm + Unity 6 + Xcode 16.2 works

Some notes I made on this for future reference:

I don't understand why it was working for me in Unity 2021.3 because Unity claims that .xcframeworks are supported in Unity 2021.3, 2022.3 and Unity 6: https://discussions.unity.com/t/does-unity-support-xcframeworks/240687/5

xcframework generation and the workaround was introduced in Realm.NET 10.3: https://github.com/realm/realm-dotnet/pull/2475/files
but it was also mentioned since that xcframework is no longer generated and we are just dealing with a .framework in 10.19 and 20.1:
#2906 (comment)

So it seems that the workaround itself shouldn't be causing the issue, it's possible that this is just a Unity 6 compatibility issue.

It turns out that this was correct - just a compatibility issue caused by Unity 6 and Xcode 15. Probably not even something that needs fixing in Realm.NET.

[a178960320]

My Unity version is 2022.3.40, and this problem also occurred after upgrading to Xcode 16.2