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, see 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, see 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# scripts from the project converted to C++ code.

Unity generates the libmain and libunity symbol files. Gradle 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.

Public symbol files use the .sym.so file extension.

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, see –only-keep-debug in the Linux user manual.

Debugging symbol files use the .dbg.so file extension.

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 are not available and Unity always generates public symbol files.

Generating a symbols package

To enable symbols package generation for your application:

1. Open the Build Settings window (menu: File > Build Settings).
2. Click Player Settings. This opens the Player Settings window.
3. Select the Android settings tab and go to Other Settings > Configuration.
4. Set Scripting Backend to IL2CPP.
5. Exit the Player Settings window and go back to the Build Settings window.
6. Select the Android platform from the Platform list.
7. Enable Create symbols.zip.

After you enable symbols package generation, building your project generates a .zip file that contains symbol files for the libmain, libunity, and libil2cpp libraries. Unity generates both public and debugging symbols for the libil2cpp library, and public symbols for the libmain and libunity libraries. 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 or generate symbols when you run the build process. Instead, it exports the project for Android Studio and creates an empty directory at unityLibrary/symbols 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. To get the libmain and libunity symbol files and complete the symbols package, you must manually find and copy them into the unityLibrary/symbols/<architecture>/ directory. Their location depends on whether you enable the Strip Engine Code Player Setting:

• Strip Engine Code enabled:
• libunity: <project-path>/Temp/StagingArea/symbols/<architecture>/. Note: Unity removes the Temp directory when you close the Editor. This means you must copy/move the symbol files after you export the project but before you close the Editor.
• libmain: <editor>/PlaybackEngines/AndroidPlayer/Variations/<scripting backend>/<build type>/Symbols/<architecture>/
• Strip Engine Code disabled:
• libunity and libmain: <editor>/PlaybackEngines/AndroidPlayer/Variations/<scripting backend>/<build type>/Symbols/<architecture>/

Before you use a public or debugging symbol file, you must remove part of the file extension. For public symbol files, this is .sym. For debugging symbol files, this is .dbg.

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, see 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.