debug 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a62295065b9bb4f9d498a21b32ea122ab680fd1e1b9794368ac2385858abf844
-  data.tar.gz: 0dc6f9aeb1ff23a47e0c399ee32ac80953821520cc52b0c4e27e30d7600a67bd
+  metadata.gz: 121cdb1003971d234dbeb40878f693d06053fa32f28024c5d2a7c0e0fd6d3719
+  data.tar.gz: fd95c68d4bf99b38a83cef1a6851680bb9abb65d39fa9fc69a94d248295a5829
 SHA512:
-  metadata.gz: 144d16fc2b8e377d7d25df0b09f088492647b76de2ffc1a841e09967caed2678f28fbaf24747fc351fd7e7d7c0d107cd39245ca0c8eff41547bce4f2ab35a8c3
-  data.tar.gz: 4e62e36b0fe72a2c1ce8e1dd44e6bae646e06b0d4d8d07072db595f908d00595252e35525a9ba1fde09a53f9a57781165c73e63d8eaa8a59a5e93219bd4c9ed5
+  metadata.gz: 4354a11670db6e0fd49e4b8151b268a08c7843c80ccd36b5c492cf5fabc7b42c6632939905b9912c81434f5513e36dac8378686b5d47c274248c523eea88a0c8
+  data.tar.gz: e22274473f567bed800c25d46a46d32adf263f070e8147cd71778ef9cbd95b8e239e2912b226892f032266a92322045a62e7f9c908f176e601a984e254acd2a7

data/CONTRIBUTING.md

@@ -249,6 +249,130 @@ Passes if `text` is not included in the last debugger log.
 
 Passes if `text` is included in the debuggee log.
 
+### Tests for DAP and CDP
+
+Currently, there are 2 kinds of test frameworks for DAP and CDP.
+
+1. Protocol-based tests
+
+If you want to write protocol-based tests, you should use the test generator.
+To run the test generator, you can enter `$ bin/gentest target.rb --open=vscode` in the terminal, VSCode will be executed.
+Also, if you enter ``$ bin/gentest target.rb --open=chrome` there, Chrome will be executed.
+If you need to modify existing tests, it is basically a good idea to regenerate them by the test generator instead of rewriting them directly.
+Please refer to [the Microsoft "Debug Adapter Protocol" article](https://microsoft.github.io/debug-adapter-protocol/specification) to learn more about DAP formats.
+Please refer to [Procol viewer for "Chrome DevTools Protocol"](https://chromedevtools.github.io/devtools-protocol/) to learn more about CDP formats.
+
+2. High-level tests
+
+High-level tests are designed to test both DAP and CDP for a single method.
+You can write tests as follows:
+**NOTE:** Use `req_terminate_debuggee` to finish debugging. You can't use any methods such as `req_continue`, `req_next` and so on.
+
+```ruby
+require_relative '../support/test_case'
+module DEBUGGER__
+  class BreakTest < TestCase
+    # PROGRAM is the target script.
+    PROGRAM = <<~RUBY
+      1| module Foo
+      2|   class Bar
+      3|     def self.a
+      4|       "hello"
+      5|     end
+      6|   end
+      7|   Bar.a
+      8|   bar = Bar.new
+      9| end
+    RUBY
+
+    def test_break1
+      run_protocol_scenario PROGRAM do # Start debugging with DAP and CDP
+        req_add_breakpoint 5 # Set a breakpoint on line 5.
+        req_add_breakpoint 8 # Set a breakpoint on line 8.
+        req_continue # Resume the program.
+        assert_line_num 5 # Check if debugger stops at line 5.
+        req_continue # Resume the program.
+        assert_line_num 8 # Check if debugger stops at line 8.
+        req_terminate_debuggee # Terminate debugging.
+      end
+    end
+  end
+end
+```
+
+#### API
+
+- run_protocol_scenario program, dap: true, cdp: true, &scenario
+
+Execute debugging `program` with `&scenario`. If you want to test it only for DAP, you can write as follows:
+
+`run_protocol_scenario program, cdp: false ...`
+
+- req_add_breakpoint(lineno, path: temp_file_path, cond: nil)
+
+Sends request to rdbg to add a breakpoint.
+
+- req_delete_breakpoint bpnum
+
+Sends request to rdbg to delete a breakpoint.
+
+- req_set_exception_breakpoints
+
+Sends request to rdbg to set exception breakpoints.
+
+- req_continue
+
+Sends request to rdbg to resume the program.
+
+- req_step
+
+Sends request to rdbg to step into next method.
+
+- req_next
+
+Sends request to rdbg to step over next method.
+
+- req_finish
+
+Sends request to rdbg to step out of current method.
+
+- req_step_back
+
+Sends request to rdbg to step back from current method.
+
+- req_terminate_debuggee
+
+Sends request to rdbg to terminate the debuggee.
+
+- assert_reattach
+
+Passes if reattaching to rdbg is successful.
+
+- assert_hover_result(expected, expression: nil)
+
+Passes if result of `expression` is equal to `expected`.
+
+- assert_repl_result(expected, expression: nil)
+
+Passes if result of `expression` is equal to `expected`.
+
+- assert_watch_result(expected, expression: nil)
+
+Passes if result of `expression` is equal to `expected`.
+
+- assert_line_num(expected)
+
+Passes if `expected` is equal to the location where debugger stops.
+
+- assert_locals_result(expected)
+
+Passes if all of `expected` local variable entries match the ones returned by debugger.
+
+An variable entry looks like this: `{ name: "bar", value: "nil", type: "NilClass" }`.
+
+Please note that both `value` and `type` need to be strings.
+
+
 ## To Update README
 
 This project generates `README.md` from the template `misc/README.md.erb`

data/Gemfile

@@ -6,3 +6,4 @@ gem "rake"
 gem "rake-compiler"
 gem "test-unit", "~> 3.0"
 gem "test-unit-rr"
+gem "json-schema"

data/README.md

@@ -1,8 +1,8 @@
-[![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster)
+[![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster) [![Protocol](https://github.com/ruby/debug/actions/workflows/protocol.yml/badge.svg)](https://github.com/ruby/debug/actions/workflows/protocol.yml)
 
 # debug.rb
 
-This library provides debugging functionality to Ruby.
+This library provides debugging functionality to Ruby (MRI) 2.6 and later.
 
 This debug.rb is replacement of traditional lib/debug.rb standard library which is implemented by `set_trace_func`.
 New debug.rb has several advantages:
@@ -113,7 +113,7 @@ d => nil
       5| binding.break
       6| c = 3
       7| d = 4
-=>    8| binding.break                 # Again the program stops at here
+=>    8| binding.break                 # Again the program stops here
       9| p [a, b, c, d]
      10|
      11| __END__
@@ -358,6 +358,8 @@ Also `open` command allows opening the debug port.
 
 #### VSCode integration
 
+([vscode-rdbg v0.0.9](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) or later is required)
+
 If you don't run a debuggee Ruby process on VSCode, you can attach with VSCode later with the following steps.
 
 `rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
@@ -417,7 +419,7 @@ Note that you can attach with `rdbg --attach` and continue REPL debugging.
 
 #### Chrome DevTool integration
 
-With `rdbg --open=chrome` command will shows the following message.
+With `rdbg --open=chrome` command will show the following message.
 
 ```
 $ rdbg target.rb --open=chrome
@@ -435,8 +437,6 @@ Also `open chrome` command works like `open vscode`.
 
 For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
 
-Note: If you want to maximize Chrome DevTools, click [Toggle Device Toolbar](https://developer.chrome.com/docs/devtools/device-mode/#viewport).
-
 ## Configuration
 
 You can configure the debugger's behavior with debug commands and environment variables.
@@ -567,8 +567,8 @@ The `<...>` notation means the argument.
   * break and run `<command>` before stopping.
 * `b[reak] ... do: <command>`
   * break and run `<command>`, and continue.
-* `b[reak] ... path: <path_regexp>`
-  * break if the triggering event's path matches <path_regexp>.
+* `b[reak] ... path: <path>`
+  * break if the path matches to `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `b[reak] if: <expr>`
   * break if: `<expr>` is true at any lines.
   * Note that this feature is super slow.
@@ -580,8 +580,8 @@ The `<...>` notation means the argument.
   * runs `<command>` before stopping.
 * `catch ... do: <command>`
   * stops and run `<command>`, and continue.
-* `catch ... path: <path_regexp>`
-  * stops if the exception is raised from a path that matches <path_regexp>.
+* `catch ... path: <path>`
+  * stops if the exception is raised from a `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `watch @ivar`
   * Stop the execution when the result of current scope's `@ivar` is changed.
   * Note that this feature is super slow.
@@ -591,8 +591,8 @@ The `<...>` notation means the argument.
   * runs `<command>` before stopping.
 * `watch ... do: <command>`
   * stops and run `<command>`, and continue.
-* `watch ... path: <path_regexp>`
-  * stops if the triggering event's path matches <path_regexp>.
+* `watch ... path: <path>`
+  * stops if the path matches `<path>`. `<path>` can be a regexp with `/regexp/`.
 * `del[ete]`
   * delete all breakpoints.
 * `del[ete] <bpnum>`
@@ -631,8 +631,8 @@ The `<...>` notation means the argument.
   * Show information about accessible constants except toplevel constants.
 * `i[nfo] g[lobal[s]]`
   * Show information about global variables
-* `i[nfo] ... </pattern/>`
-  * Filter the output with `</pattern/>`.
+* `i[nfo] ... /regexp/`
+  * Filter the output with `/regexp/`.
 * `i[nfo] th[read[s]]`
   * Show all threads (same as `th[read]`).
 * `o[utline]` or `ls`
@@ -683,8 +683,8 @@ The `<...>` notation means the argument.
   * Add an exception tracer. It indicates raising exceptions.
 * `trace object <expr>`
   * Add an object tracer. It indicates that an object by `<expr>` is passed as a parameter or a receiver on method call.
-* `trace ... </pattern/>`
-  * Indicates only matched events to `</pattern/>` (RegExp).
+* `trace ... /regexp/`
+  * Indicates only matched events to `/regexp/`.
 * `trace ... into: <file>`
   * Save trace information into: `<file>`.
 * `trace off <num>`

data/Rakefile

@@ -2,8 +2,6 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
@@ -17,7 +15,6 @@ begin
 rescue LoadError
 end
 
-
 task :default => [:clobber, :compile, 'README.md', :test]
 
 file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
@@ -28,7 +25,10 @@ file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
   puts 'README.md is updated.'
 end
 
-task :run => :compile do
-  system(RbConfig.ruby, *%w(-I ./lib test.rb))
+task :test_protocol do
+  ENV['RUBY_DEBUG_PROTOCOL_TEST'] = '1'
 end
 
+Rake::TestTask.new(:test_protocol) do |t|
+  t.test_files = FileList["test/protocol/*_test.rb"]
+end

data/debug.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["ko1@atdot.net"]
 
   spec.summary       = %q{Debugging functionality for Ruby}
-  spec.description   = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the encient Ruby versions.}
+  spec.description   = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the ancient Ruby versions.}
   spec.homepage      = "https://github.com/ruby/debug"
   spec.licenses      = ["Ruby", "BSD-2-Clause"]
   spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
@@ -17,11 +17,13 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
   end
   spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions    = ['ext/debug/extconf.rb']
 

data/ext/debug/debug.c

@@ -118,11 +118,82 @@ create_method_added_tracker(VALUE self)
     return rb_tracepoint_new(0, RUBY_EVENT_CALL, method_added_tracker, NULL);
 }
 
+// iseq
+
+const struct rb_iseq *rb_iseqw_to_iseq(VALUE iseqw);
+
+#ifdef HAVE_RB_ISEQ_TYPE
+VALUE rb_iseq_type(const struct rb_iseq *);
+
+static VALUE
+iseq_type(VALUE iseqw)
+{
+    const struct rb_iseq *iseq = rb_iseqw_to_iseq(iseqw);
+    return rb_iseq_type(iseq);
+}
+#endif
+
+#ifdef HAVE_RB_ISEQ_PARAMETERS
+VALUE rb_iseq_parameters(const struct rb_iseq *, int is_proc);
+
+static VALUE
+iseq_parameters_symbols(VALUE iseqw)
+{
+    const struct rb_iseq *iseq = rb_iseqw_to_iseq(iseqw);
+    VALUE params = rb_iseq_parameters(iseq, 0);
+    VALUE ary = rb_ary_new();
+
+    static VALUE sym_ast, sym_astast, sym_amp;
+
+    if (sym_ast == 0) {
+        sym_ast = ID2SYM(rb_intern("*"));
+        sym_astast = ID2SYM(rb_intern("**"));
+        sym_amp = ID2SYM(rb_intern("&"));
+    }
+
+    for (long i=0; i<RARRAY_LEN(params); i++) {
+        VALUE e = RARRAY_AREF(params, i);
+        if (RARRAY_LEN(e) == 2) {
+            VALUE sym = RARRAY_AREF(e, 1);
+            if (sym != sym_ast &&
+                sym != sym_astast &&
+                sym != sym_amp) rb_ary_push(ary, RARRAY_AREF(e, 1));
+        }
+    }
+
+    return ary;
+}
+#endif
+
+#ifdef HAVE_RB_ISEQ_CODE_LOCATION
+void rb_iseq_code_location(const struct rb_iseq *, int *first_lineno, int *first_column, int *last_lineno, int *last_column);
+
+static VALUE
+iseq_first_line(VALUE iseqw)
+{
+    const struct rb_iseq *iseq = rb_iseqw_to_iseq(iseqw);
+    int line;
+    rb_iseq_code_location(iseq, &line, NULL, NULL, NULL);
+    return INT2NUM(line);
+}
+
+static VALUE
+iseq_last_line(VALUE iseqw)
+{
+    const struct rb_iseq *iseq = rb_iseqw_to_iseq(iseqw);
+    int line;
+    rb_iseq_code_location(iseq, NULL, NULL, &line, NULL);
+    return INT2NUM(line);
+}
+#endif
+
 void Init_iseq_collector(void);
 
 void
 Init_debug(void)
 {
+    VALUE rb_mRubyVM = rb_const_get(rb_cObject, rb_intern("RubyVM"));
+    VALUE rb_cISeq = rb_const_get(rb_mRubyVM, rb_intern("InstructionSequence"));
     rb_mDebugger = rb_const_get(rb_cObject, rb_intern("DEBUGGER__"));
     rb_cFrameInfo = rb_const_get(rb_mDebugger, rb_intern("FrameInfo"));
 
@@ -134,5 +205,18 @@ Init_debug(void)
     rb_define_singleton_method(rb_mDebugger, "frame_depth", frame_depth, 0);
     rb_define_singleton_method(rb_mDebugger, "create_method_added_tracker", create_method_added_tracker, 0);
     rb_define_const(rb_mDebugger, "SO_VERSION", rb_str_new2(RUBY_DEBUG_VERSION));
+
+    // iseq
+#ifdef HAVE_RB_ISEQ_TYPE
+    rb_define_method(rb_cISeq, "type", iseq_type, 0);
+#endif
+#ifdef HAVE_RB_ISEQ_PARAMETERS
+    rb_define_method(rb_cISeq, "parameters_symbols", iseq_parameters_symbols, 0);
+#endif
+#ifdef HAVE_RB_ISEQ_CODE_LOCATION
+    rb_define_method(rb_cISeq, "first_line", iseq_first_line, 0);
+    rb_define_method(rb_cISeq, "last_line", iseq_last_line, 0);
+#endif
+
     Init_iseq_collector();
 }

data/ext/debug/extconf.rb

@@ -1,4 +1,15 @@
 require 'mkmf'
 require_relative '../../lib/debug/version'
 File.write("debug_version.h", "#define RUBY_DEBUG_VERSION \"#{DEBUGGER__::VERSION}\"\n")
+
+have_func "rb_iseq_parameters(NULL, 0)",
+          [["VALUE rb_iseq_parameters(void *, int is_proc);"]]
+
+have_func "rb_iseq_code_location(NULL, NULL, NULL, NULL, NULL)",
+          [["void rb_iseq_code_location(void *, int *first_lineno, int *first_column, int *last_lineno, int *last_column);"]]
+
+# from Ruby 3.1
+have_func "rb_iseq_type(NULL)",
+          [["VALUE rb_iseq_type(void *);"]]
+
 create_makefile 'debug/debug'

data/lib/debug/breakpoint.rb

@@ -8,9 +8,13 @@ module DEBUGGER__
 
     attr_reader :key
 
-    def initialize do_enable = true
+    def initialize cond, command, path, do_enable: true
       @deleted = false
 
+      @cond = cond
+      @command = command
+      @path = path
+
       setup
       enable if do_enable
     end
@@ -82,8 +86,11 @@ module DEBUGGER__
     end
 
     def skip_path?(path)
-      if @path
+      case @path
+      when Regexp
         !path.match?(@path)
+      when String
+        !path.include?(@path)
       else
         super
       end
@@ -108,7 +115,7 @@ module DEBUGGER__
       @oneshot = oneshot
       @key = [:iseq, @iseq.path, @iseq.first_lineno].freeze
 
-      super()
+      super(nil, nil, nil)
     end
 
     def setup
@@ -127,20 +134,17 @@ module DEBUGGER__
     attr_reader :path, :line, :iseq
 
     def initialize path, line, cond: nil, oneshot: false, hook_call: true, command: nil
-      @path = path
       @line = line
-      @cond = cond
       @oneshot = oneshot
       @hook_call = hook_call
-      @command = command
       @pending = false
 
       @iseq = nil
       @type = nil
 
-      @key = [@path, @line].freeze
+      @key = [path, @line].freeze
 
-      super()
+      super(cond, command, path)
 
       try_activate
       @pending = !@iseq
@@ -216,7 +220,7 @@ module DEBUGGER__
       nearest = nil # NearestISeq
 
       ObjectSpace.each_iseq{|iseq|
-        if (iseq.absolute_path || iseq.path) == self.path &&
+        if DEBUGGER__.compare_path((iseq.absolute_path || iseq.path), self.path) &&
             iseq.first_lineno <= self.line &&
             iseq.type != :ensure # ensure iseq is copied (duplicated)
 
@@ -277,11 +281,7 @@ module DEBUGGER__
       @key = [:catch, @pat].freeze
       @last_exc = nil
 
-      @cond = cond
-      @command = command
-      @path = path
-
-      super()
+      super(cond, command, path)
     end
 
     def setup
@@ -314,29 +314,28 @@ module DEBUGGER__
   end
 
   class CheckBreakpoint < Breakpoint
-    def initialize expr, path
-      @expr = expr.freeze
-      @key = [:check, @expr].freeze
-      @path = path
+    def initialize cond:, command: nil, path: nil
+      @key = [:check, cond].freeze
 
-      super()
+      super(cond, command, path)
     end
 
     def setup
       @tp = TracePoint.new(:line){|tp|
-        next if tp.path.start_with? __dir__
-        next if tp.path.start_with? '<internal:'
+        next if SESSION.in_subsession? # TODO: Ractor support
         next if ThreadClient.current.management?
         next if skip_path?(tp.path)
 
-        if safe_eval tp.binding, @expr
+        if safe_eval tp.binding, @cond
           suspend
         end
       }
     end
 
     def to_s
-      "#{generate_label("Check")} #{@expr}"
+      s = "#{generate_label("Check")}"
+      s += super
+      s
     end
   end
 
@@ -348,10 +347,7 @@ module DEBUGGER__
 
       @current = current
 
-      @cond = cond
-      @command = command
-      @path = path
-      super()
+      super(cond, command, path)
     end
 
     def watch_eval(tp)
@@ -374,9 +370,6 @@ module DEBUGGER__
 
     def setup
       @tp = TracePoint.new(:line, :return, :b_return){|tp|
-        next if tp.path.start_with? __dir__
-        next if tp.path.start_with? '<internal:'
-
         watch_eval(tp)
       }
     end
@@ -404,13 +397,10 @@ module DEBUGGER__
 
       @klass = nil
       @method = nil
-      @cond = cond
       @cond_class = nil
-      @command = command
-      @path = path
       @key = "#{klass_name}#{op}#{method_name}".freeze
 
-      super(false)
+      super(cond, command, path, do_enable: false)
     end
 
     def setup
@@ -419,7 +409,6 @@ module DEBUGGER__
         next if @cond_class && !tp.self.kind_of?(@cond_class)
 
         caller_location = caller_locations(2, 1).first.to_s
-        next if caller_location.start_with?(__dir__)
         next if skip_path?(caller_location)
 
         suspend

data/lib/debug/client.rb

@@ -18,6 +18,10 @@ module DEBUGGER__
         case name
         when 'gen-sockpath'
           puts DEBUGGER__.create_unix_domain_socket_name
+        when 'gen-portpath'
+          port_path = File.join(DEBUGGER__.unix_domain_socket_dir, 'tcp_port')
+          File.unlink port_path if File.exist?(port_path)
+          puts port_path
         when 'list-socks'
           cleanup_unix_domain_sockets
           puts list_connections
@@ -76,7 +80,7 @@ module DEBUGGER__
 
       def cleanup_unix_domain_sockets
         Dir.glob(DEBUGGER__.create_unix_domain_socket_name_prefix + '*') do |file|
-          if /(\d+)$/ =~ file
+          if File.socket?(file) && (/-(\d+)-\d+$/ =~ file || /-(\d+)$/ =~ file)
             begin
               Process.kill(0, $1.to_i)
             rescue Errno::EPERM
@@ -88,7 +92,9 @@ module DEBUGGER__
       end
 
       def list_connections
-        Dir.glob(DEBUGGER__.create_unix_domain_socket_name_prefix + '*')
+        Dir.glob(DEBUGGER__.create_unix_domain_socket_name_prefix + '*').find_all do |path|
+          File.socket?(path)
+        end
       end
     end
 
@@ -175,7 +181,7 @@ module DEBUGGER__
         trap(:SIGWINCH){
           @width = IO.console_size[1]
         }
-      rescue ArgumentError => e
+      rescue ArgumentError
         @width = 80
       end