Search Unity

  1. Click here to see what's on sale for the "Best of Super Sale" on the Asset Store
    Dismiss Notice
  2. Good news ✨ We have more Unite Now videos available for you to watch on-demand! Come check them out and ask our experts any questions!
    Dismiss Notice

Unity Linux IL2CPP Cross Compiler Packages Now Available in Preview

Discussion in 'macOS' started by andrews_unity, Sep 24, 2020.

  1. andrews_unity


    Unity Technologies

    Dec 11, 2015
    Starting in 2019.4, we introduced IL2CPP support for Linux, which allows developers that build on Linux to gain the performance and scalability benefits of IL2CPP compilation rather than having to rely on Mono. However, this support relied upon building from the Linux editor and it relied upon a developer configuring their own C++ toolchain. That means that it was not suitable for developers that were building for Linux but were not using the Linux editor. It also was challenging for developers to set up a compilation toolchain that was compatible with Unity’s.

    Because Linux is a diverse ecosystem with a wide variety of environments and distributions, we wanted to provide developers with a way to guarantee a consistent runtime no matter which supported Unity platform they chose to build from. To help address this, we've created a new package that contains our own verified sysroot. While you can still choose to leverage your own system's sysroot if you so choose, building against ours will ensure a consistent, compatible end result on all supported Linux distributions.

    In addition to our sysroot package we have supplied a toolchain package that provides a standard toolchain (compiler, linker and related tools) to build the player. This split of the sysroot and toolchain allows us to support cross-compilation of Linux players. With the appropriate toolchain package for the host platform (Editor) and target platform (Player), we can support building of Linux targets (players) on macOS and Windows hosts.

    Our goal with these features is to provide you with a versatile set of plug-and-play solutions that you can pick and choose from to fit your own unique needs, whether that’s using your local machine to build for Linux or whether you’re building target binaries for your Linux servers. We want developers to be able to build and deploy as quickly as possible without having to worry about unnecessary complexities getting it to run. This will ultimately reduce their iteration times and let them get back to what's really important: shipping amazing products.

    Package Installation

    To make using these packages as simple to use as possible, we have created a series of platform-specific toolchain packages that include the necessary build tools and load the sysroot package as a dependency. You simply add the appropriate toolchain package based on the host platform/architecture and target platform/architecture:
    • Linux: com.unity.toolchain.linux-x86_64@0.1.13-preview
    • macOS: com.unity.toolchain.macos-x86_64-linux-x86_64@0.1.15-preview
    • Windows:
    Note that the format of the name is host platform, host architecture, target platform, and target architecture. You can shorten the name if the host and the target are the same.

    For the moment, these packages are not discoverable through the Package Manager UI search function. You can add them by clicking on the “+” in the Package Manager toolbar, selecting “Add package from git URL”, and then typing the name of the package as listed in the table above.

    Once the package is installed, you are set to build on Linux.

    To build on macOS or Windows, you will need the Linux-IL2CPP module to be installed. This module can be installed from the Hub. (You’ll need Hub 2.4.0 or newer.)

    Set the ScriptingBackend in PlayerSettings / Other Settings / Configuration to IL2CPP, select the Linux target, and build.

    The sysroot package and toolchain require approximately 164 MB on Linux and about 1.4GB on macOS and Windows. The bulk of the data is stored in the local application data directory as shown below:
    • Linux: ~/.local/share/unity3d/cache/sysroots
    • macOS: ~/Library/Unity/cache/sysroots
    • Windows: %LocalApplicationData%\unity3d\cache\sysroots
    If necessary, the uncompressed sysroot and toolchain can be relocated by setting the environment variable UNITY_SYSROOT_CACHE to another directory.


    In summary, these are the requirements to build Linux targets:
    • Recent version of Editor: 2019.4.11f1, 2020.1.6f1, 2020.2.0b3
    • Hub 2.4
    • On macOS and Windows, Linux-IL2CPP module installed
    • Correct toolchain for host platform installed
    • ScriptingBackend set to IL2CPP
    Known issues

    On macOS there was an issue with early versions of the Linux-IL2CPP module being installed in the wrong directory, which results in the Linux build target not being found. To fix this, you will need to uninstall the editor and reinstall with the Linux-IL2CPP module. This will pick up the fixed version of the module.

    There is an issue with IL2CPP not handling paths with spaces in them. This will be fixed in a future release.


    We’re looking for feedback on these new packages, so if you have any questions or want to share notes on your experience using them, please feel free to leave us a comment!
    Last edited: Sep 30, 2020
    Meltdown, CommunityUS, PixelJ and 6 others like this.
  2. CommunityUS


    Sep 2, 2011
    Works great! Thank you for your hard work on this.
  3. Kichang-Kim


    Oct 19, 2010
    I found that macos-x86_64-linux-x86_64 package does not work until opening the project manually (non-batch mode) and re-importing sysroot package. If your project has never been opened as non-batch mode, sysroot package does not correctly initialized and failed to build with clang compilation error (missing feature.h header).

    This is critical issue when using Unity with CI tools, like jenkins.
  4. PixelJ


    Unity Technologies

    Nov 1, 2018
    Have you reported this bug? Do you have a minimal repro project?
  5. Meltdown


    Oct 13, 2010
    @andrews_unity I am using Unity 2019.4.9f on Windows.
    I have installed the latest 0.1.16 package from Package Manager.

    • Windows:
    I changed backend to IL2CPP, but I get spammed with thre following errors in the editor..

    Code (CSharp):
    1. Failed to initialize sysroot
    2. 0x00007FF6ACC0840C (Unity) StackWalker::GetCurrentCallstack
    3. 0x00007FF6ACC0C3C1 (Unity) StackWalker::ShowCallstack
    4. 0x00007FF6AB2E87A5 (Unity) GetStacktrace
    5. 0x00007FF6AD88826E (Unity) DebugStringToFile
    6. 0x00007FF6ACC677A5 (Unity) DebugLogHandler_CUSTOM_Internal_Log
    7. 0x000001CD6D91D1EB (Mono JIT Code) (wrapper managed-to-native) UnityEngine.DebugLogHandler:Internal_Log (UnityEngine.LogType,UnityEngine.LogOption,string,UnityEngine.Object)
    8. 0x000001CD6D91CDFB (Mono JIT Code) UnityEngine.DebugLogHandler:LogFormat (UnityEngine.LogType,UnityEngine.Object,string,object[])
    9. 0x000001CD6D91C31E (Mono JIT Code) UnityEngine.Logger:Log (UnityEngine.LogType,object)
    10. 0x000001CD6D91B8ED (Mono JIT Code) UnityEngine.Debug:Log (object)
    11. 0x000001CDFC0815DB (Mono JIT Code) UnityEditorInternal.SysrootManager:FindSysroot (string,string)
    12. 0x000001CDFC080F0B (Mono JIT Code) UnityEditorInternal.SysrootManager:FindSysroot (UnityEditor.BuildTarget)
    13. 0x000001CDFC080BE3 (Mono JIT Code) [LinuxStandaloneBuildWindowExtension.cs:25] UnityEditor.LinuxStandalone.LinuxStandaloneBuildWindowExtension:GetCannotBuildIl2CppPlayerInCurrentSetupError ()
    14. 0x000001CDFC091B09 (Mono JIT Code) DesktopStandaloneBuildWindowExtension:EnabledBuildButton ()
    15. 0x000001CDFC075915 (Mono JIT Code) UnityEditor.BuildPlayerWindow:ShowBuildTargetSettings ()
    16. 0x000001CDFC065963 (Mono JIT Code) UnityEditor.BuildPlayerWindow:OnGUI ()
    17. 0x000001CD6D8DBAF0 (Mono JIT Code) (wrapper runtime-invoke) object:runtime_invoke_void__this__ (object,intptr,intptr,intptr)
    18. 0x00007FF9EF7DD690 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
    19. 0x00007FF9EF762912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
    20. 0x00007FF9EF76BB42 (mono-2.0-bdwgc) [object.c:3073] mono_runtime_invoke_checked
    21. 0x00007FF9EF76C2D9 (mono-2.0-bdwgc) [object.c:5264] mono_runtime_try_invoke_array
    22. 0x00007FF9EF76BAD6 (mono-2.0-bdwgc) [object.c:5142] mono_runtime_invoke_array_checked
    23. 0x00007FF9EF710384 (mono-2.0-bdwgc) [icall.c:3358] ves_icall_InternalInvoke
    24. 0x000001CD6D9CA606 (Mono JIT Code) (wrapper managed-to-native) System.Reflection.MonoMethod:InternalInvoke (System.Reflection.MonoMethod,object,object[],System.Exception&)
    25. 0x000001CD6D9C9D4B (Mono JIT Code) System.Reflection.MonoMethod:Invoke (object,System.Reflection.BindingFlags,System.Reflection.Binder,object[],System.Globalization.CultureInfo)
    26. 0x000001CD6DB5BB3F (Mono JIT Code) System.Reflection.MethodBase:Invoke (object,object[])
    27. 0x000001CD3916BADB (Mono JIT Code) UnityEditor.HostView:Invoke (string,object)
    28. 0x000001CD3916B94B (Mono JIT Code) UnityEditor.HostView:Invoke (string)
    29. 0x000001CDFC0641CB (Mono JIT Code) UnityEditor.HostView:OldOnGUI ()
    30. 0x000001CCE019169A (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:DoOnGUI (UnityEngine.Event,UnityEngine.Matrix4x4,UnityEngine.Rect,bool,UnityEngine.Rect,System.Action,bool)
    31. 0x000001CCE017EB43 (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:HandleIMGUIEvent (UnityEngine.Event,UnityEngine.Matrix4x4,UnityEngine.Rect,System.Action,bool)
    32. 0x000001CCE018D8A3 (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:DoIMGUIRepaint ()
    33. 0x000001CCE0189136 (Mono JIT Code) UnityEngine.UIElements.UIR.RenderChainCommand:ExecuteNonDrawMesh (UnityEngine.UIElements.UIR.DrawParams,bool,single,System.Exception&)
    34. 0x000001CCE01827CB (Mono JIT Code) UnityEngine.UIElements.UIR.UIRenderDevice:EvaluateChain (UnityEngine.UIElements.UIR.RenderChainCommand,UnityEngine.Rect,UnityEngine.Matrix4x4,UnityEngine.UIElements.PanelClearFlags,UnityEngine.Texture,UnityEngine.Texture,UnityEngine.Texture,single,Unity.Collections.NativeArray`1<UnityEngine.UIElements.UIR.Transform3x4>,Unity.Collections.NativeArray`1<UnityEngine.Vector4>,System.Exception&)
    35. 0x000001CCE017A24B (Mono JIT Code) UnityEngine.UIElements.UIR.UIRenderDevice:DrawChain (UnityEngine.UIElements.UIR.RenderChainCommand,UnityEngine.Rect,UnityEngine.Matrix4x4,UnityEngine.UIElements.PanelClearFlags,UnityEngine.Texture,UnityEngine.Texture,UnityEngine.Texture,single,Unity.Collections.NativeArray`1<UnityEngine.UIElements.UIR.Transform3x4>,Unity.Collections.NativeArray`1<UnityEngine.Vector4>,System.Exception&)
    36. 0x000001CCE01537EB (Mono JIT Code) UnityEngine.UIElements.UIR.RenderChain:Render (UnityEngine.Rect,UnityEngine.Matrix4x4,UnityEngine.UIElements.PanelClearFlags)
    37. 0x000001CCE014E1FB (Mono JIT Code) UnityEngine.UIElements.UIRRepaintUpdater:DrawChain (UnityEngine.Rect,UnityEngine.Matrix4x4)
    38. 0x000001CCE014D1DE (Mono JIT Code) UnityEngine.UIElements.UIRRepaintUpdater:Update ()
    39. 0x000001CD40B63F1A (Mono JIT Code) UnityEngine.UIElements.VisualTreeUpdater:UpdateVisualTreePhase (UnityEngine.UIElements.VisualTreeUpdatePhase)
    40. 0x000001CD40B63CB3 (Mono JIT Code) UnityEngine.UIElements.Panel:UpdateForRepaint ()
    41. 0x000001CD40B631DB (Mono JIT Code) UnityEngine.UIElements.Panel:Repaint (UnityEngine.Event)
    42. 0x000001CD40B620F1 (Mono JIT Code) UnityEngine.UIElements.UIElementsUtility:DoDispatch (UnityEngine.UIElements.BaseVisualElementPanel)
    43. 0x000001CD40B619EB (Mono JIT Code) UnityEngine.UIElements.UIElementsUtility:ProcessEvent (int,intptr)
    44. 0x000001CD40B61253 (Mono JIT Code) UnityEngine.GUIUtility:ProcessEvent (int,intptr)
    45. 0x000001CD40B614D3 (Mono JIT Code) (wrapper runtime-invoke) <Module>:runtime_invoke_bool_int_intptr (object,intptr,intptr,intptr)
    46. 0x00007FF9EF7DD690 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
    47. 0x00007FF9EF762912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
    48. 0x00007FF9EF76B96F (mono-2.0-bdwgc) [object.c:2968] mono_runtime_invoke
    49. 0x00007FF6ACB7AB2E (Unity) scripting_method_invoke
    50. 0x00007FF6ACB7486D (Unity) ScriptingInvocation::Invoke
    51. 0x00007FF6ACB6E87A (Unity) ScriptingInvocation::Invoke<bool>
    52. 0x00007FF6A9EAE0B5 (Unity) Scripting::UnityEngine::GUIUtilityProxy::ProcessEvent
    53. 0x00007FF6AA809674 (Unity) GUIView::ProcessRetainedMode
    54. 0x00007FF6AB30F438 (Unity) GUIView::OnInputEvent
    55. 0x00007FF6AA80956C (Unity) GUIView::ProcessInputEvent
    56. 0x00007FF6AB30560E (Unity) GUIView::DoPaint
    57. 0x00007FF6AB311E8D (Unity) GUIView::RepaintAll
    58. 0x00007FF6AA99C7F7 (Unity) Application::TickTimer
    59. 0x00007FF6AB30E1C0 (Unity) MainMessageLoop
    60. 0x00007FF6AB318398 (Unity) WinMain
    61. 0x00007FF6AE326542 (Unity) __scrt_common_main_seh
    62. 0x00007FFA6A367C24 (KERNEL32) BaseThreadInitThunk
    63. 0x00007FFA6AA8D4D1 (ntdll) RtlUserThreadStart
    This leaves the Build window with the 'Building IL2CPP requires a sysroot toolchain' error and the build buttons disabled.

    I am on Unity Hub 2.4.2 and cannot see any Linux Build Support for IL2CPP option? Only Mono?

    See this image

    EDIT : I had to uninstall Linux Mono, before I could see the Linux IL2CPP install option.
    It seems both cannot be installed side by side.

    But I still get the error message, after installing the Linux IL2CPP build support package :(
    Last edited: Nov 12, 2020
  6. andrews_unity


    Unity Technologies

    Dec 11, 2015

    We have seen this issue happen with a couple folks but have not been able to repro it locally or in our automated testing. Will take this info back and see if we can figure out what's going on.
    Meltdown likes this.
  7. andrews_unity


    Unity Technologies

    Dec 11, 2015
    We know what the issue here is for this, and plan to resolve it in a package/unity update no ETA but hopefully soon.
    Kichang-Kim likes this.
  8. Meltdown


    Oct 13, 2010
    Thanks for the speedy response Andrew, much appreciated!
  9. Meltdown


    Oct 13, 2010
    @andrews_unity Here is some more info to help you reproduce.

    I have cleared the editor logs. And opened the editor. I upgraded to 2019.4.14f1.

    When I first open the editor, all seems good. I get some positive messages telling me the sysroot toolchain is found

    Code (CSharp):
    1. Found sysroot: com.unity.sysroot, hp=, ha=, tp=, ta=
    2. 0x00007FF75ADFD2CC (Unity) StackWalker::GetCurrentCallstack
    3. 0x00007FF75AE01281 (Unity) StackWalker::ShowCallstack
    4. 0x00007FF7594C3F55 (Unity) GetStacktrace
    5. 0x00007FF75BA859FE (Unity) DebugStringToFile
    6. 0x00007FF75AE5C695 (Unity) DebugLogHandler_CUSTOM_Internal_Log
    7. 0x0000014824C1750B (Mono JIT Code) (wrapper managed-to-native) UnityEngine.DebugLogHandler:Internal_Log (UnityEngine.LogType,UnityEngine.LogOption,string,UnityEngine.Object)
    8. 0x0000014824C1711B (Mono JIT Code) UnityEngine.DebugLogHandler:LogFormat (UnityEngine.LogType,UnityEngine.Object,string,object[])
    9. 0x0000014824C1663E (Mono JIT Code) UnityEngine.Logger:Log (UnityEngine.LogType,object)
    10. 0x0000014824C15C0D (Mono JIT Code) UnityEngine.Debug:Log (object)
    11. 0x0000014824BFBDCB (Mono JIT Code) UnityEditorInternal.SysrootManager:RegisterSysroots ()
    12. 0x0000014824BFB1E3 (Mono JIT Code) UnityEditorInternal.SysrootManager:Initialize ()
    13. 0x0000014824BFB0C3 (Mono JIT Code) [ExtensionModule.cs:20] UnityEditor.LinuxStandalone.TargetExtension:OnLoad ()
    14. 0x0000014824BC36BE (Mono JIT Code) UnityEditor.Modules.ModuleManager:InitializePlatformSupportModules ()
    15. 0x0000014824C0D345 (Mono JIT Code) (wrapper runtime-invoke) object:runtime_invoke_void (object,intptr,intptr,intptr)
    16. 0x00007FF9F0CAD6B0 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
    17. 0x00007FF9F0C32912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
    18. 0x00007FF9F0C3B96F (mono-2.0-bdwgc) [object.c:2968] mono_runtime_invoke
    19. 0x00007FF75AD6F93E (Unity) scripting_method_invoke
    20. 0x00007FF75AD6966D (Unity) ScriptingInvocation::Invoke
    21. 0x00007FF75AD63655 (Unity) ScriptingInvocation::Invoke<void>
    22. 0x00007FF758072E4E (Unity) Scripting::UnityEditor::Modules::ModuleManagerProxy::InitializePlatformSupportModules
    23. 0x00007FF75AD3C662 (Unity) MonoManager::SetupLoadedEditorAssemblies
    24. 0x00007FF75AD34573 (Unity) MonoManager::EndReloadAssembly
    25. 0x00007FF75AD3AD07 (Unity) MonoManager::ReloadAssembly
    26. 0x00007FF75911B707 (Unity) LoadDomainAndUserAssemblies
    27. 0x00007FF75911E4C2 (Unity) RegisterScriptsAndTryLoadingExistingUserAssemblies
    28. 0x00007FF75963A209 (Unity) ImportAndPostprocessOutOfDateAssets
    29. 0x00007FF759641FBB (Unity) RefreshInternalV2
    30. 0x00007FF759644C36 (Unity) StopAssetImportingV2
    31. 0x00007FF75963C086 (Unity) InitialScriptRefreshV2
    32. 0x00007FF758B645D5 (Unity) Application::InitializeProject
    33. 0x00007FF7594F3844 (Unity) WinMain
    34. 0x00007FF75C54CFC2 (Unity) __scrt_common_main_seh
    35. 0x00007FFA6A367C24 (KERNEL32) BaseThreadInitThunk
    36. 0x00007FFA6AA8D4D1 (ntdll) RtlUserThreadStart
    But as soon as I open File -> Build Settings window, the build settings dialog freezes for a while (about 30 seconds), as a blank dialog. Once it stops freezing, then all the 'Failed to initialize sysroot' error messages appear.

    I have attached my Editor log that captures opening the editor, and then opening the Build Settings window.

    Attached Files:

  10. andrews_unity


    Unity Technologies

    Dec 11, 2015
    We have updated the packages:

    Code (Json):
    2. com.unity.sysroot                                           "version": "0.1.16-preview",
    3. com.unity.toolchain.macos-x86_64-linux-x86_64               "version": "0.1.17-preview",
    4.                 "version": "0.1.16-preview",
    5. com.unity.toolchain.linux-x86_64                            "version": "0.1.15-preview",
    6. com.unity.sysroot.linux-x86_64                              "version": "0.1.12-preview",

    These updates include some removal of some log spam, as well as resolving some issues with NiceIO conflicting with other packages who are also using it.
  11. andrews_unity


    Unity Technologies

    Dec 11, 2015

    Thank for more info shall take a look.
  12. andrews_unity


    Unity Technologies

    Dec 11, 2015
    @Meltdown can you try running the editor as administrator? or can you set
    as an env variable to a location that doesn't require admin privilege's

    I see these errors in your log

    ERROR: Can not create symbolic link : A required privilege is not held by the client.

    also can you post the results of winver
    Last edited: Nov 13, 2020
    Meltdown likes this.
  13. Meltdown


    Oct 13, 2010
    Thanks, that worked.

    Here is a screenshot from the WinVer dialog.
  14. icefallgames


    Dec 6, 2014
    On Windows, we have:
    - 2019.4.14f1
    - Unity Hub 2.4.2
    - Linux IL2CPP module installed
    - The following three packages installed:
    "com.unity.sysroot": "0.1.16-preview",
    "com.unity.sysroot.linux-x86_64": "0.1.12-preview",
    "": "0.1.16-preview",

    And yet we still get the message "Building Linux IL2CPP player requires a sysroot toolchain package to be installed".

    What's missing?

    (Building Mono Linux works fine)
  15. andrews_unity


    Unity Technologies

    Dec 11, 2015
    DO you have your editor logs ?
  16. OneManArmy3D


    Jun 2, 2011
    - 2019.4.15f1
    - 0.1.16-preview
    - Unity Hub 2.4.2
    - Linux IL2CPP module installed
    - Windows 10

    Found sysroot: com.unity.sysroot, hp=, ha=, tp=, ta=
    Found sysroot: com.unity.sysroot.linux-x86_64, hp=, ha=, tp=linux, ta=x86_64
    Found sysroot:, hp=windows, ha=x86_64, tp=linux, ta=x86_64

    And as soon as i am pressing Build, i am getting 100+
    Failed to initialize package:
  17. FungusSamurai


    Mar 3, 2016
    -Unity Hub 2.4.2
    -Linux IL2CPP module installed
    -Windows 10

    Stack 1:
    Failed to initialize sysroot
    UnityEditorInternal.SysrootManager:FindSysroot(String, String)
    UnityEngine.GUIUtility:processEvent(Int32, IntPtr, Boolean&)

    Stack 2:
    Failed to initialize sysroot
    UnityEditorInternal.SysrootManager:FindSysroot(String, String)
    UnityEngine.GUIUtility:processEvent(Int32, IntPtr, Boolean&)

    Also worth noting: I set up
    UNITY_SYSROOT_CACHE to go to: C:\dev\toolchain and I can see it added this folder: C:\dev\toolchain\linux-x86 but there's nothing in that file path.
  18. andrews_unity


    Unity Technologies

    Dec 11, 2015

    Can you run the editor as admin ? We are working on a new version of the package to solve this issue on windows.
  19. JesperBHansen


    Oct 9, 2020
    I'm trying to build a linux il2cpp binary from windows, Using Unity 2019.4.15f1 and "0.1.16-preview"

    It seems like some of the scripts fail to quote some arguments as it fail if the user directory contains spaces :)

    clang++: error: no such file or directory: '@C:\Users\Jesper'
    clang++: error: no such file or directory: 'Hansen\AppData\Local\Temp\il2cpp\clangargs_A32060A1B9770EB02CC8B1D29FF92DD7.txt'
    clang++: error: no input files
  20. davidbuckley_unity


    Unity Technologies

    May 4, 2018
    We have updated the packages:

    Code (json):
    1. com.unity.sysroot/package.json: 0.1.17-preview
    2. com.unity.sysroot.linux-x86_64/package.json: 0.1.13-preview
    3. com.unity.toolchain.linux-x86_64/package.json: 0.1.16-preview
    4. com.unity.toolchain.macos-x86_64-linux-x86_64/package.json: 0.1.18-preview
    5. 0.1.17-preview
    This update removes the requirment for symlink privilege on windows.
    OneManArmy3D likes this.