dSYM iOS符号表配置

来源Bugly: https://bugly.qq.com/docs/user-guide/symbol-configuration-ios/?v=1.0.0

介绍

什么是符号表？

符号表是内存地址与函数名、文件名、行号的映射表。符号表元素如下所示：
<起始地址> <结束地址> <函数> [<文件名:行号>]

为什么要配置符号表？

为了能快速并准确地定位用户APP发生Crash的代码位置，Bugly使用符号表对APP发生Crash的程序堆栈进行解析和还原。
举一个例子：

Bugly提供了自动和手动两种方法配置iOS符号表。

自动配置：XCode + sh脚本

自动配置请首先下载和解压自动配置符号表工具包，然后选择上传方式并配置Xcode的编译执行脚本。

上传方式

使用脚本自动配置支持两种上传方式（建议用方式二）：

• 方式一：直接上传dSYM文件（默认方式 ）
• 方式二：提取dSYM文件的符号表文件并上传

其中，使用方式二需要额外操作以下几步：

• 下载符号表提取工具依赖的Java运行环境（JRE或JDK版本需要>=1.6）
• 把工具包buglySymbolIOS.jar保存在用户主目录（Home）的bin目录下（没有bin文件夹,请自行创建）:

配置Xcode编译执行脚本

• 在Xcode工程对应Target的Build Phases中新增Run Scrpit Phase

• 打开工具包中的dSYM_upload.sh，复制所有内容，在新增的Run Scrpit Phase中粘贴
• 修改新增的Run Scrpit中的 为您的App ID，为您的App Key， 为App的Bundle Id

脚本默认在Debug模式及模拟器编译情况下不会上传符号表，在需要上传的时候，请修改下列选项

• Debug模式编译是否上传，1＝上传 0＝不上传，默认不上传UPLOAD_DEBUG_SYMBOLS=0
• 模拟器编译是否上传，1＝上传 0＝不上传，默认不上传UPLOAD_SIMULATOR_SYMBOLS=0

至此，自动上传符号表脚本配置完毕，Bugly 会在每次 Xcode 工程编译后自动完成符号表配置工作。

手动配置

手动配置的流程如下：

• 下载最新版Bugly iOS符号表工具，其中工具包中包括：
  • 符号表工具JAR包（buglySymboliOS.jar）
  • Windows的脚本（buglySymboliOS.bat）
  • Shell脚本（buglySymboliOS.sh）
  • 默认符号表配置文件（settings.txt）
  • 符号表工具iOS版-使用指南
• 根据Crash的UUID定位dSYM文件
• 使用工具生成符号表文件（zip文件）
• 在页面上传符号表文件

其他说明

• Bugly iOS符号表工具2.3.0及以上版本增加了上传功能，2.5.0及以上版本支持dSYM文件的上传；

• 定位dSYM文件的方法和工具的使用方法请参考：“符号表工具iOS版-使用指南”。

  符号表上传接口

  Bugly提供了上传符号表的API接口（使用POST方式上传）:

• https://api.bugly.qq.com/openapi/file/upload/symbol

HTTPS接口支持上传dSYM文件（需要压缩成Zip文件）和符号表文件（Symbol）。

参数说明

上传接口的参数说明如下：

其中包名、版本号和符号表文件名需要做URL Encode。

例子：使用Curl上传

使用Curl工具来上传的例子如下：

• 上传dSYM文件

curl -k “https://api.bugly.qq.com/openapi/file/upload/symbol?app_key=xxxxxx&app_id=xxxxxx“ —form “api_version=1” —form “app_id=xxxxxx” —form “app_key=xxxxxx” —form “symbolType=2” —form “bundleId=com.demo.test” —form “productVersion=1.0” —form “channel=xxx” —form “fileName=app.dSYM.zip” —form “file=@app.dSYM.zip” —verbose

• 上传符号表文件（Symbol文件）

curl -k “https://api.bugly.qq.com/openapi/file/upload/symbol?app_key=xxxxxx&app_id=xxxxxx“ —form “api_version=1” —form “app_id=xxxxxx” —form “app_key=xxxxxx” —form “symbolType=2” —form “bundleId=com.demo.test” —form “productVersion=1.0” —form “fileName=symbol.zip” —form “file=@symbol.zip” —verbose

dSYM文件

什么是dSYM文件？

iOS平台中，dSYM文件是指具有调试信息的目标文件，文件名通常为：xxx.app.dSYM。如下图所示：

为了方便找回Crash对应的dSYM文件和还原堆栈，建议每次构建或者发布APP版本的时候，备份好dSYM文件。

如何定位dSYM文件？

一般情况下，项目编译完dSYM文件跟app文件在同一个目录下，下面以XCode作为IDE详细说明定位dSYM文件。
-> 进入XCode；
-> 打开工程（已编译过）；
-> 在左栏找到“Product”项；
-> 鼠标右键点击编译生成的“xxx.app”；
-> 点击“Show in Finder”；
如下图所示：


如果有多个dSYM文件，可以在使用工具时指定输入为dSYM文件所在的目录或者工程目录。

XCode编译后没有生成dSYM文件？

XCode Release编译默认会生成dSYM文件，而Debug编译默认不会生成，对应的Xcode配置如下：
XCode -> Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
XCode -> Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

开启Bitcode之后需要注意哪些问题？

• 在点“Upload to App Store”上传到App Store服务器的时候需要声明符号文件（dSYM文件）的生成：

• 在配置符号表文件之前，需要从App Store中把该版本对应的dSYM文件下载回本地（参考“如何找回已发布到App Store的App对应的dSYM文件？”），然后用符号表工具生成和上传符号表文件。

• 不需要配置自动生成符号表的脚本了，也不要用本地生成的dSYM文件来生成符号表文件，因为本地编译生成的dSYM文件的符号表信息都被隐藏了。如果用本地编译生成的dSYM文件生成符号表文件并配置到Bugly平台之后，还原出来的结果将是类似于“__hiden#XXX”这样的符号。

  如何判断dSYM文件是否与Crash的UUID匹配？

  Bugly还原Crash堆栈时，需要根据UUID来匹配符号表文件，因此只有上传的符号表文件的UUID与Crash对应APP的UUID一致时，才能准确地对堆栈进行还原。

• 查看符号表文件的UUID（“如何查看dSYM文件的UUID？”）

• 查看Crash对应的APP的UUID

Bugly v1.0页面
崩溃 —-> Crash issue —-> dSYM UUID

Bugly v2.0页面
崩溃分析 —-> Crash issue —-> 符号表 —-> UUID

如何查看dSYM文件的UUID？

通过命令查看UUID

xcrun dwarfdump —uuid

通过符号表文件查看UUID

符号表文件的UUID与dSYM文件的UUID是一致的，因此可以通过符号表工具生成的符号表文件来查看dSYM文件的UUID：
生成符号表文件(.zip) —-> 解压符号表文件(.symbol) —-> 使用文本编辑器打开符号表文件

其中符号表文件的“UUID”信息即Debug SO文件的UUID，亦是符号表文件的UUID，如果文件较大，建议使用“Sublime Text”等文本编辑器来打开符号表文件。

如何找回已发布到App Store的App对应的dSYM文件？

通过Xcode找回

1. 打开 Xcode 顶部菜单栏 -> Window -> Organizer 窗口：
2. 打开 Xcode 顶部菜单栏，选择 Archive 标签：
3. 找到发布的归档包，右键点击对应归档包，选择Show in Finder操作：
4. 右键选择定位到的归档文件，选择显示包内容操作：

5. 选择dSYMs目录，目录内即为下载到的 dSYM 文件：

   通过iTunes Connect找回

6. 登录iTunes Connect；

7. 进入“我的App（My Apps）”的“活动（Activity）”页面：
8. 在“所有构件版本（All Builds）”中选择某一个版本，点“下载dSYM（Download dSYM）”下载dSYM文件：

   通过mdfind工具找回

   在Bugly的issue页面查询到crash对应的UUID：
   然后在Mac的Shell中，用mdfind命令定位dSYM文件：
   mdfind “com_apple_xcode_dsym_uuids == “
   注意，使用mdfind时，UUID需要格式转换（增加“-”）： 12345678-1234-1234-1234-xxxxxxxxxxxx
   例如，要定位的dSYM的UUID为：E30FC309DF7B3C9F8AC57F0F6047D65F 则定位dSYM文件的命令如下：

   mdfind "com_apple_xcode_dsym_uuids == E30FC309-DF7B-3C9F-8AC5-7F0F6047D65F"                                      |12345678-1234-1234-1234-xxxxxxxxxxxx|

   建议每次构建或者发布APP版本的时候，备份App对应的dSYM文件！