Symbol Table Tool Usage Introduction

---

1 Introduction

What is a symbol table? A symbol table is a mapping table that contains memory addresses, function names, file names, and line numbers. Symbol table elements are as follows:

    <start address> <end address> <function> [<file name:line number>]

What is a symbol table for?

To locate the code where a crash happened in the user's app quickly and accurately, CrashSight uses symbol tables to analyze and retrace the crash stack. For example:

stack before retrace	stack after retrace
#00 pc 0021cdf4 /lib/libgame.so	#00 pc 0021cdf4 _ZNK14CAnimationNode13getCurEquipldEv(CAnimationNode.h:51)
#01 pc 002abe36 /lib/libgame.so	#01 pc 002abe36 _ZNSt6vectorl15NDKCallbackNodeSalS0_EE5beginEv(NDKHelper.cpp:312)
#02 pc 003aebee /lib/libgame.so	#02 pc 003aebee _ZNK6b2Vec26LengthEv(b2Math.h:121)

The symbol table tool is a tool CrashSight offers developers to extract symbol table files (.symbol). If the project doesn't contain Native code, but has used ProGuard to obfuscate code, just upload the Mapping file generated by ProGuard. The symbol table also supports uploading Mapping files. The way to do it is explained below.

1.1 Environment Requirements

The symbol table tool requires 64 bits Java SE Runtime Environment under 64bit. JRE and JDK version 1.6 and above. The Windows symbol table must be uploaded on a Windows platform.

1.2 Symbol Table Extraction Requirements

To extract symbol tables, the symbol table tool and libraries with symbol table are required (see Symbol table file format for each platform, and how to generate it in unity and unreal engines for more details).

1.3 Uploading Symbol Table

The CrashSight symbol table tool supports symbol table uploading. When using the uploading feature, the following info must be specified: App ID, App version, URL for reporting.

1.4 How to Obtain App ID

2 How to use Symbol Table Tool

The symbol table tool supports three platforms: Windows, Linux, and Mac. The corresponding symbol table tool can be downloaded from the "Tutorial" in the left sidebar of the project:

Download Symbol Table Tool open in new window (Download is unavailable due to an ongoing internal review. To download it, please contact crashsight@tencent.com)

2.1 Tool Usage and Options

    jar -jar <JAR file> [-option <parameter>]

It is recommended to copy the auto-generated commands directly in the "Tutorial" to avoid missing parameters.

Option	Note
-i	Assign a file path. It can be a directory (For Windows symbol tables, you can only specify directories)
-p	Platform type: aos/ios/win
-o	Assign a path for outputting symbol table zip files. It must be a zip file (Windows symbol tables are output to a temporary directory, and cannot be assigned a directory)
-d	Debugging mode switch (off by default)
-s	Assign a configuration file (the setting.txt file under the Jar directory is read by default)
-u	Upload switch
-url	Upload URL
-id	App ID
-key	App Key
-package	App package name
-version	App version
-channel	App channel (optional)
-mapping	Mapping file (optional)
-symbol	Generate symbol file (optional)
-m	Generation mode. Fill in "win" or "ori" ("win" by default. Only supports windows symbol tables.)

Note that the symbol table tool of this version doesn't generate .sym files by default. To get .sym files, specify the "-symbol" parameter before running the symbol table tool.

URL for reporting:

• Local(China): https://api.crashsight.qq.com/openapi/file/upload/symbol
• International: https://crashsight.wetest.net/openapi/file/upload/symbol

3 FAQs

1. What is the input file of symbol table tool? For Android, input .so files with debugging info. For iOS, input dsym files

2. What is a symbol table's UUID? UUID is a built-in property of so/dsym. For one single file, its value remains the same.

3. Does uploading a symbol table overwrite the previous table? The previous table will be overwritten if the two tables share the same UUID, but retained if the UUIDs are different.

4. After using the symbol table uploading tool, how can I know whether the upload is successful? Usually, the upload is successful as long as the symbol table tool is executed. You can also check on the page whether the symbol table of the corresponding version has been uploaded.

5. How would I know it when the uploading tool needs an update? And how to update it? If the update is optional, it will be included in this document. If the update is a must, users will be notified via the communication channel provided upon Integration.

4 Getting iOS system symbol table

Since iOS crashes occur within the system library, in order to symbolicate this part of the crash, you need to use the symbol table of the system library. iOS system symbol table can be obtained as follows:

1. Prepare a device corresponding to the system version / model. Here as much as possible to use crash the same model, because iOS the same version of the system, different models, may be different symbol table.

2. Prepare a Mac with Xcode installed. It is best to have a MAC with the latest Xcode installed, otherwise the latest iOS may not be supported. For a specific support list, check the MAC machine directory /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport for the version number of the system for which you need to upload a symbol table.

3. Connect to the MAC with USB, open Xcode's Device Manager, and wait for the synchronization to complete, which usually takes 10 to 30 minutes or more.

4. The "~/Library/Developer/Xcode/iOS DeviceSupport" directory is the folder with the corresponding version number.

5. Zip the corresponding version of the system folder and send it to the CrashSight administrator.

5 Symbol table file format for each platform, and the generating method in unity and unreal engine

1.Android - debug version of the .so file. Unity: in build settings, [Create symbols.zip] select Debugging. Unreal: in project settings - advanced compilation, check [Fixed save a copy of libUnreal.so with symbols]. 2. iOS - dSYM file. Unity: configure GENERATE_DEBUG_SYMBOLS(True) and DEBUG_INFORMATION_FORMAT(dwarf-with-dsym) in the exported xcode project. Unreal: Check Generate dSYM file for code debugging and profiling and Generate dSYM bundle for third party crash tools in Project Settings-Platforms-iOS-Build. 3. Windows - PDB files, and corresponding EXE or DLL files. Unity: check [Copy PDB files] in the build settings. Unreal: File-Package project-Package settings, Check [Include debug files].