IL2CPP build size improvements

NOTE: The original post is outdated. Please refer to this knowledge base article instead - https://support.unity3d.com/hc/en-us/articles/208412186






Deprecated original article:

We created a small guide on IL2CPP build sizes. What is important, what can be improved and how you can improve it. We constantly work on the improvements and could already gain massive size improvements in the latest patches. Ensure always to use the latest patch, as we fix bug on daily basis and work on size improvements in parallel. Although, many parts are similar to WebGL this guide is mainly targeted to iOS. But all the fixes we make for IL2CPP have direct affect on WebGL and iOS builds.

Why is the the binary size of the IL2CPP project larger that the mono version?

Two things apply:

• If you make a universal build, there's a 32bit slice and a 64bit slice, which contains the exact same executable for 2 different architectures so nearly doubled size.
• IL2CPP produced bigger builds even if you just compare ARMv7 Mono with ARMv7 IL2CPP; this had to do with how we dealt with the type metadata. It was resolved in Unity 4.6.4p2.

With "Universal" builds, you will always yield larger binary sizes than just having ARMv7 or ARM64. The removal of the managed assemblies already made the builds smaller (in Unity 4.6.3f1), the real improvement came when we were able to construct at least generic typeinfos at runtime, but this is now partly possible (since Unity 4.6.4p1). But we have some more improvements in production, so stay tuned. Universal builds include 32-bit and 64-bit slices in the fat executable which results in at least doubled size of standard mono 32bit.

We made improvements to generic type and array generation in Unity 4.6.4p1 too. Apart from that, there's information here about reducing your iOS build size: http://docs.unity3d.com/Manual/iphone-playerSizeOptimization.html. For additional information read in Stripping below.

Please always make a comparison table with mono (ARMv7), IL2CPP (ARMv7), IL2CPP (ARM64), IL2CPP Universal and which striping settings you use to have all information to compare!

It's always worth to check the actual binary size, as this is the one which is affected by the source code compilation referred to as the fat file containing binary from ARMv7 and ARM64 if it is a universal build and therefore nearly doubled size of a single ARMv7 mono or IL2CPP build. If you make a universal build, there's a 32bit slice and a 64bit slice, which contains the exact same executable for 2 different architectures so nearly doubled size. If you want to compare the output directly please compare ARMv7 mono with ARMv7 IL2CPP.

Which sizes limit does Apple check?

Apple has a 80MB limit for the 32bit+64bit code segment in total if you support a minimum OS of less than iOS 7.0. Apps that are set to minimum OS of 7.0 or greater have a binary size limit of 60MB (60 000 000 bytes) per architecture slice. 100MB (mobile data) application limit (user needs to download via Wifi if >100MB) and max 4GB application limit. 80MB and 60MB/60MB is the limit for code segment size included in the fat binary for the 32bit and 64bit slice. You need to use otool to get the right numbers. 100MB applies to to the .ipa size (Use the estimate button in Xcode after archiving to get the right estimate), this determines if users need a WiFi connection to download your app. Follow following steps to get the right numbers:

1. Build your app in release mode. Do not use debug mode, as it does not represent your final app. Ensure you use correct optimisation, more information can be found here: http://docs.unity3d.com/Manual/iphone-playerSizeOptimization.html.
2. Archive your app in XCode.
3. Use the estimate button to get the estimated size of your app to ensure if you are above or below 100MB or the overall size of 4GB.
   Note: since XCode 6.3 there is no estimate button anymore. You can calculate it by using following formula, but be aware that the compression coefficient might vary:
   
   Code (CSharp):

   1. app_store_size = sizeof(.ipa/(zip with exec_binary removed)) + sizeof(codesegment(exec_binary)) + 0.2 * sizeof(datasegment(exec_binary))
   The formula is coming from broader knowledge that only the code segment gets encrypted and the data segment compression ratio can be verified pretty easy.
   Extract the data segment from executable via dd command (you can specify byte offset + length) and then try to compress it. The code segment gets scrambled to look like a perfect noise. You need to descramble it with a decryption key before executing. iTunes/App Store app manages there keys. That's why we add code segment as whole without adjusting for compression ratio.
   
4. Once you have archived your app, show the .xcodearchive in your finder
   1. Show Package Content
   2. Go to Products/Applications/Productname.app. (Which should have nearly the same size as the estimated size button in XCode returns)
   3. Show the content of the Productname.app
   4. Locate the ProductName binary (exec_binary) on the top level.
5. Use otool to generate the output for the 80MB limit.
   
   
   Code (CSharp):

   1. otool -l path_to_exec_binary
   or even
   Code (CSharp):

   1. size path_to_exec_binary
6. Now you can retrieve the output depending on the architecture (armv7 + a section arm64 if it's a universal build) Gather the information for armv7 (LC_SEGMENT) and do the same for arm64 if applicable (LC_SEGMENT_64)
   1. Locate the LC_SEGMENT with segname __TEXT and take the filesize
      code segment size = 30474240 ~= 30MB
   2. Locate the LC_SEGMENT with segname __DATA and take the filesize
      data segment size (mostly metadata) = 10420224 ~= 10 MB
   This results in following otool result table:
   
   architecture armv7:
   code segment size = 30474240 ~= 30MB
   data segment size (mostly metadata) = 10420224 ~= 10 MB
   segment + data segment = 30 + 10 = 40MB
   
   architecture arm64:
   code segment size = 25559040 ~= 26MB
   data segment size (mostly metadata) = 17727488 ~= 18 MB
   segment + data segment = 26 + 18 = 44MB
   
   Apple uses for their check armv7(code segment)+arm64 (code segment) which results in a otool report of 30MB + 26MB = 56MB in this example which is below the 80MB for <7.0 and 30MB & 26MB are each below 60MB >=7.0 for a universal build.

It's easy to test this, make a test app in release mode and submit it to the app store, the static project checker in the beginning should alert you if a slice is over a certain limit. For the estimated size XCode should take all the DRM measurements into account, but if you encounter a different behaviour please let us know! Again, as soon as you uploaded a test app to iTunesConnect, it should show you any pitfalls and you should see also the app size in the Version Summary page.


Stripping
The IL2CPP scripting backend always does byte code stripping, no matter what the “Stripping Level” setting is in the editor. The best option for a user is to set the “Stripping Level” option in the editor to a value of “Disabled”, as the affect of any other “Stripping Level” option will likely be minimal on executable size, because IL2CPP will strip anyway. If the you choose a “Stripping Level” value other than “Disabled” you could run into problems, because then the IL2CPP build toolchain in the editor will attempt to determine which native engine code is used by you scripting assemblies, and only register that native code when the player starts. If you encounter problems with your stripping settings and you believe they are wrong, please submit a bug report.

Exceptions
By default Mono exceptions are caught in Xcode, but IL2CPP exceptions are not.

You can make the Xcode debugger break on exceptions by adding an Exception breakpoint as described here: https://developer.apple.com/library.../articles/adding_an_exception_breakpoint.html

Replace the text "std::underflow_error" with "Il2CppExceptionWrapper" in the text-box shown on that page. You may need to restart Xcode, or possibly just the debug session.

In general the il2cpp managed callstacks are currently unreliable and on iOS only partially working - the way we do them often prints wrong functions. So for now you need to check the real callstacks int the XCode callstack window. We work on improvements on these areas though.

A managed exception is not necessarily an app crash. But to break on a managed exception in Xcode, set a breakpoint at il2cpp_codegen_raise_exception or in case of a nullreference exception you can set a breakpoint in NullCheck method in il2cpp-codegen.h You don’t want to break when the method is called, as it will be called very often, but you can break after the if check at the start of the NullCheck method.

5.3.x build size increase due to BitCode
Recently we are seeing number of questions scattered around forums regarding build size increase when building iOS applications with Unity 5.3.x often due to BitCode support enabled which is new in 5.3.x. This post aims to clarify some aspects of it in single place. http://forum.unity3d.com/threads/unity-5-3-x-build-size-increase-faq.383533/

Some more information to read about IL2CPP and 64bit can be found on our blog:
IL2CPP blog posts
iOS 64bit support

I hope this helps and if you have any questions or suggestions to improve the post, please let me know!

 

Hello,

did you file a bug for this codegen issue? We will be very happy in checking and fixing it
Which version of Unity are you using? Are you still having the same issue with the latest patch release btw?

Thanks,
Gabriele

 

@greyhoundgames I had to remove the generic parts for now, as it lacks information and a proper example. I'll work on one now and once I can provide you proper stats and examples, I'll push it again. What I generally do is to compare my codebase or the function I need against what is provided by the default implementation and estimate if it is suitable to make my own minimal implementation which I can compare then in a specific minimal example to compare the output. However, this is not easy and needs to be evaluated very carefully. The array part did not come out correctly, in the latest version it's not a problem to use them anymore, but in older versions the sizes of the generated code for arrays was not as improved as it is now. This should have been a hint if you have problems with the generated code sizes, you need to consider upgrading to one of the latest patch releases.

 

Any chance you can create a smaller repro case that does not contain the sensitive information and send that one to us? It is by far the best way to get the issue fairly quickly

Thanks,
Gabriele

 

@greyhoundgames

It is not surprising to have 100 Bulk_Generics .cpp files, it just happens to be exactly 100. As you make changes to the project or we make changes to the code generation, I would expect that number to differ. The il2cpp.exe chooses a number of types to include in each Biuld_Generics file, but it doesn't do anything about the number of Bulk_Generics files generated, so this should not be a problem.

None of the generic types you mentioned are bad to use. I would continue to use them, as they provide nice expressive power in C#, and the alternatives are often more difficult to use. We have had some customers see binary size decreases by making some targeted changes to the use or implementation of these generic types. For most projects though, this is an optimization that you should only undertake after measuring.

 

@bluescrn

It's not really correct to say that "generics are bad, actually. In past releases, the IL2CPP conversion process did cause generics to lead to increased code size. However, recent improvements in IL2CPP mean that generics are not a significant problem any more. n the next few weeks we will land changes to complete generics sharing, mean that the implementation of generics with the IL2CPP scripting backend will be on par with the implementation from the Mono scripting backend.

So I would not encourage you to move away from generics in your code. In fact, mscorlib makes heavy use of generics, so we need to do everything that we can to improve generics support no matter how much they are used in user script code.

With all of this said, we have has some users experience executable size decrease by moving away from generic types in some cases. This improvement is more about analysis of what parts of the managed code are actually being used (and removal of parts that are not necessary) than it is about generics in general.

As usual with any type of optimization, measurement and data are the best options.

 

@big_march

It is necessary to use link.xml only if you need to preserve some types from being stripped. Usually this happens with serializers, as they tend to use types at runtime. The need to link.xml will vary on a project by project basis.

I'm not sure how to reduce memory pressure other than to reduce the use of assets that are unnecessary. We're looking now at how to lower the IL2CPP memory usage to bring it in line with Mono, but we don't have anything ready yet.

 

@big_march

In IL2CPP stripping is always enabled. So even if the "Stripping Level" setting in the editor has a value of "Disabled", the IL2CPP scripting backend is still doing the equivalent of the "Byte code stripping" value. So you can same that "Stripping Level" is no longer a way to reduce executable size (and therefore memory), but that's only because IL2CPP is already doing stripping!

The link.xml file is used to augment stripping, to actually include code that would otherwise be stripped. It's role is unchanged with IL2CPP.

I hope this clears things up, let me know if it is not clear. Thanks.

 

@big_march

As long as you are sure that there are not any managed or native plugins in the build that you don't actually need, there are not too many options to make that smaller. We're working on some things from our end to decrease the executable size though, so this should decrease in future releases.

 

With Xcode 4.0 and later, when you build and archive, the products of your target and their dSYM file will be all archived. The archives can be used to symbolicate crash logs. Select the archive, and [show package contents], you can see the dSYMs and app are there. The dSYM is included within the app archive but not within the .ipa file. So so it is not possible to get it from downloading the app from the App Store. If you make a final distribution build for the app store the dSYM file is not used in the calculation of your app size and never included in your .ipa or transferred to the end user. Find more information about this topic in the official Apple Developer manuals.

 

@big_march

I don't believe that this is possible. However, you may want to try some of the profiling tools in Xcode. They might give you a better view into memory for native plugins.

 

The Data/Managed/*.dll AND Data/Managed/non-stripped/*'dll can be safely removed when using IL2CPP this is a bug which should be fixed soon.

 

@shinymark

Your best option for optimization is to follow the steps in David's initial post here to determine what is causing the size increase. If the entire 42 MB increase is from the 64-bit binary slice, then there is probably not a whole lot you can do from your end (other than drop 32-bit support, as you mentioned).

However, if the increase from the 64-bit slice is less than the total increase, then we probably need to do some more investigation to determine where the size is going.

Note from our side, we're still pushing to decrease binary sizes, so expect it to be less in the coming releases. However, we'll likely not be able to get both slices down to the size of a single slice.

 

The IL2CPP version is pretty much the same between versions 4.6, 5.0, and 5.1. The compiler warning in generated C++ code occur in all versions. So while I've not heard of any app submissions with 5.1, I do know that we've had many app submissions with the C++ warnings occurring, and we've not had any rejections do to those warnings.

 

@CPXTom

I don't think that there is a need for the UnityEngine.xml file in either of the directories you mentioned. This file probably should not be included in the build at all. The fact that is sounds like a bug. Can you submit a bug report on this issue? We should be able to correct it.

The SymbolMap files are used to generated accurate managed call stacks. So they are not strictly required, but if they are not present, managed stack traces will have some incorrect entries in them. If managed stack traces are not important for your project, then the SymbolMap files can be deleted.

 

@CPXTom

Thanks, we will investigate it.