VSCode rdbg Ruby Debugger 0.2.2

新的介绍内容：

VSCode rdbg Ruby Debugger：提升Ruby开发效率的必备工具

VSCode rdbg Ruby Debugger是一款专为Ruby开发者设计的调试工具，利用了Ruby最新调试支持功能。通过与VSCode无缝集成，rdbg为您提供了一个直观且功能强大的调试环境。

安装要求：

要使用rdbg，您需要安装最新的debug gem，并确保rdbg命令位于您的$PATH中。

$ gem install debug

无配置启动调试：

无需任何配置，您只需激活.rb文件并按下"F5"键启动调试。您将看到"Debug command line"输入对话框，在这里输入您希望调试的命令行。

例如：

• ruby foo.rb 启动foo.rb
• ruby foo.rb 10 20 30 带参数启动foo.rb
• rake taskA 启动rake任务taskA
• bundle exec rspec 以bundle exec启动rspec
• bin/rails s 启动bin/rails s

选择命令行后，指定的命令将在rdbg调试器上运行，VSCode将通过UNIX域套接字连接到rdbg调试器。同时会创建一个新的终端（命名为rdbg），您可以在rdbg终端中查看stdout/err输出，并输入stdin。

您可以通过以下方式停止程序：

• 在源代码上设置断点（F9）
• 启用“rescue exception”时通过异常
• 按下暂停按钮（F6）

当程序停止时，您可以查看“调用堆栈”、“变量”，并设置“监视”表达式。在调试控制台中，您可以输入有效的Ruby程序，并在选定的上下文（“调用堆栈”）中获取评估结果。

配置启动调试：

您可以在.vscode/launch.json中编写您喜欢的设置。要创建带有默认设置的.vscode/launch.json文件，只需在“运行和调试”窗格中点击“创建launch.json文件”。您将看到以下默认配置：

{
    // 使用IntelliSense了解可能的属性。
    // 悬停查看现有属性的描述。
    // 有关更多信息，请访问：https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "rdbg",
            "name": "使用rdbg调试当前文件",
            "request": "launch",
            "script": "${file}",
            "args": [],
            "askParameters": true
        },
        {
            "type": "rdbg",
            "name": "附加到rdbg",
            "request": "attach"
        }
    ]
}

它包含“使用rdbg调试当前文件”（launch）配置和“附加到rdbg”（attach）配置。您可以修改此配置，也可以添加您喜欢的配置，例如：

        {
            "type": "rdbg",
            "name": "运行rake test",
            "request": "launch",
            "command": "rake",
            "script": "test", // 以调试器启动rake test
            "args": [],
            "askParameters": false // 不再询问启动参数
        },

您可以使用以下“launch”配置：

• 调试目标设置

  • script：目标脚本文件名。默认值为VSCode中活动的Ruby文件。
  • command：可执行的Ruby命令。例如，可以指定bundle exec ruby。默认值为ruby。
  • cwd：执行程序的目录。默认值为${workspaceFolder}。
  • args：传递给程序的命令行参数。默认值为[]。
  • env：传递给调试（和被调试）进程的附加环境变量。默认值为N/A。
  • useBundler：如果未给出命令配置且工作区中有Gemfile，则使用bundle exec执行Ruby程序。请注意，您可以通过扩展配置指定此useBundler（默认值为true）。默认值为未定义（扩展配置默认值为true）。

• 行为设置

  • askParameters：在调试前询问“调试命令行”。如果主程序始终相同，请将其设置为false。请注意，最后调用的命令会被记住。默认值为true。
  • rdbgPath：rdbg可执行文件的位置。请注意，您可以通过扩展配置指定此rdbgPath（默认值为rdbg）。默认值为rdbg。
  • debugPort：如果没有debugPort配置，将打开UNIX域套接字（或在Windows上打开TCP/IP localhost:0）与被调试程序通信。如果您想使用其他调试端口，请设置此配置。
    • 数字（例如12345）：以端口12345打开TCP/IP调试端口
    • 主机名:端口（例如hostname:12345）：以端口12345和主机名hostname打开TCP/IP端口
    • 否则，以此配置给出的文件名打开UNIX域套接字
  • waitLaunchTime：如果您要打开TCP/IP调试端口，您可能需要等待调试端口打开。默认情况下，它等待5000毫秒（5秒），但如果不够，请指定更长的等待时间（默认值为5000毫秒）。
  • useTerminal：如果配置为true，则创建一个新终端，然后在那里执行调试命令行。这会稍微慢一些。否则，STDIN/OUT的所有输出将显示在DEBUG CONSOLE中。如果您需要使用STDIN，请设置此选项。默认值为false。
  • showProtocolLog：在“rdbg”输出中打印所有DAP通信日志。这是为开发此扩展准备的。默认值为false。

请注意，如果启动rdbg时遇到问题，请尝试指定rdbgPath。没有此配置，此扩展将简单地在PATH中调用rdbg。

附加到运行中的Ruby进程：

您可以附加到以打开调试端口运行的Ruby进程。

以下命令以打开调试端口启动foo.rb。有更多方法可以打开端口。请参阅更多关于ruby/debug的信息：Ruby的调试功能。

# 使用rdbg命令
$ rdbg --open foo.rb              # 打开调试端口。-O是--open的缩写
$ rdbg -n -O foo.rb               # 不停留在应用程序开始处
$ rdbg -O -c -- bundle exec rspec # 以远程方式运行rspec

# 使用debug/open库
$ ruby -r debug/open foo.rb
$ ruby -r debug/open_nonstop foo.rb # 不停留在应用程序开始处

# 如果您的应用程序明确要求debug/open（或debug/open_nonstop），当然-r是不需要的。
$ ruby foo.rb

# 使用debug库与RUBY_DEBUG_OPEN
$ RUBY_DEBUG_OPEN=true ruby -r debug foo.rb

# 如果您的应用程序明确要求debug，当然-r是不需要的。
$ RUBY_DEBUG_OPEN=true ruby foo.rb

# 如果您的Gemfile中有`gem 'debug'`行与Rails一起使用，您只需使用`RUBY_DEBUG_OPEN`环境变量启动它。
$ RUBY_DEBUG_OPEN=true rails server

之后，您可以连接到调试端口。此扩展会搜索打开的调试端口并附加到该端口，通过运行“附加到rdbg”（在“运行和调试”窗格顶部选择它，然后按下绿色的“开始调试”按钮）来实现。

您可以指定以下“attach”配置：

• rdbgPath：与launch请求相同。
• debugPort：与launch请求相同。
• localfs：在TCP/IP上，如果目标主机是本地机器，设置为true，您可以直接打开文件。默认值为false。
• localfsMap：指定远程根路径和本地根路径的对，如/remote_dir:/local_dir，如果本地和远程计算机共享相同的源代码存储库。您可以通过,连接多个对，如/rem1:/loc1,/rem2:/loc2。默认值为未定义。

没有debugPort配置，

使用debugPort，您可以附加到TCP/IP调试端口。

• 以debug.gem配置启动带有TCP/IP调试端口的调试命令。
  • 使用rdbg命令，如：rdbg --open --port 12345 foo.rb
  • 使用debug/open库：RUBY_DEBUG_PORT=12345 ruby -r debug/open foo.rb
  • 使用debug库与RUBY_DEBUG_OPEN环境变量：RUBY_DEBUG_OPEN=true RUBY_DEBUG_PORT=12345 ruby -r debug foo.rb
• 在VSCode（调试器端）：
  • 添加debugPort: '12345'附加配置。
  • 选择“附加到rdbg”并开始附加调试

localfsMap在您运行调试器并与调试器共享相同文件系统但名称不同时非常有用。

例如，使用-v选项（和--network=host以与主机和docker容器通信）运行docker容器：

$ docker run --network=host -it -v `pwd`:/app/ --rm ruby bash
/:# cd app
/app:# rdbg -O --port=12345 target.rb

在这种情况下，主机的当前目录（${workspaceFolder}）以/app的名称与容器共享，主机上的VSCode可以通过TCP/IP端口12345连接到容器中的调试器进程。launch.json配置应为：

        {
            "type": "rdbg",
            "name": "附加到rdbg（tcp 12345）", // 指定您喜欢的名称
            "request": "attach",
            "debugPort": "localhost:12345",
            "localfsMap": "/app:${workspaceFolder}"
        }

选择版本管理器：

为了使用正确的Ruby版本启动调试器，rdbg允许您配置您喜欢的版本管理器，用于通过扩展设置（或settings.json）激活Ruby环境。

// 默认值为"none"，表示不使用版本管理器激活环境
// 可用的管理器有shadowenv、chruby、asdf、rbenv和rvm

{
  // 用户设置
  "rdbg.rubyVersionManager": "none"
}

如果您使用rbenv配置了登录shell（在bash或zsh上），您不需要指定此配置，因为vscode-rdbg将以登录shell设置（如bash -lic ruby ...）启动ruby命令。使用此配置，vscode-rdbg将简单地启动ruby命令。此配置在您使用其他环境如chruby等时会很有用。

致谢：

• 此扩展基于Ethan Reesor / VSCode Byebug · GitLab由Ethan Reesor开发。没有他的出色工作，此扩展无法发布（Koichi通过他的扩展学习了TypeScript、VSCode扩展和DAP）。
• 图标由@firien提供（https://github.com/ruby/vscode-rdbg/pull/74）。