To help you debug your application, Unity can generate a package that contains symbol files with debug metadata for native Unity libraries. Symbol files contain an executable file section called symbol table (.symtab
) that translates active memory addresses into information you can use, like a method name. The translation process is called symbolication. You can upload a symbols package to the Google Play Console to see a human-readable stack trace on the Android Vitals dashboard.
For more information about executable file (ELF) section, refer to Wikipedia.
Unity generates symbol files for the following libraries:
libmain
: Responsible for the initial Unity engine loading logic. The symbol file is precompiled.
libunity
: Unity’s engine code:
libil2cpp
: Contains C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary:
Gradle generates the remaining symbol files.
Depending upon your application build format, Unity generates symbol files in two ways :
apk
or aab
.aab
. Unity doesn’t embed symbol files into an apk
.Use UserBuildSettings.DebugSymbols.format API to set the format of the symbol package.
Unity uses debugSymbolLevel property of Gradle to generate symbol files. There are two types of symbol files:
Use UserBuildSettings.DebugSymbols.level to generate the required type of symbol file.
Note: By default, Gradle generates symbol files with .so.sym
or .so.dbg
extensions. Some digital distribution services don’t recognize these extensions and require files with .so
extension. In such cases, use Unity.Android.Types.DebugSymbolFormat.LegacyExtensions API to create symbol files with .so
extension.
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle | DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;
A public symbols file contains information that resolves function addresses to human-readable strings. These files don’t contain debugging information. This makes public symbol files smaller than debugging symbols files.
A debugging symbols file contains full debugging information and a symbol table section. Use it to:
Note: If debugging symbols aren’t available, Unity places a public symbols file in your project at build time. For the libmain
and libunity
libraries, debugging symbols aren’t available and Unity always generates public files.
You can instruct Unity to include additional symbol files. This is useful if you use shared libraries and want your local debugger, and Google Play, to resolve the shared library stack traces if the application crashes.
To make Unity include a custom symbols file:
Assets
folder (Project tab) More info.so
file extension.Whenever Unity generates a symbols package, it adds the additional symbol files to the symbols package.
If you want to make Unity include a custom symbols file from a C# script, the UnityEditor.Android namespace includes the following APIs to set the CPU and Shared Library Type respectively:
Note: The symbols file name must match the name of the shared library that the symbols file is for. For example, if a shared library is called mylibrary.so, the symbols file must also be named mylibrary.so. To avoid file name collisionsA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info
See in Glossary, the symbols file and the shared library must be in separate directories.
Important: Ensure the symbols file is up to date and compatible with the shared library that contains the executable code. If you don’t, your local debugger and Google Play will fail to resolve stack traces for code in the shared library.
There are two ways to enable symbols package generation for your application:
To enable symbols package generation through the Build Profiles window:
Open the Build Profiles window (menu: File > Build Profiles).
From the list of platforms in the Platforms panel, select Android or create a build profile for the Android platform.
Set Debug Symbols to one of the following:
Set Symbols output options to .zip.
After you enable symbols package generation, building your project generates a .zip
file that contains symbol files for the libmain
and libunity
library. If you set your scripting backendA framework that powers scripting in Unity. Unity supports three different scripting backends depending on target platform: Mono, .NET and IL2CPP. Universal Windows Platform, however, supports only two: .NET and IL2CPP. More info
See in Glossary to IL2CPPA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info
See in Glossary, the .zip
also contains a symbol file for the libil2cpp
library. Unity places this symbols package within the output directory.
If you enable Export Project in the Android build settings, Unity doesn’t build the project. Instead, it exports the project for Android Studio, generates symbols for libmain
and libunity
, and places them within unityLibrary/symbols/<architecture>/
in the output directory. When you build your exported project from Android Studio, Gradle generates the libil2cpp
symbol file and places it within the unityLibrary/symbols/<architecture>/
directory alongside the libmain
and libunity
symbol file.
If you’re producing an Android App bundle (aab), you can embed symbols directly into an aab
and upload it to Google Play.
Note: Unity doesn’t embed symbols into an apk
. In this case, you must upload a zip file with symbols separately.
UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.IncludeInBundle;
To produce a zipped symbols package, use the following code:
UserBuildSettings.DebugSymbols.level = DebugSymbolLevel.SymbolTable;
UserBuildSettings.DebugSymbols.format = DebugSymbolFormat.Zip | DebugSymbolFormat.LegacyExtensions;
After you upload your application to Google Play, you can upload a public symbols zip package. For information on how to do this, refer to Google’s documentation: Deobfuscate or symbolicate crash stack traces.
Note: Google Play doesn’t symbolicate crashes that your application received before you uploaded the symbols package.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.