Skip to content

Commit 2634dcb

Browse files
CopilotCopilot
authored
feat(build): enable dSYM debugging information generation for macOS Debug builds (#383)
1 parent e63d8e0 commit 2634dcb

File tree

5 files changed

+777
-0
lines changed

5 files changed

+777
-0
lines changed

‎.vscode/launch.json‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Debug transmute_browser",
6+
"type": "lldb",
7+
"request": "launch",
8+
"program": "${workspaceFolder}/build/output/release/universal-apple-darwin/transmute_browser",
9+
"args": [
10+
"${workspaceFolder}/fixtures/html/document.html"
11+
],
12+
"cwd": "${workspaceFolder}",
13+
"preLaunchTask": null,
14+
"sourceMap": {},
15+
"initCommands": [
16+
"settings set target.load-script-from-symbol-file true"
17+
],
18+
"postRunCommands": [
19+
"target symbols add ${workspaceFolder}/build/output/release/universal-apple-darwin/transmute_browser.dSYM"
20+
]
21+
},
22+
{
23+
"name": "Debug transmute_browser (Custom HTML)",
24+
"type": "lldb",
25+
"request": "launch",
26+
"program": "${workspaceFolder}/build/output/release/universal-apple-darwin/transmute_browser",
27+
"args": [
28+
"${input:htmlFile}"
29+
],
30+
"cwd": "${workspaceFolder}",
31+
"preLaunchTask": null,
32+
"sourceMap": {},
33+
"initCommands": [
34+
"settings set target.load-script-from-symbol-file true"
35+
],
36+
"postRunCommands": [
37+
"target symbols add ${workspaceFolder}/build/output/release/universal-apple-darwin/transmute_browser.dSYM"
38+
]
39+
},
40+
{
41+
"name": "Debug TransmuteClient",
42+
"type": "lldb",
43+
"request": "launch",
44+
"program": "${workspaceFolder}/build/output/release/universal-apple-darwin/TransmuteClient",
45+
"args": [],
46+
"cwd": "${workspaceFolder}",
47+
"preLaunchTask": null,
48+
"sourceMap": {},
49+
"initCommands": [
50+
"settings set target.load-script-from-symbol-file true"
51+
],
52+
"postRunCommands": [
53+
"target symbols add ${workspaceFolder}/build/output/release/universal-apple-darwin/TransmuteClient.dSYM"
54+
]
55+
},
56+
{
57+
"name": "Attach to Process",
58+
"type": "lldb",
59+
"request": "attach",
60+
"pid": "${command:pickProcess}",
61+
"initCommands": [
62+
"settings set target.load-script-from-symbol-file true"
63+
]
64+
}
65+
],
66+
"inputs": [
67+
{
68+
"id": "htmlFile",
69+
"type": "promptString",
70+
"description": "Path to HTML file to load",
71+
"default": "${workspaceFolder}/fixtures/html/document.html"
72+
}
73+
]
74+
}

‎cmake/TransmuteCXXFlags.cmake‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,8 +154,13 @@ if (APPLE)
154154
# FIXME: (penguinliong) Workaround the overwhelming truncation errors
155155
# compiling to iOS.
156156
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-shorten-64-to-32")
157+
# Generate dSYM files for debugging in Xcode
158+
set(CMAKE_XCODE_ATTRIBUTE_DEBUG_INFORMATION_FORMAT "dwarf-with-dsym")
157159
endif()
158160

161+
# Add debug symbols for Debug builds on macOS
162+
set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -fno-limit-debug-info")
163+
159164
# Set the -mmacosx-version-min flag to the minimum supported version of macOS.
160165
# This is required to ensure that the resulting dylib is compatible with older macOS versions.
161166
set(CMAKE_OSX_DEPLOYMENT_TARGET "11" CACHE STRING "Minimum macOS version to target")

‎cmake/TransmuteCommon.cmake‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,22 @@ function(tr_install_nodejs)
165165
endif()
166166
endfunction()
167167

168+
# Function to generate dSYM bundles for Debug builds on macOS
169+
function(tr_target_generate_dsym TARGET)
170+
if (APPLE AND CMAKE_BUILD_TYPE STREQUAL "Debug")
171+
# Use dsymutil to generate dSYM bundle after build
172+
add_custom_command(TARGET ${TARGET} POST_BUILD
173+
COMMAND dsymutil $<TARGET_FILE:${TARGET}> -o $<TARGET_FILE:${TARGET}>.dSYM
174+
COMMENT "Generating dSYM bundle for ${TARGET}"
175+
VERBATIM
176+
)
177+
# Install the dSYM bundle alongside the binary
178+
install(DIRECTORY $<TARGET_FILE:${TARGET}>.dSYM
179+
DESTINATION ${TR_RELEASE_DEST}
180+
OPTIONAL)
181+
endif()
182+
endfunction()
183+
168184
# Function to set properties
169185
function(tr_target_set_properties TARGET)
170186
if (APPLE)
@@ -181,6 +197,8 @@ function(tr_target_set_properties TARGET)
181197
INSTALL_RPATH "${APPLE_TARGET_INSTALL_RPATH}"
182198
BUILD_WITH_INSTALL_RPATH TRUE
183199
)
200+
# Generate dSYM bundles for Debug builds
201+
tr_target_generate_dsym(${TARGET})
184202
elseif (ANDROID)
185203
cmake_parse_arguments(ANDROID_ARG "USE_EXECUTABLE_PATH" "" "" ${ARGN})
186204
if (ANDROID_ARG_USE_EXECUTABLE_PATH)

‎docs/development-zh.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,164 @@
1010
$ make darwin CLEAN=yes
1111
```
1212

13+
#### 使用调试符号编译
14+
15+
如需生成带有 dSYM 调试信息的构建,可以使用 Debug 模式:
16+
17+
```sh
18+
$ make darwin CLEAN=yes RELEASE=no
19+
```
20+
21+
这将生成:
22+
- 编译时使用 `-g -fno-limit-debug-info` 标志以包含完整的调试信息
23+
- 为每个目标自动生成 `.dSYM` 调试包
24+
- dSYM 文件将被安装到输出目录中,与二进制文件一起
25+
26+
生成的 dSYM 文件可以用于:
27+
- 使用 `lldb` 进行源码级调试
28+
- 崩溃日志符号化
29+
- 性能分析工具
30+
31+
#### 使用 lldb 调试
32+
33+
在使用调试符号编译后，按照以下步骤使用 lldb 进行调试：
34+
35+
**1. 启动 lldb 并加载二进制文件：**
36+
37+
```sh
38+
$ lldb ./build/output/release/universal-apple-darwin/transmute_browser
39+
```
40+
41+
**2. 加载 dSYM 文件（如果未自动检测到）：**
42+
43+
通常情况下，如果 dSYM 文件与二进制文件在同一目录中，lldb 会自动加载。要验证或手动加载：
44+
45+
```sh
46+
# 检查调试符号是否已加载
47+
(lldb) image list transmute_browser
48+
49+
# 如果调试符号未显示，手动添加 dSYM 包
50+
(lldb) target symbols add ./build/output/release/universal-apple-darwin/transmute_browser.dSYM
51+
```
52+
53+
**3. 设置断点：**
54+
55+
```sh
56+
# 按函数名设置断点
57+
(lldb) breakpoint set --name main
58+
(lldb) b main
59+
60+
# 在特定文件和行号设置断点
61+
(lldb) breakpoint set --file main.cpp --line 42
62+
(lldb) b main.cpp:42
63+
64+
# 列出所有断点
65+
(lldb) breakpoint list
66+
```
67+
68+
**4. 运行程序：**
69+
70+
```sh
71+
# 带参数运行
72+
(lldb) run /path/to/test.html
73+
74+
# 或使用简写 'r'
75+
(lldb) r /path/to/test.html
76+
```
77+
78+
**5. 调试命令：**
79+
80+
```sh
81+
# 继续执行
82+
(lldb) continue
83+
(lldb) c
84+
85+
# 单步跳过（执行当前行）
86+
(lldb) next
87+
(lldb) n
88+
89+
# 单步进入（进入函数调用）
90+
(lldb) step
91+
(lldb) s
92+
93+
# 单步跳出（完成当前函数）
94+
(lldb) finish
95+
96+
# 打印回溯（堆栈跟踪）
97+
(lldb) backtrace
98+
(lldb) bt
99+
100+
# 打印变量值
101+
(lldb) print variable_name
102+
(lldb) p variable_name
103+
104+
# 打印帧变量
105+
(lldb) frame variable
106+
107+
# 检查内存
108+
(lldb) memory read 0x12345678
109+
(lldb) x 0x12345678
110+
```
111+
112+
**6. 调试崩溃：**
113+
114+
如果程序崩溃，lldb 会在崩溃点停止：
115+
116+
```sh
117+
# 查看崩溃位置
118+
(lldb) bt
119+
120+
# 移动到特定帧
121+
(lldb) frame select 2
122+
(lldb) f 2
123+
124+
# 查看局部变量
125+
(lldb) frame variable
126+
127+
# 查看崩溃点的源代码
128+
(lldb) source list
129+
```
130+
131+
**7. 高级调试：**
132+
133+
```sh
134+
# 附加到运行中的进程
135+
$ lldb -p <pid>
136+
137+
# 或从 lldb 内部附加
138+
(lldb) process attach --pid <pid>
139+
140+
# 设置条件断点
141+
(lldb) breakpoint set --name foo --condition 'x > 10'
142+
143+
# 在变量上设置观察点
144+
(lldb) watchpoint set variable my_var
145+
146+
# 查看所有加载的模块
147+
(lldb) image list
148+
```
149+
150+
**8. 使用 VSCode 调试：**
151+
152+
项目在 `.vscode/launch.json` 中提供了 VSCode 启动配置，方便进行调试。使用方法：
153+
154+
1. **在 VSCode 中安装 CodeLLDB 扩展**（macOS 上使用 lldb 调试所必需）
155+
156+
2. **使用调试符号编译：**
157+
```sh
158+
$ make darwin CLEAN=yes RELEASE=no
159+
```
160+
161+
3. **在 VSCode 中打开项目**，然后选择可用的调试配置之一：
162+
- **Debug transmute_browser**：使用 `fixtures/html/document.html` 启动 transmute_browser
163+
- **Debug transmute_browser (Custom HTML)**：提示输入自定义 HTML 文件路径
164+
- **Debug TransmuteClient**：启动 TransmuteClient
165+
- **Attach to Process**：附加到运行中的进程
166+
167+
4. **开始调试**：按 `F5` 或使用调试面板开始调试
168+
169+
启动配置会自动加载 dSYM 文件并设置调试器以获得最佳调试体验。
170+
13171
### Android
14172
15173
编译 Android 平台需要下载 NDK，下载完成后，新开一个终端配置参数：

0 commit comments

Comments
 (0)