iOS support

[p-lindberg]

The base library is built for iOS, but I don't believe the current approach works in practice. In my preliminary testing it failed to load the library at runtime (although I should mention this was in a Unity game, where the iOS build pipeline is a bit finicky).

Are you currently verifying the iOS support in any way?

I'm not an iOS developer by trade, but based on what I know from previous experience with integrating native libraries on iOS, in order to properly load a dylib on an iOS device,

• It must be wrapped in a framework (basically a directory named {library_name}.framework, containing the library and an Info.plist file with various metadata).
• The library file itself should not have a file extension (but this might just be convention)
• The library's install name property should be of the form @rpath/{library_name}.framework/{library_name}. This can be set using install_name_tool -id {new_install_name} path/to/library on MacOS (and read using otool -l path/to/library). I'm not 100% sure if the @rpath/ prefix is necessary though, as I don't remember the exact details around it right now.

AFAIK, it is possible to load a "bare" .dylib file, but it only works in development builds and will fail when attempting to build a release archive, specifically due to code signing issues IIRC.

Oh, and the current install name is liblmdb.so (set by the compiler, not updated when the file gets renamed), which is probably why it fails to load right now, even in development builds.

Setting up a proper Xcode build pipeline that outputs a framework directly is probably not too complicated, but I don't have the exact details on hand atm. Another way to do it is to just set up the expected folder structure and Info.plist file manually and use install_name_tool to set the correct install name, but this is a bit more fragile.

Finally, I believe clients also need to register the framework in their Xcode project in order for things to work, so some manual intervention may be necessary in the end.

I will be looking further into this in the coming days, but I'm not sure if I'll be able to allocate enough time to submit a proper PR - I may need to go with the hacky solution of manually creating a framework around the library file for now.

[CoreyKaylor]

Any pointers hacky or otherwise would be appreciated even if you can't get in a PR.

[p-lindberg]

One issue that became apparent when digging further into this is that the library name constant MDB_DLL_NAME needs to be different on iOS: lmdb.framework/lmdb instead of lmdb. This is unfortunate since the library name must be a constant in order to be used in attributes. This likely means that we either need to compile a different version of the DLL for iOS targets, or set up the FFI bindings dynamically using dlopen and dlsym (would be a lot of work though). Thoughts?

[CoreyKaylor]

I'm a little confused, not that I think you're wrong but I'm starting to wonder why the nuget package even supports iOS target native binaries if this is how it has to work. Feels like that would be a wrench in every use-case.

[CoreyKaylor]

Is it possible to call NativeLibrary.Load with that path explicitly on iOS and still have the native methods mapped accordingly with the default name? I suspect it might be possible.

[CoreyKaylor]

I think something like this is probably more promising.

NativeLibrary.SetDllImportResolver(
            typeof(NativeMethods).Assembly,
            (string libraryName, Assembly assembly, DllImportSearchPath? searchPath) =>
            {
                if (libraryName != "lmdb") return IntPtr.Zero;  // Ignore other libs

#if NET6_0_OR_GREATER
                if (OperatingSystem.IsIOS())
#else
                if (RuntimeInformation.IsOSPlatform(OSPlatform.Create("IOS")))
#endif
                {
                    // Load iOS framework path
                    return NativeLibrary.Load("lmdb.framework/lmdb");  // Or "@rpath/lmdb.framework/lmdb" or "Frameworks/lmdb.framework/lmdb"
                }
                else
                {
                    // Default or other platforms
                    return NativeLibrary.Load("lmdb");  // Runtime will add extensions/paths as needed
                }
            });
    }

[p-lindberg]

I'm a little confused, not that I think you're wrong but I'm starting to wonder why the nuget package even supports iOS target native binaries if this is how it has to work. Feels like that would be a wrench in every use-case.

I think the wrench is courtesy of Apple in this instance, with their design choices around frameworks. I find it peculiar that we can't just dlopen("libname") when this is the standard on all other platforms, and instead have to pass in a path that goes inside the framework. The location of the binary inside the framework directory is fixed anyhow AFAIK, which would make the path redundant.

Is it possible to call NativeLibrary.Load with that path explicitly on iOS and still have the native methods mapped accordingly with the default name? I suspect it might be possible.

While I believe this might work, as well as the NativeLibrary.SetDllImportResolver approach you outlined below, the NativeLibrary API is not supported in .NET Standard 2.1 and older as far as I can tell, so an alternative solution is necessary in order to retain backwards compatibility. This would be necessary for my use case, as Unity only supports .NET Standard 2.1. Hopefully there is an equivalent older API that can be used to achieve the same result; otherwise I think it may be necessary to build a platform specific DLL of the managed code just for iOS.

Another thing: it may be more convenient to statically link the library on iOS, as it avoids the need to set up a framework and complicate the build pipeline. May yield better load times for the binary as well, but I don't know if it's significant. In that case, the binding would need to be against __Internal instead. One possibility to avoid divergent platform implementations could perhaps be to use static linking on all platforms, then we'd just have __Internal everywhere. But I'm not sure right now if other platforms have other constraints.

I will experiment some more.

[p-lindberg]

After some more digging I found that static linking and __Internal binding doesn't work on all platforms. It seems to be an iOS / AOT-compilation thing. It does however seem like it may be the most convenient and efficient solution on iOS.

I think a possible solution based on static linking may look something like this:

• Copy the .a file instead of .so file when deploying the compiled library to the runtimes folder for iOS targets
• Add iOS targets to the .csproj file (to build the platform-specific DLLs)
• Use compiler directives to set MDB_DLL_NAME to __Internal when compiling for iOS.
• Add the static library to the LightningDB.targets file so that MSBuild knows how to include it when building the app binary

This would be slightly less work than the dynamic route, as that requires the framework wrapping on top of everything else.

The last step I believe is necessary in order for things to work when building MAUI apps, as the MSBuild pipeline apparently handles the whole build process there (I've never used it myself though). For Unity games, the static library should be added automatically to the Xcode project produced by Unity, as long as one tags the file as an iOS library in the Unity editor. Finally, I think this approach should work with Xamarin apps as well, but not sure how relevant that is.

[p-lindberg]

I'm curious what the approach is for building the iOS armv7 targets? I can't find any information on it in the repository. This is the old 32-bit architecture of iPhone 5 and earlier models, which requires an older version of the iOS SDK (that comes bundled with older versions of Xcode).

Wondering whether it's actually worth supporting these legacy targets - I'm not even sure you could realistically submit an app update targeting such devices and have it successfully reviewed by Apple these days.

[CoreyKaylor]

It's the compile script in the lmdb directory. It shows how each target is compiled.

[p-lindberg]

It's the compile script in the lmdb directory. It shows how each target is compiled.

Let me rephrase; I'm confused as to how that build script works for the armv7 target - it does not succeed on my machine, by the looks of it because I don't have a legacy version of Xcode installed. Are you manually running this script on a machine with all dependencies installed?

[p-lindberg]

I've continued looking into this and have sort of arrived at the conclusion that there are conflicting constraints that can't be solved without very large (and possibly ad-hoc) changes.

To summarize, the constraints for my use case are:

• The solution must work on netstandard2.1 in order to be usable by Unity
• The native library must be loaded using a different method on iOS due to Apple requirements. Either,
  • Using static linking: requires mapping extern methods using __Internal as library name, or
  • Using dynamic linking: requires wrapping the lib in a framework and mapping external methods using lmdb.framework/lmdb as library name,
• (due to the above) The library name has to be controlled via #if compiler directives in order to work with netstandard2.1, as dynamic library name resolution is not available (introduced in .NET Core 3.0)

However, there is no support for OS-specific compilation of netstandard2.1 libraries as far as I can tell. OS-specific targets like net10.0-ios and platform preprocessor symbols like IOS were only introduced in .NET Core 5.0.

The remaining options seem to be:

• Fork the library and build a bespoke version for iOS / Unity, excluding support for other platforms
• Rewrite the FFI using dynamic binding instead of P/Invoke, i.e. by manually opening the library using dlopen and binding functions to delegates using dlsym and Marshal.GetDelegateForFunctionPointer.

The latter would be quite a significant change as it requires rewriting all the FFI code and dealing with various platform-specific edge cases. I could draft a PR for it, but it's unlikely that I would have time to actually verify the implementation.

Unless you see another way to proceed with this, I advise we close this issue.

[sebastienros]

I ran the issue by Opus/Codex, here is the result

iOS Support Fix — Issue #201 Analysis & Implementation Plan

Problem Summary

Lightning.NET's iOS native library loading is broken (#201). The P/Invoke declarations use MDB_DLL_NAME = "lmdb" but iOS requires either:

• Framework wrapping: load via lmdb.framework/lmdb
• Static linking: use __Internal as library name

Additionally, the native .dylib has its install name set to liblmdb.so (wrong), which prevents loading even in development builds.

Key Constraints

• NativeLibrary.SetDllImportResolver only available in .NET Core 3.0+ (not netstandard2.0)
• Unity requires netstandard2.1 (no NativeLibrary API, no IOS preprocessor symbol)
• Static linking (__Internal) only works on iOS/AOT, not all platforms
• No OS-specific TFMs for netstandard2.x
• armv7 (32-bit) iOS is legacy and can't be built with modern Xcode

---

Model Comparison: Opus 4.5 vs Codex (GPT-5.1)

Opus 4.5 Recommendation: Static Linking + iOS-Specific TFMs

Core approach: Add net8.0-ios, net9.0-ios, net10.0-ios TFMs alongside existing targets. Use #if IOS to set MDB_DLL_NAME = "__Internal" for iOS builds. Build static .a libraries instead of .dylib for iOS.

Key changes proposed:

1. Build script: Produce .a (static archives) for iOS targets, drop armv7
2. Lmdb.cs: #if IOS → MDB_DLL_NAME = "__Internal", else "lmdb"
3. New LmdbNativeLibrary.cs: NativeLibrary.SetDllImportResolver for NET7+ non-iOS as robustness fallback
4. New ModuleInitializer.cs: Auto-register the resolver
5. csproj: Add iOS TFMs, NativeReference items for static libs, SupportedOSPlatformVersion
6. New LightningDB.iOS.targets: Transitive static library linking for MAUI consumers
7. Existing .targets: Add condition to skip iOS platforms
8. Unity: Documented as requiring manual setup — copy .a to Plugins/iOS/ and use iOS-specific DLL

Strengths:

• Clean separation: iOS gets __Internal, other platforms unchanged
• Standard .NET multi-targeting approach
• Works with MAUI out of the box
• Simpler deployment than framework wrapping
• Comprehensive — covers build script, C#, project files, docs

Weaknesses:

• Doesn't solve netstandard2.0 for Unity iOS — Unity consumers need a custom-compiled DLL or separate package
• Increases number of TFMs (3 new iOS targets)
• Requires iOS SDK on build machine for CI

Codex (GPT-5.1) Recommendation: Hybrid Static + Dynamic with Runtime Fallback

Core approach: Ship BOTH .a (static) and .dylib (framework-wrapped) for iOS. Use NativeLibrary.SetDllImportResolver for NET7+ to remap to lmdb.framework/lmdb or __Internal. For netstandard2.x, introduce wrapper methods that catch DllNotFoundException and fall back to duplicate [DllImport("__Internal")] declarations.

Key changes proposed:

1. Build script: Build both .a and .dylib, run install_name_tool -id @rpath/lmdb.framework/lmdb on dylibs, create .xcframework structure, drop armv7
2. Lmdb.cs: Add static constructor with SetDllImportResolver for NET7+; for netstandard2.x, add generated wrapper methods with DllNotFoundException catch → fallback to [DllImport("__Internal")] duplicates
3. csproj: Add iOS TFMs (net8.0-ios, etc.), conditional DefineConstants, include new runtime assets
4. targets: Detect $(TargetPlatformIdentifier) for ios/maccatalyst, add <NativeReference> with Kind=Framework and ForceLoad=true

Strengths:

• More complete: covers both static and dynamic linking scenarios
• netstandard2.0 gets a runtime fallback (catch DllNotFoundException, redirect to __Internal)
• Framework wrapping gives proper iOS App Store compliance for dynamic linking
• XCFramework is the modern Apple standard

Weaknesses:

• Significantly more complex build pipeline (two outputs per iOS target + framework wrapping)
• The DllNotFoundException catch + fallback approach has performance overhead on first call
• Duplicate [DllImport("__Internal")] declarations essentially doubles the P/Invoke surface
• More fragile — many moving parts to get right
• XCFramework creation adds build complexity

---

Comparison Summary

Aspect	Opus 4.5 (Static Linking)	Codex (Hybrid)
Complexity	Medium	High
Build changes	.a only, drop armv7	.a + .dylib + xcframework
C# changes	#if IOS conditional	Resolver + fallback wrappers
netstandard2.0	Manual/docs (Unity setup)	Runtime fallback (try/catch)
MAUI support	✅ Via iOS TFMs	✅ Via iOS TFMs
Unity support	⚠️ Requires manual DLL/setup	⚠️ Runtime fallback (untested)
Maintainability	Good — clean separation	Lower — dual paths, duplicated P/Invoke
Risk	Low	Medium — more failure points
Files changed	~7 files	~7 files but more code

---

Recommended Approach

Use the Opus 4.5 approach (static linking + iOS TFMs) with one enhancement from Codex: the DllNotFoundException fallback for netstandard2.0.

Rationale

1. Static linking is simpler, more reliable, and better suited for iOS
2. Adding iOS-specific TFMs is the standard .NET approach
3. The Codex fallback idea for netstandard2.0 (catch DllNotFoundException → retry with __Internal) is valuable for Unity support without requiring a custom build
4. Framework wrapping adds complexity without proportional benefit since static linking solves the core problem

---

Implementation Todos

1. Drop armv7 iOS target from build script
2. Build static .a libraries for iOS targets (ios-arm64, iossimulator-arm64, iossimulator-x64)
3. Add iOS TFMs to csproj (net8.0-ios, net9.0-ios, net10.0-ios)
4. Add conditional MDB_DLL_NAME in Lmdb.cs (__Internal on iOS, lmdb elsewhere)
5. Add NativeLibrary.SetDllImportResolver for NET7+ non-iOS platforms
6. Add netstandard2.0 fallback wrapper that catches DllNotFoundException and retries with __Internal
7. Create LightningDB.iOS.targets for transitive static library linking
8. Update LightningDB.targets to exclude iOS platforms
9. Update README with Unity iOS setup instructions
10. Test on all target platforms

[p-lindberg]

Not sure what value this adds; the models regurgitated my conclusions in a longer format, hallucinated contradictory work items, and failed to understand the central problem.

[CoreyKaylor]

One option that might be easier is to maintain a separate branch for ios support with it's own nuget publish, etc. and you can remove the other concerns there. Thoughts?