Document Debug CMake build on Apple Silicon

.gitignore

@@ -37,6 +37,7 @@ CTestTestfile.cmake
 /CPackSourceConfig.cmake
 /CPackConfig.cmake
 /cmake-build-debug/
+/build-debug/
 /googletest-download/
 /googletest-src/
 /test/rpc_data/

docs/cn/getting_started.md

@@ -283,6 +283,42 @@ Monterey中openssl的安装位置可能不再位于`/usr/local/opt/openssl`，
 * 先运行`brew link openssl --force`看看`/usr/local/opt/openssl`是否出现了
 * 没有的话可以自行设置软链：`sudo ln -s /opt/homebrew/Cellar/openssl@3/3.0.3 /usr/local/opt/openssl`。请注意此命令中openssl的目录可能随环境变化而变化，可通过`brew info openssl`查看。
 
+### 使用 CMake 编译 Debug 版 brpc
+
+Apple Silicon 可以使用 Homebrew 安装的依赖编译 Debug 版本：
+
+```shell
+cmake -S . -B build-debug -G "Unix Makefiles" \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DDEBUG=ON \
+  -DCMAKE_OSX_ARCHITECTURES=arm64 \
+  -DCMAKE_OSX_SYSROOT="$(xcrun --sdk macosx --show-sdk-path)" \
+  -DCMAKE_PREFIX_PATH="$(brew --prefix)" \
+  -DOPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"
+cmake --build build-debug --parallel
+```
+
+该命令使用单配置的Unix Makefiles生成器，因此`CMAKE_BUILD_TYPE=Debug`会选择
+CMake的Debug构建配置。`DEBUG=ON`启用brpc的调试日志并保留断言。构建产物位于
+`build-debug/output/`。
+
+如需为 clangd 等工具生成编译数据库，请在配置命令中添加以下可选项：
+
+```shell
+-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+生成的编译数据库位于 `build-debug/compile_commands.json`。
+
+如果 CMake 报错 `tapi error: malformed file`，请确认 Command Line Tools 与 Xcode
+版本一致，并选择当前安装的 Xcode：
+
+```shell
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+如果问题仍然存在，请检查`xcrun --sdk macosx --show-sdk-path`返回的SDK路径是否有效。
+
 ### 使用config_brpc.sh编译brpc
 git克隆brpc，进入到项目目录然后运行：
 ```shell

docs/en/getting_started.md

@@ -291,6 +291,45 @@ openssl installed in Monterey may not be found at `/usr/local/opt/openssl`, inst
 * Run `brew link openssl --force` first and check if `/usr/local/opt/openssl` appears.
 * If above command does not work, consider making a soft link using `sudo ln -s /opt/homebrew/Cellar/openssl@3/3.0.3 /usr/local/opt/openssl`. Note that the installed openssl in above command may be put in different places in different environments, which could be revealed by running `brew info openssl`.
 
+### Compile a Debug build with CMake
+
+Apple Silicon can build the Debug configuration against dependencies installed by Homebrew:
+
+```shell
+cmake -S . -B build-debug -G "Unix Makefiles" \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DDEBUG=ON \
+  -DCMAKE_OSX_ARCHITECTURES=arm64 \
+  -DCMAKE_OSX_SYSROOT="$(xcrun --sdk macosx --show-sdk-path)" \
+  -DCMAKE_PREFIX_PATH="$(brew --prefix)" \
+  -DOPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"
+cmake --build build-debug --parallel
+```
+
+The command uses the single-config Unix Makefiles generator, so
+`CMAKE_BUILD_TYPE=Debug` selects CMake's Debug configuration. `DEBUG=ON`
+enables brpc's debug logs and keeps assertions enabled. Build artifacts are
+written to `build-debug/output/`.
+
+To generate a compilation database for tools such as clangd, add the following
+optional argument to the configuration command:
+
+```shell
+-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+```
+
+The compilation database is generated at `build-debug/compile_commands.json`.
+
+If CMake reports `tapi error: malformed file`, make sure the Command Line Tools
+and Xcode versions match, then select the installed Xcode:
+
+```shell
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+If the problem persists, verify that `xcrun --sdk macosx --show-sdk-path` returns
+a valid SDK path.
+
 ### Compile brpc with config_brpc.sh
 git clone brpc, cd into the repo and run
 ```shell