CocoaPods - 源码调试环境搭建

曾经终败给现在 2024-05-24 21:44 21阅读 0赞

#### 文章目录 ####

*  前言
 *  开发环境
 *  搭建调试环境
 *  测试调试环境
 *  新的调试工具（推荐）
 *  无法进入调试问题
 *  Ruby自带debug库
 *  最后

--------------------

## 前言 ##

在分析这个问题[Flutter & iOS问题记录 - 多环境配置下Pod库的宏定义失效][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源码][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][vscode-ruby_ Debugger Installation]

1.  在【调试目录】路径下执行`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][]。

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

![screenshot1][]

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

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

![screenshot2][]

对生成的`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][vscode-ruby_ Launching from VS Code]

## 测试调试环境 ##

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

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

接着尝试运行调试：

![screenshot3][]

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

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`][debug]调试Ruby，试了试效果不错，官方出品还是很可靠的。

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

1.  `Gemfile`文件：

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

1.  `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`。

1.  在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源码。

![screenshot4][]

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

## 无法进入调试问题 ##

1.  可能是插件冲突

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

1.  `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版本][RVM - _Ruby]。

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

## 最后 ##

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

--------------------

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

[Flutter _ iOS_ - _Pod]: https://blog.csdn.net/crasowas/article/details/129826345
[CocoaPods]: https://github.com/CocoaPods/CocoaPods/tree/master
[1.12.0]: https://github.com/CocoaPods/CocoaPods/releases/tag/1.12.0
[vscode-ruby_ Debugger Installation]: https://github.com/rubyide/vscode-ruby/wiki/1.-Debugger-Installation
[0.2.4.1 and 0.2.5.beta Fail to build on macOS Catalina 10.15.7]: https://github.com/ruby-debug/debase/issues/91
[Ruby]: https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby
[screenshot1]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/42545f37da1b42869acfec4a390423c3.png
[screenshot2]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/0a6db359cfef42fab5c5927ec016d1df.jpeg
[VSCode Launch.json attributes]: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
[VSCode Variables Reference]: https://code.visualstudio.com/docs/editor/variables-reference
[vscode-ruby_ Launching from VS Code]: https://github.com/rubyide/vscode-ruby/wiki/2.-Launching-from-VS-Code
[screenshot3]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/a6ba2495252445038489899cfd6cf350.jpeg
[Ruby 3.0.2 compatibilty]: https://github.com/ruby-debug/debase/issues/94
[debug]: https://github.com/ruby/debug
[VSCode rdbg Ruby Debugger]: https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg
[screenshot4]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/25e5d1ededea4d53a189149f7bc4c3ca.png
[HOW TO USE]: https://github.com/ruby/debug#how-to-use
[RVM - _Ruby]: https://blog.csdn.net/crasowas/article/details/129826534
[Link 1]: https://github.com/ruby/debug#installation
[crasowas]: https://blog.csdn.net/crasowas