Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Introduction to IL2CPP

Understand IL2CPP's role in Unity script compilation and how it works.
Read time 4 minutesLast updated 9 days ago
IL2CPP (Intermediate Language To C++) is Unity's custom, ahead-of-time (AOT) scripting back end, which was originally developed for platforms that don't support Mono and just-in-time (JIT) compilation, such as iOS. IL2CPP converts IL (Intermediate Language) to C++, and compiles it into platform-specific native code, which is then packaged with your application in the standard format for the target platform, such as APK/AAB, iOS app bundle, or Windows executable and DLLs.
IL2CPP is supported on all platforms and can offer several benefits over the Mono scripting back end, including improved performance and shorter startup times. However, the need to include machine code in built applications generally increases both the build time and the size of the final built application.
IL2CPP supports the debugging of managed code in the same way as the Mono. For more information, refer to Debugging C# code in Unity.

Building a project with IL2CPP

To build a project with IL2CPP, you must have Il2CPP installed as part of your Unity installation. You can select IL2CPP as an optional module when you first install a version of Unity, or add IL2CPP support to an existing installation through the Unity Hub. For more information, refer to Installing the Unity Hub and Add modules to the Unity Editor.
IL2CPP also requires some systems native to the target platform to generate the C++ code. This means that cross-compilation is generally not supported and to build an IL2CPP Player for a particular target platform you must build from an Editor running on the same platform. For example, to build a macOS Player with IL2CPP, you must build on macOS. The exception to this is Linux, where building Linux Players on other desktop platforms is supported. For more information, refer to Linux IL2CPP cross-compiler.
You can change the scripting back end Unity uses to build your application in one of two ways:
  • Through the
    Player Settings

    ?

    menu in the Editor. Perform the following steps to change the scripting back end through the Player Settings menu:
    1. Go to Edit >
      Project Settings

      ?

      .
    2. Click on the Player Settings button to open the Player settings for the current platform in the Inspector.
    3. Navigate to the Configuration section heading under the Other Settings sub-menu.
    4. Click on the
      Scripting Backend

      ?

      dropdown menu, then select
      IL2CPP

      ?

      .
    You can also open the Player Settings menu from the Build Profiles window; go to File > Build Profiles and click on the Player Settings tab.
  • Through the Editor scripting API. Use the 
    PlayerSettings.SetScriptingBackend
     property to change the scripting back end that Unity uses.

The Configuration section of the Player settings

For more information about system requirements for desktop platforms, including IL2CPP requirements for individual platforms, refer to the Desktop section of System Requirements for Unity.

How IL2CPP works

When you build with IL2CPP, Unity automatically performs the following steps:
  1. The Roslyn C# compiler compiles your application's C# code and any required package code to .NET DLLs (managed assemblies).
  2. Unity applies managed code stripping. This step can significantly reduce the size of a built application.
  3. The IL2CPP back end converts all managed assemblies into standard C++ code.
  4. The C++ compiler compiles the generated C++ code and the runtime part of IL2CPP with a native platform compiler.
  5. Unity creates either an executable file or a DLL, depending on the platform you target.

Optimizing IL2CPP build times

Project build times with IL2CPP can be significantly longer than with Mono. However, you can do several things to reduce build time:
  • Exclude your Unity project and target build folders from anti-malware software scans before you build your project.
  • Store your project and target build folder on the fastest disk drive you have available. Converting IL code to C++ and compiling it involves many read/write operations, so a faster storage device speeds up this process.
  • Change the IL2CPP Code Generation option in the Player Settings. To change how IL2CPP generates code, open the Player Settings and configure the IL2CPP Code Generation option. By default, the Optimize for runtime speed option is enabled, which produces more machine code that reduces the impact of IL2CPP at runtime. To reduce build times, you can set this option to Optimize for code size and build time. This method produces and includes less machine code in the binary executable and so can reduce performance at runtime, but also significantly reduces build times and binary size.
  • On Linux, change the IL2CPP LTO Mode option in the Player settings. To change the link-time optimization (LTO) mode that IL2CPP uses, open the Linux Player settings or Embedded Linux Player settings, and change IL2CPP LTO Mode to Thin. This setting provides strong optimizations while requiring less time than the Full option.

Optimizing runtime performance with Burst

In suitable projects, you can improve the runtime performance of your project by using the Burst compiler alongside IL2CPP to compile compatible sections of your code to highly optimized machine code. For more information, refer to Burst compilation.

Additional resources