Android symbols

To help you debug your application, Unity can generate a package that contains symbol files for native Unity libraries. Symbol files contain a table 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.

There are two types of symbol files:

• Public: A small file that contains a symbol table. For more information, refer to Public symbols.
• Debug: Contains everything that a public symbol file contains, and full debugging information that you can use for more in-depth debugging. For more information, refer to Debugging symbols.

You can generate symbol files for the following libraries:

• libmain: Responsible for initial Unity engine loading logic.
• 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 from the project converted to C++ code.

Unity generates the libmain and libunity symbol files. GradleAn Android build system that automates several build processes. This automation means that many common build errors are less likely to occur. More info
See in Glossary generates the libil2cpp symbol file.

Public symbols

A public symbol file contains information that resolves function addresses to human-readable strings. Unity uses the --strip-debug parameter to create public symbols that remove more in-depth debug information. This makes public symbol files and packages smaller than debugging symbol files and packages.

Debugging symbols

A debugging symbol file contains full debugging information and a symbol table. Use it to:

• Resolve stack traces and to debug applications that you have source code available for.
• Attach a native debugger to the application and debug the code.

Unity uses the --only-keep-debug parameter to create debugging symbols. For more information, refer to –only-keep-debug in the Linux user manual.

Note: If debugging symbols aren’t available, Unity places a public symbol file in your project at build time. For the libmain and libunity libraries, debugging symbols aren’t available and Unity always generates public symbol files.

Custom symbols

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:

1. In the Project windowA window that shows the contents of your Assets folder (Project tab) More info
   See in Glossary, select a plug-inA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
   See in Glossary that has a .so file extension.
2. In the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
   See in Glossary, find the Platform settings section.
3. Set CPU to the CPU architecture that the symbols file is compatible with.
4. Set Shared Library Type to Symbol.

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:

• PluginImporter.SetAndroidCPU
• PluginImporter.SetAndroidSharedLibraryType

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.

Generating a symbols package

There are two ways to enable symbols package generation for your application:

• Through the Build Settings window.
• Using the EditorUserBuildSettings.androidCreateSymbols API.

To enable symbols package generation through the Build Settings window:

1. Open the Build Settings window (menu: File > Build Settings).

2. Select the Android platform.

3. Set Create symbols.zip to one of the following:

   • Public
   • Debugging

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.

Using symbols in the Google Play console

After you upload your application to Google Play, you can upload a public symbols package for it. 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.