Linux IL2CPP Cross Compiler Packages Now Available in Preview

Unity Engine
, ,
1

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: com.unity.toolchain.win-x86_64-linux-x86_64@0.1.14-preview

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.

Requirements

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.

Feedback

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!

11 Likes
2

Works great! Thank you for your hard work on this.

3

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

Have you reported this bug? Do you have a minimal repro project?

5

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

i.e

  • Windows: com.unity.toolchain.win-x86_64-linux-x86_64@0.1.16-preview

I changed backend to IL2CPP, but I get spammed with thre following errors in the editor…

Failed to initialize sysroot com.unity.toolchain.win-x86_64-linux-x86_64
0x00007FF6ACC0840C (Unity) StackWalker::GetCurrentCallstack
0x00007FF6ACC0C3C1 (Unity) StackWalker::ShowCallstack
0x00007FF6AB2E87A5 (Unity) GetStacktrace
0x00007FF6AD88826E (Unity) DebugStringToFile
0x00007FF6ACC677A5 (Unity) DebugLogHandler_CUSTOM_Internal_Log
0x000001CD6D91D1EB (Mono JIT Code) (wrapper managed-to-native) UnityEngine.DebugLogHandler:Internal_Log (UnityEngine.LogType,UnityEngine.LogOption,string,UnityEngine.Object)
0x000001CD6D91CDFB (Mono JIT Code) UnityEngine.DebugLogHandler:LogFormat (UnityEngine.LogType,UnityEngine.Object,string,object[])
0x000001CD6D91C31E (Mono JIT Code) UnityEngine.Logger:Log (UnityEngine.LogType,object)
0x000001CD6D91B8ED (Mono JIT Code) UnityEngine.Debug:Log (object)
0x000001CDFC0815DB (Mono JIT Code) UnityEditorInternal.SysrootManager:FindSysroot (string,string)
0x000001CDFC080F0B (Mono JIT Code) UnityEditorInternal.SysrootManager:FindSysroot (UnityEditor.BuildTarget)
0x000001CDFC080BE3 (Mono JIT Code) [LinuxStandaloneBuildWindowExtension.cs:25] UnityEditor.LinuxStandalone.LinuxStandaloneBuildWindowExtension:GetCannotBuildIl2CppPlayerInCurrentSetupError ()
0x000001CDFC091B09 (Mono JIT Code) DesktopStandaloneBuildWindowExtension:EnabledBuildButton ()
0x000001CDFC075915 (Mono JIT Code) UnityEditor.BuildPlayerWindow:ShowBuildTargetSettings ()
0x000001CDFC065963 (Mono JIT Code) UnityEditor.BuildPlayerWindow:OnGUI ()
0x000001CD6D8DBAF0 (Mono JIT Code) (wrapper runtime-invoke) object:runtime_invoke_void__this__ (object,intptr,intptr,intptr)
0x00007FF9EF7DD690 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
0x00007FF9EF762912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
0x00007FF9EF76BB42 (mono-2.0-bdwgc) [object.c:3073] mono_runtime_invoke_checked
0x00007FF9EF76C2D9 (mono-2.0-bdwgc) [object.c:5264] mono_runtime_try_invoke_array
0x00007FF9EF76BAD6 (mono-2.0-bdwgc) [object.c:5142] mono_runtime_invoke_array_checked
0x00007FF9EF710384 (mono-2.0-bdwgc) [icall.c:3358] ves_icall_InternalInvoke
0x000001CD6D9CA606 (Mono JIT Code) (wrapper managed-to-native) System.Reflection.MonoMethod:InternalInvoke (System.Reflection.MonoMethod,object,object[],System.Exception&)
0x000001CD6D9C9D4B (Mono JIT Code) System.Reflection.MonoMethod:Invoke (object,System.Reflection.BindingFlags,System.Reflection.Binder,object[],System.Globalization.CultureInfo)
0x000001CD6DB5BB3F (Mono JIT Code) System.Reflection.MethodBase:Invoke (object,object[])
0x000001CD3916BADB (Mono JIT Code) UnityEditor.HostView:Invoke (string,object)
0x000001CD3916B94B (Mono JIT Code) UnityEditor.HostView:Invoke (string)
0x000001CDFC0641CB (Mono JIT Code) UnityEditor.HostView:OldOnGUI ()
0x000001CCE019169A (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:smile:oOnGUI (UnityEngine.Event,UnityEngine.Matrix4x4,UnityEngine.Rect,bool,UnityEngine.Rect,System.Action,bool)
0x000001CCE017EB43 (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:HandleIMGUIEvent (UnityEngine.Event,UnityEngine.Matrix4x4,UnityEngine.Rect,System.Action,bool)
0x000001CCE018D8A3 (Mono JIT Code) UnityEngine.UIElements.IMGUIContainer:smile:oIMGUIRepaint ()
0x000001CCE0189136 (Mono JIT Code) UnityEngine.UIElements.UIR.RenderChainCommand:ExecuteNonDrawMesh (UnityEngine.UIElements.UIR.DrawParams,bool,single,System.Exception&)
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&)
0x000001CCE017A24B (Mono JIT Code) UnityEngine.UIElements.UIR.UIRenderDevice:smile:rawChain (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&)
0x000001CCE01537EB (Mono JIT Code) UnityEngine.UIElements.UIR.RenderChain:Render (UnityEngine.Rect,UnityEngine.Matrix4x4,UnityEngine.UIElements.PanelClearFlags)
0x000001CCE014E1FB (Mono JIT Code) UnityEngine.UIElements.UIRRepaintUpdater:smile:rawChain (UnityEngine.Rect,UnityEngine.Matrix4x4)
0x000001CCE014D1DE (Mono JIT Code) UnityEngine.UIElements.UIRRepaintUpdater:Update ()
0x000001CD40B63F1A (Mono JIT Code) UnityEngine.UIElements.VisualTreeUpdater:UpdateVisualTreePhase (UnityEngine.UIElements.VisualTreeUpdatePhase)
0x000001CD40B63CB3 (Mono JIT Code) UnityEngine.UIElements.Panel:UpdateForRepaint ()
0x000001CD40B631DB (Mono JIT Code) UnityEngine.UIElements.Panel:Repaint (UnityEngine.Event)
0x000001CD40B620F1 (Mono JIT Code) UnityEngine.UIElements.UIElementsUtility:smile:oDispatch (UnityEngine.UIElements.BaseVisualElementPanel)
0x000001CD40B619EB (Mono JIT Code) UnityEngine.UIElements.UIElementsUtility:ProcessEvent (int,intptr)
0x000001CD40B61253 (Mono JIT Code) UnityEngine.GUIUtility:ProcessEvent (int,intptr)
0x000001CD40B614D3 (Mono JIT Code) (wrapper runtime-invoke) <Module>:runtime_invoke_bool_int_intptr (object,intptr,intptr,intptr)
0x00007FF9EF7DD690 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
0x00007FF9EF762912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
0x00007FF9EF76B96F (mono-2.0-bdwgc) [object.c:2968] mono_runtime_invoke
0x00007FF6ACB7AB2E (Unity) scripting_method_invoke
0x00007FF6ACB7486D (Unity) ScriptingInvocation::Invoke
0x00007FF6ACB6E87A (Unity) ScriptingInvocation::Invoke<bool>
0x00007FF6A9EAE0B5 (Unity) Scripting::UnityEngine::GUIUtilityProxy::ProcessEvent
0x00007FF6AA809674 (Unity) GUIView::ProcessRetainedMode
0x00007FF6AB30F438 (Unity) GUIView::OnInputEvent
0x00007FF6AA80956C (Unity) GUIView::ProcessInputEvent
0x00007FF6AB30560E (Unity) GUIView::smile:oPaint
0x00007FF6AB311E8D (Unity) GUIView::RepaintAll
0x00007FF6AA99C7F7 (Unity) Application::TickTimer
0x00007FF6AB30E1C0 (Unity) MainMessageLoop
0x00007FF6AB318398 (Unity) WinMain
0x00007FF6AE326542 (Unity) __scrt_common_main_seh
0x00007FFA6A367C24 (KERNEL32) BaseThreadInitThunk
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 :frowning:

6

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.

2 Likes
7

We know what the issue here is for this, and plan to resolve it in a package/unity update no ETA but hopefully soon.

1 Like
8

Thanks for the speedy response Andrew, much appreciated!

9

@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
See Screenshot by Lightshot

Found sysroot: com.unity.sysroot, hp=, ha=, tp=, ta=
0x00007FF75ADFD2CC (Unity) StackWalker::GetCurrentCallstack
0x00007FF75AE01281 (Unity) StackWalker::ShowCallstack
0x00007FF7594C3F55 (Unity) GetStacktrace
0x00007FF75BA859FE (Unity) DebugStringToFile
0x00007FF75AE5C695 (Unity) DebugLogHandler_CUSTOM_Internal_Log
0x0000014824C1750B (Mono JIT Code) (wrapper managed-to-native) UnityEngine.DebugLogHandler:Internal_Log (UnityEngine.LogType,UnityEngine.LogOption,string,UnityEngine.Object)
0x0000014824C1711B (Mono JIT Code) UnityEngine.DebugLogHandler:LogFormat (UnityEngine.LogType,UnityEngine.Object,string,object[])
0x0000014824C1663E (Mono JIT Code) UnityEngine.Logger:Log (UnityEngine.LogType,object)
0x0000014824C15C0D (Mono JIT Code) UnityEngine.Debug:Log (object)
0x0000014824BFBDCB (Mono JIT Code) UnityEditorInternal.SysrootManager:RegisterSysroots ()
0x0000014824BFB1E3 (Mono JIT Code) UnityEditorInternal.SysrootManager:Initialize ()
0x0000014824BFB0C3 (Mono JIT Code) [ExtensionModule.cs:20] UnityEditor.LinuxStandalone.TargetExtension:OnLoad ()
0x0000014824BC36BE (Mono JIT Code) UnityEditor.Modules.ModuleManager:InitializePlatformSupportModules ()
0x0000014824C0D345 (Mono JIT Code) (wrapper runtime-invoke) object:runtime_invoke_void (object,intptr,intptr,intptr)
0x00007FF9F0CAD6B0 (mono-2.0-bdwgc) [mini-runtime.c:2809] mono_jit_runtime_invoke
0x00007FF9F0C32912 (mono-2.0-bdwgc) [object.c:2921] do_runtime_invoke
0x00007FF9F0C3B96F (mono-2.0-bdwgc) [object.c:2968] mono_runtime_invoke
0x00007FF75AD6F93E (Unity) scripting_method_invoke
0x00007FF75AD6966D (Unity) ScriptingInvocation::Invoke
0x00007FF75AD63655 (Unity) ScriptingInvocation::Invoke<void>
0x00007FF758072E4E (Unity) Scripting::UnityEditor::Modules::ModuleManagerProxy::InitializePlatformSupportModules
0x00007FF75AD3C662 (Unity) MonoManager::SetupLoadedEditorAssemblies
0x00007FF75AD34573 (Unity) MonoManager::EndReloadAssembly
0x00007FF75AD3AD07 (Unity) MonoManager::ReloadAssembly
0x00007FF75911B707 (Unity) LoadDomainAndUserAssemblies
0x00007FF75911E4C2 (Unity) RegisterScriptsAndTryLoadingExistingUserAssemblies
0x00007FF75963A209 (Unity) ImportAndPostprocessOutOfDateAssets
0x00007FF759641FBB (Unity) RefreshInternalV2
0x00007FF759644C36 (Unity) StopAssetImportingV2
0x00007FF75963C086 (Unity) InitialScriptRefreshV2
0x00007FF758B645D5 (Unity) Application::InitializeProject
0x00007FF7594F3844 (Unity) WinMain
0x00007FF75C54CFC2 (Unity) __scrt_common_main_seh
0x00007FFA6A367C24 (KERNEL32) BaseThreadInitThunk
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 com.unity.toolchain.win-x86_64-linux-x86_64’ error messages appear.

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

6518641–735241–Editor.log.txt (937 KB)

10

We have updated the packages:

com.unity.sysroot                                           "version": "0.1.16-preview",
com.unity.toolchain.macos-x86_64-linux-x86_64               "version": "0.1.17-preview",
com.unity.toolchain.win-x86_64-linux-x86_64                 "version": "0.1.16-preview",
com.unity.toolchain.linux-x86_64                            "version": "0.1.15-preview",
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

Thank for more info shall take a look.

12

@Meltdown can you try running the editor as administrator? or can you set
UNITY_SYSROOT_CACHE 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

1 Like
13

Thanks, that worked.

Here is a screenshot from the WinVer dialog.
https://prnt.sc/vic477

14

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”,
    “com.unity.toolchain.win-x86_64-linux-x86_64”: “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

DO you have your editor logs ?

16
  • 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: com.unity.toolchain.win-x86_64-linux-x86_64, 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: com.unity.toolchain.win-x86_64-linux-x86_64

17

-2020.1.14f1
-0.1.16-preview
-Unity Hub 2.4.2
-Linux IL2CPP module installed
-Windows 10

Stack 1:
Failed to initialize sysroot com.unity.toolchain.win-x86_64-linux-x86_64
UnityEngine.Debug:Log(Object)
UnityEditorInternal.SysrootManager:FindSysroot(String, String)
UnityEditorInternal.SysrootManager:FindSysroot(BuildTarget)
UnityEditor.LinuxStandalone.LinuxStandaloneBuildWindowExtension:GetCannotBuildIl2CppPlayerInCurrentSetupError()
DesktopStandaloneBuildWindowExtension:ShowIl2CppErrorIfNeeded()
DesktopStandaloneBuildWindowExtension:ShowPlatformBuildOptions()
UnityEngine.GUIUtility:ProcessEvent(Int32, IntPtr, Boolean&)

Stack 2:
Failed to initialize sysroot com.unity.toolchain.win-x86_64-linux-x86_64
UnityEngine.Debug:Log(Object)
UnityEditorInternal.SysrootManager:FindSysroot(String, String)
UnityEditorInternal.SysrootManager:FindSysroot(BuildTarget)
UnityEditor.LinuxStandalone.LinuxStandaloneBuildWindowExtension:GetCannotBuildIl2CppPlayerInCurrentSetupError()
DesktopStandaloneBuildWindowExtension:EnabledBuildButton()
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

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

19

I’m trying to build a linux il2cpp binary from windows, Using Unity 2019.4.15f1 and
com.unity.toolchain.win-x86_64-linux-x86_64 “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 :slight_smile:

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

We have updated the packages:

com.unity.sysroot/package.json: 0.1.17-preview
com.unity.sysroot.linux-x86_64/package.json: 0.1.13-preview
com.unity.toolchain.linux-x86_64/package.json: 0.1.16-preview
com.unity.toolchain.macos-x86_64-linux-x86_64/package.json: 0.1.18-preview
com.unity.toolchain.win-x86_64-linux-x86_64/package.json: 0.1.17-preview

This update removes the requirment for symlink privilege on windows.

1 Like