Unity Android Build Works in Mono but Fails in IL2CPP due to Undefined References, Missing Library

Question

I'm attempting to update our ARToolkit5 based Unity Android app that has been in the Google Play store for years. ARToolkit5 is no longer supported, but we still rely on its libraries, built about 4 years ago. My Unity version is 2020.1.11f1.

I need to upgrade the app to a Google App Bundle and add 64-bit support. So the first step, I understand, is to change from Mono to IL2CPP as the Scripting Backend. The 32-bit Android ARMv7 app builds in Mono and runs fine, but when I literally only make one change, which is flipping to IL2CPP as the Scripting Backend under Project Settings, the build fails. I haven't even tried adding the ARM64 option yet.

When using IL2CPP the build fails with a BuilderFailedException and hundreds of Undefined References...

Exception: /Applications/2020.1.11f1/Unity.app/Contents/il2cpp/build/deploy/net471/il2cpp.exe did not run properly!

Failed running "/Applications/2020.1.11f1/Unity.app/Contents/il2cpp/build/deploy/net471/il2cpp.exe" --convert-to-cpp --emit-null-checks --enable-array-bounds-check --dotnetprofile="unityaot" --compile-cpp --libil2cpp-static --platform="Android" --architecture="ARMv7" --configuration="Release" --outputpath="<redacted>/Temp/StagingArea/assets/bin/Data/Native/armeabi-v7a/libil2cpp.so" --cachedirectory="<redacted>/Assets/../Library/il2cpp_android_armeabi-v7a/il2cpp_cache" --additional-include-directories="/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/Tools/bdwgc/include" --additional-include-directories="/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/Tools/libil2cpp/include" --baselib-directory="/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/Variations/il2cpp/Release/StaticLibs/armeabi-v7a" --avoid-dynamic-library-copy --tool-chain-path="/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/NDK" --profiler-report --map-file-parser="/Applications/2020.1.11f1/Unity.app/Contents/Tools/MapFileParser/MapFileParser" --directory="<redacted>/Temp/StagingArea/assets/bin/Data/Managed" --generatedcppdir="<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput"  

stdout:
Running il2cpp.exe in workstation GC mode.
Building libil2cpp.so with AndroidToolChain
    Output directory: <redacted>/Temp/StagingArea/assets/bin/Data/Native/armeabi-v7a
    Cache directory: <redacted>/Library/il2cpp_android_armeabi-v7a/il2cpp_cache
ObjectFiles: 186 of which compiled: 0
Total compilation time: 157 milliseconds.
il2cpp.exe didn't catch exception: Unity.IL2CPP.Building.BuilderFailedException: /Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin/clang++ @"/var/folders/vc/9b7436817vzgvxlqrftcl1nr0000gn/T/tmp1b926095.tmp" -o "<redacted>/Library/il2cpp_android_armeabi-v7a/il2cpp_cache/linkresult_01F24D8C43A06CD45FA9C75071D0A3D6/libil2cpp.so" -shared -Wl,-soname,libil2cpp.so -Wl,--no-undefined -Wl,-z,noexecstack -Wl,--gc-sections -Wl,--build-id -stdlib=libc++ -static-libstdc++ -target armv7-linux-androideabi19 -Wl,--wrap,sigaction "/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/Variations/il2cpp/Release/StaticLibs/armeabi-v7a/baselib.a" -llog -rdynamic -fuse-ld=gold

<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28131: error: undefined reference to 'arwRegisterLogCallback'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28140: error: undefined reference to 'arwSetLogLevel'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28149: error: undefined reference to 'arwInitialiseAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28159: error: undefined reference to 'arwInitialiseARWithOptions'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28173: error: undefined reference to 'arwGetARToolKitVersion'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28190: error: undefined reference to 'arwGetError'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28200: error: undefined reference to 'arwShutdownAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28221: error: undefined reference to 'arwStartRunningB'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28235: error: undefined reference to 'arwIsRunning'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28245: error: undefined reference to 'arwStopRunning'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28262: error: undefined reference to 'arwGetProjectionMatrix'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28276: error: undefined reference to 'arwGetVideoParams'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28293: error: undefined reference to 'arwCapture'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28303: error: undefined reference to 'arwUpdateAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28313: error: undefined reference to 'arwUpdateTexture32'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28323: error: undefined reference to 'arwGetMarkerPatternCount'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28340: error: undefined reference to 'arwGetMarkerPatternConfig'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28357: error: undefined reference to 'arwGetMarkerPatternImage'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28367: error: undefined reference to 'arwGetMarkerOptionBool'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28377: error: undefined reference to 'arwSetMarkerOptionBool'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28386: error: undefined reference to 'arwGetMarkerOptionInt'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28396: error: undefined reference to 'arwSetMarkerOptionInt'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28405: error: undefined reference to 'arwGetMarkerOptionFloat'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28415: error: undefined reference to 'arwSetMarkerOptionFloat'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28424: error: undefined reference to 'arwSetVideoDebugMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28433: error: undefined reference to 'arwGetVideoDebugMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28443: error: undefined reference to 'arwSetVideoThreshold'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28452: error: undefined reference to 'arwGetVideoThreshold'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28462: error: undefined reference to 'arwSetVideoThresholdMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28471: error: undefined reference to 'arwGetVideoThresholdMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28481: error: undefined reference to 'arwSetLabelingMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28490: error: undefined reference to 'arwGetLabelingMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28500: error: undefined reference to 'arwSetBorderSize'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28509: error: undefined reference to 'arwGetBorderSize'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28519: error: undefined reference to 'arwSetPatternDetectionMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28528: error: undefined reference to 'arwGetPatternDetectionMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28538: error: undefined reference to 'arwSetMatrixCodeType'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28547: error: undefined reference to 'arwGetMatrixCodeType'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28557: error: undefined reference to 'arwSetImageProcMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28566: error: undefined reference to 'arwGetImageProcMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28576: error: undefined reference to 'arwSetNFTMultiMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28585: error: undefined reference to 'arwGetNFTMultiMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28599: error: undefined reference to 'arwAddMarker'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28613: error: undefined reference to 'arwRemoveMarker'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28623: error: undefined reference to 'arwRemoveAllMarkers'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28633: error: undefined reference to 'arwQueryMarkerVisibility'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28650: error: undefined reference to 'arwQueryMarkerTransformation'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28685: error: undefined reference to 'arwLoadOpticalParams'
clang++: error: linker command failed with exit code 1 (use -v to see invocation)


  at Unity.IL2CPP.Building.CppProgramBuilder.PostprocessObjectFiles (System.Collections.Generic.HashSet`1[T] objectFiles, Unity.IL2CPP.Building.ToolChains.CppToolChainContext toolChainContext) [0x00203] in <bb3d372ae2c942d1b47f060d5cd89a4d>:0 
  at Unity.IL2CPP.Building.CppProgramBuilder.Build (Unity.IL2CPP.Building.Statistics.IBuildStatistics& statistics) [0x0025c] in <bb3d372ae2c942d1b47f060d5cd89a4d>:0 
  at Unity.IL2CPP.Building.Statistics.BuildingTestRunnerHelper.BuildAndLogStatsForTestRunner (Unity.IL2CPP.Building.CppProgramBuilder builder, Unity.IL2CPP.Building.Statistics.IBuildStatistics& statistics) [0x00000] in <bb3d372ae2c942d1b47f060d5cd89a4d>:0 
  at il2cpp.Compilation.CompilationDriver.Run (Unity.IL2CPP.Common.RuntimePlatform platform, Unity.IL2CPP.Building.BuildingOptions buildingOptions) [0x001fd] in <3be9f628f5fa469389bd6a91a579ba8a>:0 
  at il2cpp.Program.DoRun (System.String[] args, Unity.IL2CPP.Common.RuntimePlatform platform, Unity.IL2CPP.Building.BuildingOptions buildingOptions) [0x0001f] in <3be9f628f5fa469389bd6a91a579ba8a>:0 
  at il2cpp.Program.Run (System.String[] args, System.Boolean setInvariantCulture) [0x00063] in <3be9f628f5fa469389bd6a91a579ba8a>:0 
  at il2cpp.Program.Main (System.String[] args) [0x00000] in <3be9f628f5fa469389bd6a91a579ba8a>:0 
stderr:

Unhandled Exception:
Unity.IL2CPP.Building.BuilderFailedException: /Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin/clang++ @"/var/folders/vc/9b7436817vzgvxlqrftcl1nr0000gn/T/tmp1b926095.tmp" -o "<redacted>/Library/il2cpp_android_armeabi-v7a/il2cpp_cache/linkresult_01F24D8C43A06CD45FA9C75071D0A3D6/libil2cpp.so" -shared -Wl,-soname,libil2cpp.so -Wl,--no-undefined -Wl,-z,noexecstack -Wl,--gc-sections -Wl,--build-id -stdlib=libc++ -static-libstdc++ -target armv7-linux-androideabi19 -Wl,--wrap,sigaction "/Applications/2020.1.11f1/PlaybackEngines/AndroidPlayer/Variations/il2cpp/Release/StaticLibs/armeabi-v7a/baselib.a" -llog -rdynamic -fuse-ld=gold

<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28131: error: undefined reference to 'arwRegisterLogCallback'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28140: error: undefined reference to 'arwSetLogLevel'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28149: error: undefined reference to 'arwInitialiseAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28159: error: undefined reference to 'arwInitialiseARWithOptions'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28173: error: undefined reference to 'arwGetARToolKitVersion'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28190: error: undefined reference to 'arwGetError'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28200: error: undefined reference to 'arwShutdownAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28221: error: undefined reference to 'arwStartRunningB'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28235: error: undefined reference to 'arwIsRunning'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28245: error: undefined reference to 'arwStopRunning'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28262: error: undefined reference to 'arwGetProjectionMatrix'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28276: error: undefined reference to 'arwGetVideoParams'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28293: error: undefined reference to 'arwCapture'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28303: error: undefined reference to 'arwUpdateAR'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28313: error: undefined reference to 'arwUpdateTexture32'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28323: error: undefined reference to 'arwGetMarkerPatternCount'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28340: error: undefined reference to 'arwGetMarkerPatternConfig'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28357: error: undefined reference to 'arwGetMarkerPatternImage'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28367: error: undefined reference to 'arwGetMarkerOptionBool'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28377: error: undefined reference to 'arwSetMarkerOptionBool'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28386: error: undefined reference to 'arwGetMarkerOptionInt'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28396: error: undefined reference to 'arwSetMarkerOptionInt'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28405: error: undefined reference to 'arwGetMarkerOptionFloat'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28415: error: undefined reference to 'arwSetMarkerOptionFloat'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28424: error: undefined reference to 'arwSetVideoDebugMode'
<redacted>/Temp/StagingArea/Il2Cpp/il2cppOutput/Assembly-CSharp.cpp:28433: error: undefined referen<message truncated>

What I think this says is that the linker can't find definitions for the functions listed, all of which are from one ARToolkit library: libARWrapper.so

This library exists in the Unity project at: Assets/Plugins/Android/lib/armeabi-v7a/libARWrapper.so.

A quick check in the Unity Inspector shows that the library Import Settings seem to be correct.

This seems to indicate that this library will be included in Android ARMv7 builds, which this is. And I know the library works and runs on an ARMv7 device, and builds using Mono, so I think it is just somehow left out of the IL2CPP build.

So in conclusion, Mono includes the libARWrapper.so library in its build, but when I flip over to IL2CPP for the exact same project, the library is not included and thus fails to link. Does anyone know why this would be? Thanks!

Answer 1

The code in the plugin tries to P/Invoke into these APIs by declaring that they're in the same binary as your C# code:

    [DllImport("__Internal")]
    public static extern void arwRegisterLogCallback(PluginFunctions.LogCallback callback);

    [DllImport("__Internal")]
    public static extern void arwSetLogLevel(int logLevel);
    
    [DllImport("__Internal")]
    [return: MarshalAsAttribute(UnmanagedType.I1)]
    public static extern bool arwInitialiseAR();

"__Internal" is a special DLL name which tells IL2CPP to emit calls into these APIs directly, and trust that the linker will be able to resolve them. However, the APIs actually exist in libARWrapper.so (rather than in loose .cpp files in the Unity project) and so the linker cannot locate them. Changing all instances of [DllImport("__Internal")] to [DllImport("libARWrapper.so")] will fix your issue.

Answer 2

Sunius' answer works for Android, but it broke my WebGL build, throwing the runtime error "to use dlopen, you need to use Emscripten's linking support".

I fixed this with a conditional compile. For example, from the original poster gravy:

#if UNITY_WEBGL
    [DllImport("__Internal")]
    public static extern void arwSetLogLevel(int logLevel);
#else
    [DllImport("scrBrowserScripting.jslib")]
    public static extern void arwSetLogLevel(int logLevel);
#endif

Hope this saves some people some time :-)