CocoaPods - 源码调试环境搭建

---

前言

在分析这个问题Flutter & iOS问题记录 - 多环境配置下Pod库的宏定义失效时，需要调试CocoaPods源码，于是尝试搭建调试环境。没想到搭建过程中报错一个接一个，于是就有了这篇文章，希望对你有所帮助。

开发环境

• RVM: 1.29.12
• Ruby: 3.0.0p0
• CocoaPods: 1.12.0
• VSCode: 1.76.1

搭建调试环境

因为我已经安装了VSCode，所以首选它来调试，当然RubyMine也是可以的。基于VSCode搭建调试环境的流程如下：

1. 下载CocoaPods源码到本地，为了和电脑上已安装的版本保持一致，我选择下载1.12.0版本。注意：如果你想直接调试电脑上已经安装的版本，这一步可以略过，个人不推荐直接调试已安装版本
2. 新建一个用于调试的目录，将下载的CocoaPods源码解压后放到这个目录（如果有下载），同时也新建一个Xcode项目放到这个目录并执行pod init命令生成Podfile文件
3. 在【调试目录】路径下执行bundle init命令生成Gemfile文件，接着在Gemfile文件里加入依赖项：

# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

# 如果要调试下载的指定版本，请使用这个。path需要根据实际填写
gem 'cocoapods', path: './CocoaPods-1.12.0'
# 如果要直接调试电脑上已安装的版本，请使用这个并注释上面👆的
# gem 'cocoapods'
# 调试需要依赖的库
gem 'ruby-debug-ide'
gem 'debase'

# gem "rails"

参考文档：

• vscode-ruby: Debugger Installation

4. 在【调试目录】路径下执行bundle install命令安装依赖项，会自动生成Gemfile.lock文件

安装过程中可能会遇到以下报错：

Could not fetch specs from https://rubygems.org/ due to underlying error
<Errno::ECONNRESET: Connection reset by peer - SSL_connect
(https://rubygems.org/specs.4.8.gz)>

解决方法：请尝试设置代理。

An error occurred while installing debase (0.2.4.1), and Bundler cannot
continue.

解决方法：先执行gem install debase -- --with-cflags="-Wno-error=implicit-function-declaration"命令安装debase，然后重新执行bundle install命令。
参考：0.2.4.1 and 0.2.5.beta Fail to build on macOS Catalina 10.15.7。

5. 使用VSCode打开【调试目录】，在配置调试之前要先安装用于支持调试的扩展Ruby:

2023/10/11更新：该扩展已弃用，请直接往下阅读，然后使用新的调试工具搭建调试环境。

安装完成后，切到调试页面，点击[create a launch.json file]，在弹框中选择[Ruby] -> [Debug Local File]，完成这些操作后会自动生成.vscode目录及launch.json文件。

对生成的launch.json做一些配置：

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      // 调试名称（可以随意改）
      "name": "Debug CocoaPods",
      // 调试器类型
      "type": "Ruby",
      // 请求类型
      "request": "launch",
      // 调试时要执行的程序/文件
      // ${workspaceRoot}表示当前打开的文件夹路径，已弃用（自动生成的配置不知道为啥还用），VSCode推荐使用${workspaceFolder}
      "program": "${workspaceRoot}/CocoaPods-1.12.0/bin/pod",
      // 如果要直接调试电脑上已安装的版本，请使用这个（可以通过执行[which pod]命令获得路径）并注释上面👆的
      // "program": "/Users/xxx/.rvm/gems/ruby-3.0.0/bin/pod",
      // 调试参数
      "args": ["install"],
      // 工作目录，设置为Xcode项目路径
      "cwd": "${workspaceRoot}/app",
    }
  ]
}

参考文档：

• VSCode Launch.json attributes
• VSCode Variables Reference
• vscode-ruby: Launching from VS Code

测试调试环境

搭建完成后，【调试目录】的目录结构如下：

├── CocoaPods-1.12.0
├── Gemfile
├── Gemfile.lock
└── app

app目录存放的是新建的Xcode项目。使用VSCode打开【调试目录】找到Xcode项目下的Podfile文件，随意添加一些断点。

接着尝试运行调试：

没想到报错了，报错提示：

Uncaught exception: https://github.com/CocoaPods/CLAide.git (at master@97b765e) is not yet checked out. Run `bundle install` first.

解决方法：在launch.json的配置里加上"useBundler": true,。

再次运行，报了另一个错：

symbol not found in flat namespace '_RHASH_EMPTY_P'

这个报错没找到好的解决办法。太难了，我只是想简简单单调试，问题也太多了吧。整个搭建流程走下来，我算是明白了，这套调试工具和Ruby 3.0的兼容性有问题，不过，好在还有其他新的调试工具可以用。

新的调试工具（推荐）

查找问题解决办法的过程中，看到了这个Ruby 3.0.2 compatibilty，这里面提到了用debug调试Ruby，试了试效果不错，官方出品还是很可靠的。

使用新的调试工具前，需要对前面的配置进行一些改动。

1. Gemfile文件：

# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

# 如果要调试下载的指定版本，请使用这个。path需要根据实际填写
gem 'cocoapods', path: './CocoaPods-1.12.0'
# 如果要直接调试电脑上已安装的版本，请使用这个并注释上面👆的
# gem 'cocoapods'
# 调试需要依赖的库
gem 'debug'

# gem "rails"

调试需要依赖的库改为debug，修改后重新执行bundle install命令安装依赖项。

2. launch.json文件：

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            // 调试名称（可以随意改）
            "name": "Debug CocoaPods",
            // 调试器类型
            "type": "rdbg",
            // 请求类型
            "request": "launch",
            // 调试时要执行的程序/文件
            // ${workspaceRoot}表示当前打开的文件夹路径，已弃用（自动生成的配置不知道为啥还用），VSCode推荐使用${workspaceFolder}，参考文档：https://code.visualstudio.com/docs/editor/variables-reference
            "script": "${workspaceRoot}/CocoaPods-1.12.0/bin/pod",
            // 如果要直接调试电脑上已安装的版本，请使用这个（可以通过执行[which pod]命令获得路径）并注释上面👆的
            // "script": "/Users/xxx/.rvm/gems/ruby-3.0.0/bin/pod",
            // 调试参数
            "args": ["install"],
            // 工作目录，设置为Xcode项目路径
            "cwd": "${workspaceRoot}/app",
        }
    ]
}

调试器类型改为rdbg，program改为script。

3. 在VSCode中安装VSCode rdbg Ruby Debugger扩展。

参考文档：

• VSCode rdbg Ruby Debugger

准确工作已经就绪，重新运行调试，报了新错误：

Unicode Normalization not appropriate for ASCII-8BIT (Encoding::CompatibilityError)

解决方法：在~/.bash_profile或~/.zshrc文件里面加上export LANG=en_US.UTF-8解决。如果添加后运行调试还报错，请完全退出VSCode后再重新打开运行调试。如果还是不行，请改为添加export LC_ALL=en_US.UTF-8。

一般来说，到这里应该就可以正常调试CocoaPods源码。

如果不想使用VSCode调试，想直接在命令行工具中调试，请参考debug开源项目中的HOW TO USE。

无法进入调试问题

1. 可能是插件冲突

卸载之前安装的Ruby扩展后重启VSCode。

2. Bundler版本问题

执行bundle install时提示：

Warning: the running version of Bundler (2.2.3) is older than the version that created the lockfile (2.2.32). We suggest you to upgrade to the version that created the lockfile by running `gem install bundler:2.2.32`.

按照提示执行命令升级版本：

gem install bundler:2.2.32

升级完成后重新执行bundle install命令，重新调试，成功进入调试。

Ruby自带debug库

在Ruby 3.0.2 compatibilty这个issue中有人提到Ruby 3.1版本中会捆绑debug库，那不就意味着如果Ruby版本>=3.1就不需要在Gemfile文件中加入gem 'debug'。

如果你不知道怎么通过RVM安装Ruby 3.0以上版本，可以参考这篇文章RVM - 安装最新Ruby版本。

实测Ruby 3.1.0版本自带debug 1.4.0版本，Gemfile文件中不依赖debug也能正常调试，对于大于3.1.0版本的就更不需要依赖。Ruby 3.0.0版本虽然也自带有debug 0.1.0版本，但会因为版本过低无法正常调试，debug开源项目的安装说明也明确要求版本>=1.0.0。

最后

如果这篇文章对你有所帮助，点赞👍收藏🌟支持一下吧，谢谢～

---

本篇文章由@crasowas发布于CSDN。