Symbol table classification
Download
Focus Mode
Font Size
This article primarily covers the definition, lookup, and detailed explanations of various configurations for symbol tables on the Android, iOS, and Harmony platforms.
Android symbol table
In the Android platform, symbol tables include two types: SO symbol tables and Java mapping files.
SO symbol table: A symbol table is a mapping table between memory addresses and function names, file names, and line numbers. The symbol table elements are:
<start address> <end address> <function> [<filename:line number>].For Native Crash, to quickly and accurately locate the code position where a user's App crashes, the platform uses symbol tables to parse and restore the program stack of the App crash, as shown in the following figure:
mapping file: A mapping file is used to deobfuscate obfuscated Java code. For details, see Code Obfuscation.
Android mapping files are associated by App version and build number. For example, for the specified exception in the example above, the platform locates the matching symbol table file by App version and build number. For a given App version and build number, the platform supports uploading multiple symbol table files, which are distinguished by file names.
The platform recommends that business parties name the host mapping file as mapping.txt, and name plugin or component symbol table files as xxx_mapping.txt. These symbol table files can be uploaded in batches or multiple times. For details, see Uploading Plugin Symbol Tables for Android Apps.
Look up symbol tables
Location of SO Symbol Table
In the Android platform, Debug SO files refer to SO files with debugging information, which contain symbol information for stack restoration.
Note:
To facilitate retrieving the Debug SO files corresponding to crashes and restoring the stack, it is recommended to back up Debug SO files during each build or release of the App version, or to upload the symbol tables to the platform using the symbol table upload tool.
CMake Compilation Project: By default, the Debug SO files compiled in Debug mode are located at
<Project Folder>/<Module>/build/intermediates/cmake/debug/obj/local<Architecture>/.
NDK Compilation Project: By default, the Debug SO files compiled in Debug mode are located at
<Project Folder>/<Module>/build/intermediates/ndk/debug/obj/local<Architecture>/.
mapping file location
By default, the mapping file is located at
<Project Folder>/<Module>/build/outputs/mapping/<build-type>/.
Match symbol tables with crashes
For Native Crash stack restoration, the platform needs to match symbol table files based on UUID. Only when the UUID of the uploaded symbol table file matches the UUID of the SO file in the Native Crash stack (matching from the end backwards) can the stack be accurately restored.
For Java stack restoration, the current platform uses App version number + build number to identify and locate mapping files.
To view the UUID of the symbol table file, for details, see UUID Extraction Guide.
In Issue Details > Message Details > Symbol Table, view the symbol table information in the current exception stack.
View the UUID of the Debug SO files
The UUID of the symbol table file is consistent with that of the Debug SO file. Therefore, you can view the UUID of the Debug SO file using the symbol table file generated by the symbol table tool. The steps are as follows: Generate the symbol table file (.zip) -> Unzip the symbol table file (.symbol) -> Open the symbol table file using a text editor.
The "SHA-1" information of the symbol table file is the UUID of the Debug SO file and also the UUID of the symbol table file. If the file is large, it is recommended to use a text editor such as "Sublime Text" to open the symbol table file. For more details, see UUID Extraction Guide.
Note:
Since the platform has adopted a new UUID calculation rule, to correctly match the SO file corresponding to the Crash stack, please use version 2.5.0 or later of the symbol table tool.
Locate the Debug SO file corresponding to the Crash
If the symbol table file or Debug SO file corresponding to the Crash can no longer be found locally, but the Native project code for the App version associated with the Crash can still be retrieved, it is recommended to recompile the Debug SO file using NDK and generate the symbol table file with the symbol table tool.
Note:
If the Debug SO file cannot be retrieved from the Native project code, the Crash stack cannot be restored. Therefore, it is recommended to back up the Debug SO file when building or releasing each App version.
iOS symbol table
A symbol table is a mapping table between memory addresses and function names, file names, and line numbers. The symbol table elements are:
<start address> <end address> <function> [<filename:line number>].To quickly and accurately locate the code position where a user's App crashes, the platform uses symbol tables to parse and restore the program stack of the App Crash, as shown in the following figure:
dSYM file
dSYM stands for Debug Symbols, namely the symbol table file. Symbols correspond to classes, functions, variables, etc. This symbol table file maps memory to symbols, such as function names, file names, line numbers, and plays a crucial role in crash log analysis.
In the iOS platform, the dSYM file refers to an object file with debugging information, typically named: xxx.app.dSYM. As shown in the following figure:
Back up symbol table files:
To facilitate retrieving the dSYM file corresponding to a Crash and restoring stack information, it is recommended to back up the dSYM file when building or releasing each App version.
Locate the dSYM file
Generally, after compiling the project, the dSYM file is located in the same directory as the App file. The following uses Xcode as the IDE to provide detailed instructions on locating the dSYM file.
1. Go to Xcode.
2. Open the project (that has been compiled).
3. Locate Products in the left sidebar.
4. Right-click the compiled "xxx.app", then click Show in Finder.
Note:
If there are multiple dSYM files, you can specify the input as the directory containing the dSYM files or the project directory when uploading using the symbol table tool.
Xcode Debug Compilation Configuration
By default, Xcode Release builds generate dSYM files, while Debug builds do not. The corresponding Xcode configurations are as follows:
XCode -> Build Settings -> Code Generation -> Generate Debug Symbols -> YesXCode -> Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File
The dSYM file corresponds to the UUID of the Crash
When restoring a Crash stack, the platform needs to match symbol table files based on UUID. Only when the UUID of the uploaded symbol table file matches the UUID of the Crash-related App can the stack be accurately restored.
To view the UUID of the symbol table file, for details, see UUID Extraction Guide.
In Issue Details > Message Details > Symbol Table, view the symbol table information in the current exception stack.
View the UUID of the dSYM file
View UUID via command
xcrun dwarfdump --UUID <dSYM file>
View UUID via symbol table file
The UUID of the symbol table file is consistent with that of the dSYM file. Therefore, you can view the UUID of the dSYM file using the symbol table file generated by the symbol table tool. The steps are as follows: Generate the symbol table file (.zip) -> Unzip the symbol table file (.symbol) -> Open it with a text editor.
The "UUID" information in the symbol table file is the UUID of the Debug SO file and also the UUID of the symbol table file itself. If the file is large, it is recommended to use a text editor such as "Sublime Text" to open the symbol table file.
Retrieve the dSYM file corresponding to the App published to the App Store
Support retrieving the dSYM file corresponding to the App published to the App Store via Xcode, iTunes Connect, or the mdfind tool.
1. Open the top menu bar in Xcode > Window > Organizer window.
2. Open the top menu bar in Xcode, and select the Archives Tag.
3. Locate the published archived package, right-click the corresponding archived package, and select the Show in Finder action.
4. Right-click the located archived file and select Show contents.
5. Select the dSYMs directory, inside which are the downloaded dSYM files.
1. Log in to iTunes Connect.
2. Go to My Apps > Activities page.
3. In All Builds, select a specific version and click Download dSYM (Download dSYM) to download the dSYM file.
1. Locate the UUID corresponding to the Crash on the platform's issue page.
2. Then, in the Mac Shell, use the mdfind command to locate the dSYM file.
mdfind "com_apple_xcode_dsym_UUIDs == <UUID>"
Note:
Note that when using mdfind, the UUID requires format conversion (adding "-"), for example: 12345678-1234-1234-1234-xxxxxxxxxxxx.
For example, if the UUID of the dSYM to be located is: E30FC309DF7B3C9F8AC57F0F6047D65F, use the following command to locate the dSYM file.
mdfind "com_apple_xcode_dsym_UUIDs == E30FC309-DF7B-3C9F-8AC5-7F0F6047D65F"|12345678-1234-1234-1234-xxxxxxxxxxxx|
Note:
We recommend backing up the dSYM file corresponding to the App each time you build or release an App version.
HarmonyOS (Hongmeng) Symbol Table
SO symbol table: A symbol table is a mapping table between memory addresses and function names, file names, and line numbers. The symbol table elements are:
<start address> <end address> <function> [<filename:line number>].For HarmonyOS Native Crash, to quickly and accurately locate the code position where a user's HAP encounters a crash, the platform uses symbol tables to parse and restore the program stack of the crashed HAP. For example, as shown in the following figure:
nameCache & SourceMaps files: Harmony's nameCache & SourceMaps files are similar to Android's mapping: The nameCache file is used for mapping symbols and variable names before and after obfuscation in ts/js files, while the SourceMaps file maps line numbers before and after obfuscation in ts/js files.
In the HarmonyOS IDE, configure the obfuscated build for HAP or HAR packages. For details, see HarmonyOS Code Obfuscation Rules Configuration and Building Closed-Source HAR in HarmonyOS.
nameCache & SourceMaps files are associated via
HAP version + build number. For example, for the specified crash instance above, the platform locates matching symbol table files by HAP version + build number. For a given HAP version and build number, the platform supports uploading multiple symbol table files, distinguished by their filenames. For instance, under the same version number + build number, the following files can be uploaded simultaneously.nameCache.JSON
SourceMaps.JSON
rumpro_nameCache.JSON
rumpro_SourceMaps.JSON
The platform recommends that services name the host's nameCache and SourceMaps files as nameCache.JSON and SourceMaps.JSON, respectively. Symbol table files for plugins or components should be named xxx_nameCache.JSON or xxx_SourceMaps.JSON. These symbol table files can be uploaded via batch upload or multiple uploads. If a file with the same name already exists under the same version number + build number, uploading it again will overwrite the previous file with the same name.
Note:
Currently, the HarmonyOS HAR package does not support generating SourceMaps files through obfuscated builds.
If the link for building closed-source rules cannot be accessed, you need to apply for HarmonyOS development permissions from Huawei.
Look up symbol tables
Location of SO Symbol Table
In the Harmony platform, Debug SO files refer to SO files containing debugging information, which includes symbol information for users to restore the stack. The Harmony platform compiles SO files using DWARF 5 format debugging information by default, while the Android platform typically uses DWARF 4/3 format debugging information.
Note:
To facilitate locating the Debug SO files corresponding to crashes and restoring the stack, it is recommended to back up the Debug SO files each time you build or release a HAP version. Alternatively, you can use the platform's symbol table upload tool to upload the symbol tables to the platform.
By default, Harmony platform Native code is compiled using CMake. The compiled Debug SO files are located at
<Project Folder>/<Module>/build/default/intermediates/cmake/default/obj/<Architecture>/
nameCache & SourceMaps file location
By default, the nameCache file is located at:
<Project Folder>/<Module>/build/default/cache/default/default@CompileArkTs/esmodule/release/obfuscation/nameCache.JSON/By default, the SourceMaps file is located at:
<Project Folder>/<Module>/build/default/cache/default/default@CompileArkTs/esmodule/release/SourceMaps.JSON/
Reminder:
To facilitate locating the ts stack corresponding to crashes, it is recommended to back up the nameCache and SourceMaps files each time you build or release a HAP version. Alternatively, you can use the platform's symbol table upload tool to upload the symbol tables to the platform.
Matching SO Symbol Tables to Crashes
Harmony platform also uses SO UUID to match symbol table files. For matching rules and UUID extraction rules, see Android Symbol Tables.
Help and Support
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback