unity3d - 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/

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.