符号表工具使用说明
1 介绍
什么是符号表？ 符号表是内存地址与函数名、文件名、行号的映射表。符号表元素如下所示：
<起始地址> <结束地址> <函数> [<文件名:行号>]
为什么要配置符号表？
为了能快速并准确地定位用户APP发生Crash的代码位置，CrashSight使用符号表对APP发生Crash的程序堆栈进行解析和还原。 举一个例子：
| 还原前堆栈 | 还原后堆栈 |
|---|---|
| #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) |
而符号表工具，正是CrashSight提供给开发者提取符号表文件(.symbol)的工具。 如果项目工程中没有Native代码，但使用了代码混淆proguard，那么只需要上传Proguard生成的Mapping文件。该符号表也支持Mapping文件的上传，具体方法请参看下文。
1.1 环境要求
符号表工具的运行需要64位Java运行环境（Java SE Runtime Envrionment），JRE或者JDK版本需要>=1.6。Windows符号表必须在Windows平台上进行上传。
1.2 符号表提取要求
提取符号表需要符号表工具和带符号表的库文件（详见各平台符号表文件格式，及在unity、unreal引擎中的生成方法）。
1.3上传功能
CrashSight符号表工具支持上传功能。 使用上传功能时，需要指定以下信息： App ID App版本 上报地址
1.4 如何获取App ID
2 如何使用符号表工具
符号表工具支持Windows、Linux、Mac三个平台，提供了JAR包crashSightSymbolTool.jar
在项目左侧导航栏的“接入指南”中，可以下载符号表工具：
使用方法及参数如下：
jar -jar <JAR包> [-选项 <参数>]
建议直接在“接入指南”中复制自动生成的命令，以免遗漏参数。
| 选项 | 说明 |
|---|---|
| -i | 指定文件路径，可指定目录（Windows符号表只可以指定目录） |
| -p | 指定符号表平台类型：aos/ios/win,分别对应Android，iOS和Windows平台 |
| -o | 指定输出的符号表zip文件的路径，必须是zip文件（Windows符号表在系统临时文件目录，不支持指定） |
| -d | 调试模式开关（默认关闭） |
| -s | 指定配置文件（默认读取Jar目录下的setting.txt文件） |
| -u | 上传开关 |
| -url | 上传URL |
| -id | App ID |
| -key | App Key |
| -package | App包名 |
| -version | App版本 |
| -channel | App渠道（可选） |
| -mapping | Mapping文件（可选） |
| -symbol | 生成Symbol文件（可选） |
| -m | 生成模式，填 win 或者 ori（默认为win, 仅支持windows符号表使用） |
注意该版本的符号表工具默认不生成Symbol文件，如果需要指定"-symbol"参数运行符号表工具。
上报URL：默认新加坡
- 国内：https://api.crashsight.qq.com/openapi/file/upload/symbol
- 新加坡：https://crashsight.wetest.net/openapi/file/upload/symbol
3 常见问题
-
符号表工具的具体输入文件是什么？
安卓需要输入的文件是带调试信息的.so文件，iOS的输入是dsym文件
-
符号表的 UUID 是什么?
UUID是so/dsym内置的属性，同一份文件，该值不会改变；
-
符号表的上传更新是增量更新还是覆盖更新？
相同UUID会覆盖，不同UUID会保留.
-
使用符号表上传工具，上传完成之后怎么自动确认（校验）上传是成功了的。
一般来说符号表工具成功执行完成，就是成功了。也可以在页面检查对应版本的符号表是否上传。
-
上传工具需要更新的话，是如何进行通知以及更新的？ 非必要更新，是会放到本文档中。如果存在必须要更新才能使用的情况，会通过接入时的沟通渠道进行联系。
4 iOS系统符号表获取
由于iOS崩溃会出现在系统库内，为了还原这部分崩溃，需要使用系统库的符号表。iOS系统符号表的获取方式如下：
-
准备对应系统版本/机型的设备一台。这里尽可能的使用崩溃相同机型，因为iOS同一版本系统，不同机型，有可能是不同的符号表。
-
安装Xcode的MAC一台。最好是安装最新Xcode的MAC，否则可能不支持最新的iOS系统。具体支持列表，可以查看MAC机器目录 /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport 下，是否有需要上传符号表的系统版本号。
-
USB连接MAC，打开Xcode的设备管理，等待同步完成，通常需要10到30分钟以上。
-
查看MAC机器 "~/Library/Developer/Xcode/iOS DeviceSupport" 目录下是有对应的版本号的文件夹。
-
将对应版本的系统文件夹压缩并发送给CrashSight管理人员。
5 各平台符号表文件格式，及在unity、unreal引擎中的生成方法
1.Android--debug版的.so文件。
Unity中在build settings里【Create symbols.zip】选择Debugging。
Unreal中 项目设置-高级编译 勾选上【固定保存带符号libUnreal.so的副本】。
2.iOS--dSYM文件。
Unity需要在导出的xcode项目中配置GENERATE_DEBUG_SYMBOLS(True)和 DEBUG_INFORMATION_FORMAT(dwarf-with-dsym)。
Unreal在Project Settings-Platforms-iOS-Build中勾选Generate dSYM file for code debugging and profiling和Generate dSYM bundle for third party crash tools。
3.Windows--PDB文件，以及对应的EXE或DLL文件。
Unity在build settings里勾选上【Copy PDB files】。
Unreal 文件-打包项目-打包设置 勾选【包括调试文件】。
4.MacOS--dSYM文件。
Unity可以在构建产物的XXX_BackUpThisFolder_ButDontShipItWithYourGame目录中找到dSYM文件。
Unreal在Project Settings-Project-Packaging-Project中勾选For Distribution和Include Debug Files in Shipping Builds，打包生成的xcarchive文件中会包含dSYM。