debug 1.0.0.beta5 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '039bd2cbfdb3a67bbd91603b077a4f4784235fb0c7b48721a4b9f27b493231c6'
-  data.tar.gz: f9605d076dff9d8571e70245baa5c2e97c2377cc7f92ee627cbc1f051361217b
+  metadata.gz: 4753f123beef802e8cea541c779672938b200d5077011cd53a6a99c282d225cb
+  data.tar.gz: '078b495c6c5170cf6704c3100e1769477efadcbca47b5bae54c18c76424b8466'
 SHA512:
-  metadata.gz: f222a8b1ec58fd6f5264e61ee8613e6ed229c9ebff73c6b4904c4c6c2bded0d625b776fb510b23dec57636cf576a68d471f0b91d7b01d36f8baad741ff64fd38
-  data.tar.gz: 152431ba38203334bbf1c7449ff36a6d49f5116aaa78c017ca5ffa6d695ca87be06bc011822d0bbd325e15c46504385adf4ef94e74ebd37f97468f049da910e8
+  metadata.gz: 4e3e35a50f48444a978499798ef4d0ff997060f8562118baadec7af7c55ce4932f0a7ebd937dca974338c4086e44fbe34ce85b12386d3b67f65c774ab642a0b1
+  data.tar.gz: 3ba0fa3adf1122d4c86ac491c99a782d3f31d519255f4110e9721f3749bd87ac0aed2f9d1528a14b4ca814a3eb60ed0ef2f30cb51b24f6ec219e8b9ead6c5b73

data/CONTRIBUTING.md

@@ -15,8 +15,6 @@ If you spot any problem, please open an issue.
 
 ```bash
 $ rake test
-# or
-$ ruby bin/test-unit.rb
 ```
 
 ### Run specific test(s)
@@ -27,6 +25,199 @@ $ ruby test/debug/bp_test.rb # run all tests in the specified file
 $ ruby test/debug/bp_test.rb -h # to see all the test options
 ```
 
+## Generate Tests
+There is a test generator in `debug.rb` project to make it easier to write tests.
+### Quickstart
+This section shows you how to create test file by test generator. For more advanced informations on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
+#### 1. Create a target file for debuggee.
+Let's say, we created `target.rb` which is located in top level directory of debugger.
+```ruby
+module Foo
+  class Bar
+    def self.a
+      "hello"
+    end
+  end
+  Bar.a
+  bar = Bar.new
+end
+```
+#### 2. Run `gentest` as shown in the example below.
+```shell
+$ bin/gentest target.rb
+```
+#### 3. Debugger will be executed. You can type any debug commands.
+```shell
+$ bin/gentest target.rb
+DEBUGGER: Session start (pid: 11139)
+[1, 9] in ~/workspace/debug/target.rb
+=>   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
+=>#0	<main> at ~/workspace/debug/target.rb:1
+INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:1","line":1}
+(rdbg)s
+ s
+[1, 9] in ~/workspace/debug/target.rb
+     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
+=>#0	<module:Foo> at ~/workspace/debug/target.rb:2
+  #1	<main> at ~/workspace/debug/target.rb:1
+INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:2","line":2}
+(rdbg)n
+ n
+[1, 9] in ~/workspace/debug/target.rb
+     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
+=>#0	<class:Bar> at ~/workspace/debug/target.rb:3
+  #1	<module:Foo> at ~/workspace/debug/target.rb:2
+  # and 1 frames (use `bt' command for all frames)
+INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
+(rdbg)b 7
+ b 7
+#0  BP - Line  /Users/naotto/workspace/debug/target.rb:7 (line)
+INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
+(rdbg)c
+ c
+[2, 9] in ~/workspace/debug/target.rb
+     2|   class Bar
+     3|     def self.a
+     4|       "hello"
+     5|     end
+     6|   end
+=>   7|   Bar.a
+     8|   bar = Bar.new
+     9| end
+=>#0	<module:Foo> at ~/workspace/debug/target.rb:7
+  #1	<main> at ~/workspace/debug/target.rb:1
+
+Stop by #0  BP - Line  /Users/naotto/workspace/debug/target.rb:7 (line)
+INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:7","line":7}
+(rdbg)q!
+ q!
+created: /Users/naotto/workspace/debug/test/tool/../debug/foo_test.rb
+    class: FooTest
+    method: test_1629720194
+```
+#### 4. The test file will be created as `test/debug/foo_test.rb`.
+If the file already exists, **only method** will be added to it.
+```ruby
+# frozen_string_literal: true
+
+require_relative '../support/test_case'
+
+module DEBUGGER__
+  class FooTest < TestCase
+    def 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
+    end
+    
+    def test_1629720194
+      debug_code(program) do
+        type 's'
+        assert_line_num 2
+        assert_line_text([
+          /\[1, 9\] in .*/,
+          /     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/,
+          /=>\#0\t<module:Foo> at .*/,
+          /  \#1\t<main> at .*/
+        ])
+        type 'n'
+        assert_line_num 3
+        assert_line_text([
+          /\[1, 9\] in .*/,
+          /     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/,
+          /=>\#0\t<class:Bar> at .*/,
+          /  \#1\t<module:Foo> at .*/,
+          /  \# and 1 frames \(use `bt' command for all frames\)/
+        ])
+        type 'b 7'
+        assert_line_text(/\#0  BP \- Line  .*/)
+        type 'c'
+        assert_line_num 7
+        assert_line_text([
+          /\[2, 9\] in .*/,
+          /     2\|   class Bar/,
+          /     3\|     def self\.a/,
+          /     4\|       "hello"/,
+          /     5\|     end/,
+          /     6\|   end/,
+          /=>   7\|   Bar\.a/,
+          /     8\|   bar = Bar\.new/,
+          /     9\| end/,
+          /=>\#0\t<module:Foo> at .*/,
+          /  \#1\t<main> at .*/,
+          //,
+          /Stop by \#0  BP \- Line  .*/
+        ])
+        type 'q!'
+      end
+    end
+  end
+end
+```
+
+#### gentest options
+You can get more information about `gentest` here.
+
+The default method name is `test_foo` and the class name is `FooTest`. The file name will be `[Lowercase letters with "Test" removed from the class name]_test.rb`.
+```shell
+# run without any options(test method name will be `test_foo`, class name will be `FooTest`, file name will be `foo_test.rb`)
+$ bin/gentest target.rb
+# specify the class name(test method name will be `test_foo`, class name will be `StepTest`, file name will be `step_test.rb`)
+$ bin/gentest target.rb -c StepTest
+# specify the method name(test method name will be `test_step`, class name will be `FooTest`, file name will be `foo_test.rb`)
+$ bin/gentest target.rb -m test_step
+# specify class name and method name(test method name will be `test_step`, class name will be `StepTest`, file name will be `step_test.rb`.)
+$ bin/gentest target.rb -c StepTest -m test_step
+```
+
 ## To Update README
 
 This project generates `README.md` from the template `misc/README.md.erb`
@@ -96,6 +287,7 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
 
 ```
 ❯ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
+DEBUGGER: Session start (pid: 9815)
 [1, 10] in target.rb
 =>    1| class Foo
       2|   def first_call
@@ -108,10 +300,10 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
       9|     end
      10|   end
 =>#0    <main> at target.rb:1
-(rdbg:init) b 20
-#1 line bp /PATH_TO_PROJECT/debug/target.rb:20 (return)
-(rdbg:init) c
-[15, 23] in target.rb
+(rdbg:commands) b 20
+#0  BP - Line  /PATH_TO_PROJECT/target.rb:20 (return)
+(rdbg:commands) c
+[15, 24] in target.rb
      15|     yield(10)
      16|   end
      17|
@@ -121,25 +313,26 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
      21| end
      22|
      23| Foo.new.first_call
+     24|
 =>#0    Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
-  #1    block{|ten=10|} in second_call at target.rb:8
+  #1    block {|ten=10|} in second_call at target.rb:8
   # and 4 frames (use `bt' command for all frames)
 
-Stop by #1 line bp /PATH_TO_PROJECT/debug/target.rb:20 (return)
-(rdbg:init) bt
+Stop by #0  BP - Line  /PATH_TO_PROJECT/target.rb:20 (return)
+(rdbg:commands) bt
 =>#0    Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
-  #1    block{|ten=10|} in second_call at target.rb:8
-  #2    Foo#third_call_with_block(block=#<Proc:0x00007f8bc32f0c28 target.rb:7>) at target.rb:15
+  #1    block {|ten=10|} in second_call at target.rb:8
+  #2    Foo#third_call_with_block(block=#<Proc:0x00007f9283101568 target.rb:7>) at target.rb:15
   #3    Foo#second_call(num=20) at target.rb:7
-  #4    first_call at target.rb:3
+  #4    Foo#first_call at target.rb:3
   #5    <main> at target.rb:23
-(rdbg:init) info
+(rdbg:commands) info
 =>#0    Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
- %self => #<Foo:0x00007f8bc32f0ed0>
- %return => 30
- num1 => 20
- num2 => 10
- @ivar1 => 10
- @ivar2 => 20
-(rdbg:init) q!
+%self => #<Foo:0x00007f92831016d0 @ivar1=10, @ivar2=20>
+%return => 30
+num1 => 20
+num2 => 10
+@ivar1 => 10
+@ivar2 => 20
+(rdbg:commands) q!
 ```

data/Gemfile

@@ -5,3 +5,4 @@ gemspec
 gem "rake"
 gem "rake-compiler"
 gem "test-unit", "~> 3.0"
+gem "test-unit-rr"

data/README.md

@@ -11,8 +11,8 @@ New debug.rb has several advantages:
 * Remote debugging: Support remote debugging natively.
   * UNIX domain socket
   * TCP/IP
-  * VSCode/DAP integration (TODO)
-* Extensible: application can introduce debugging support with several methods
+  * VSCode/DAP integration ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg))
+* Extensible: application can introduce debugging support with several ways:
   * By `rdbg` command
   * By loading libraries with `-r` command line option
   * By calling Ruby's method explicitly
@@ -20,6 +20,7 @@ New debug.rb has several advantages:
   * Support threads (almost done) and ractors (TODO).
   * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
   * Show parameters on backtrace command.
+  * Support recording & reply debugging.
 
 # Installation
 
@@ -29,300 +30,373 @@ $ gem install debug --pre
 
 or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
 
-# How to use
+If you use Bundler, write the following line to your Gemfile.
+
+```
+gem "debug", ">= 1.0.0.rc"
+```
+
+# HOW TO USE
+
+To use a debugger, roughly you will do the following steps:
+
+1. Set breakpoints.
+2. Run a program with the debugger.
+3. At the breakpoint, enter the debugger console.
+4. Use debug commands.
+    * Query the program status (e.g. `p lvar` to see the local variable `lvar`).
+    * Control program flow (e.g. move to the another line with `step`, to the next line with `next`).
+    * Set another breakpoint (e.g. `catch Exception` to set a breakpoint when `Exception` is raised).
+    * Change the configuration (e.g. `config set no_color true` to disable coloring).
+    * Continue the program (`c` or `continue`) and goto 3.
+
+## Invoke with the debugger
+
+There are several options for (1) and (2). Please choose your favorite way.
+
+### Modify source code as `binding.pry` and `binding.irb`
+
+If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting `binding.break` method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+After that, you run the program as usual and you will enter the debug console at breakpoints you inserted.
+
+The following example shows the demonstration of `binding.break`.
+
+```shell
+$ cat target.rb                        # Sample program
+require 'debug'
+
+a = 1
+b = 2
+binding.break                          # Program will stop here
+c = 3
+d = 4
+binding.break                          # Program will stop here
+p [a, b, c, d]
+
+$ ruby target.rb                       # Run the program normally.
+DEBUGGER: Session start (pid: 7604)
+[1, 10] in target.rb
+      1| require 'debug'
+      2|
+      3| a = 1
+      4| b = 2
+=>    5| binding.break                 # Now you can see it stops at this line
+      6| c = 3
+      7| d = 4
+      8| binding.break
+      9| p [a, b, c, d]
+     10|
+=>#0    <main> at target.rb:5
+
+(rdbg) info locals                     # You can show local variables
+=>#0    <main> at target.rb:5
+%self => main
+a => 1
+b => 2
+c => nil
+d => nil
+
+(rdbg) continue                        # Continue the execution
+[3, 11] in target.rb
+      3| a = 1
+      4| b = 2
+      5| binding.break
+      6| c = 3
+      7| d = 4
+=>    8| binding.break                 # Again the program stops at here
+      9| p [a, b, c, d]
+     10|
+     11| __END__
+=>#0    <main> at target.rb:8
+
+(rdbg) info locals                     # And you can see the updated local variables
+=>#0    <main> at target.rb:8
+%self => main
+a => 1
+b => 2
+c => 3
+d => 4
+
+(rdbg) continue
+[1, 2, 3, 4]
+```
+
+### Invoke the program from the debugger as a traditional debuggers
+
+If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
+Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
+
+```shell
+$ cat target.rb                        # Sample program
+a = 1
+b = 2
+c = 3
+d = 4
+p [a, b, c, d]
+
+$ rdbg target.rb                       # run like `ruby target.rb`
+DEBUGGER: Session start (pid: 7656)
+[1, 7] in target.rb
+=>    1| a = 1
+      2| b = 2
+      3| c = 3
+      4| d = 4
+      5| p [a, b, c, d]
+      6|
+      7| __END__
+=>#0    <main> at target.rb:1
 
-## Invoke with debugger
+(rdbg)
+```
 
-You can run ruby program on debugger with the local debug console or the remote debug console.
+`rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands. `(rdbg)` is prompt. Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
 
-* (a) Run a ruby program with the local debug console
-* (b) Run a ruby program with the remote debug console by opening a network port
-  * (b-1) Open with UNIX domain socket
-  * (b-2) Open with TCP/IP port
+```shell
+(rdbg) break 3                         # set breakpoint at line 3
+#0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 
-(b-1) is useful when you want to use debugging features after running the program.
-(b-2) is also useful when you don't have a ssh access for the Ruby process.
+(rdbg) b 5                             # set breakpoint at line 5
+#1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
 
-To use debugging feature, you can have 3 ways.
+(rdbg) break                           # show all registered breakpoints
+#0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
+#1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
+```
 
-* (1) Use `rdbg` command
-* (2) Use `ruby -r debug...` command line option
-* (3) Write `require 'debug...'` in .rb files
+You can see that two breakpoints are registered. Let's continue the program by `continue` command.
 
-### Local debug console
+```shell
+(rdbg) continue
+[1, 7] in target.rb
+      1| a = 1
+      2| b = 2
+=>    3| c = 3
+      4| d = 4
+      5| p [a, b, c, d]
+      6|
+      7| __END__
+=>#0    <main> at target.rb:3
 
-#### (1) Use `rdbg` command
+Stop by #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 
-```
-$ rdbg target.rb
-$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
+(rdbg)
 ```
 
-#### (2) Use `-r debug/run` command line option
+You can see that we can stop at line 3.
+Let's see the local variables with `info` command, and continue.
+You can also confirm that the program will suspend at line 5 and you can use `info` command again.
 
-```
-$ ruby -r debug/run target.rb
-```
+```shell
+(rdbg) info
+=>#0    <main> at target.rb:3
+%self => main
+a => 1
+b => 2
+c => nil
+d => nil
 
-#### (3) Write `require 'debug...'` in .rb files
+(rdbg) continue
+[1, 7] in target.rb
+      1| a = 1
+      2| b = 2
+      3| c = 3
+      4| d = 4
+=>    5| p [a, b, c, d]
+      6|
+      7| __END__
+=>#0    <main> at target.rb:5
 
-```ruby
-# target.rb
-require 'debug/run' # start the debug console
+Stop by #1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
 
-# or
+(rdbg) info
+=>#0    <main> at target.rb:5
+%self => main
+a => 1
+b => 2
+c => 3
+d => 4
 
-require 'debug/session'  # introduce the functionality
-DEBUGGER__.console       # and start the debug console
-# ... rest of program ...
+(rdbg) continue
+[1, 2, 3, 4]
 ```
 
-```
-$ ruby target.rb
-```
+By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
+It will help that if you want to know what the program is doing.
 
-When you run the program with the debug console, you will see the debug console prompt `(rdbg)`.
-The debuggee program (`target.rb`) is suspended at the beginning of `target.rb`.
+### Use `rdbg` with commands written in Ruby
 
-You can type any debugger's command described bellow. "c" or "continue" resume the debuggee program.
-You can suspend the debuggee program and show the debug console with `Ctrl-C`.
+If you want to run a command written in Ruby like like `rake`, `rails`, `bundle`, `rspec` and so on, you can use `rdbg -c` option.
 
-The following example shows simple usage of the debug console. You can show the all variables
+* Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
+* With `-c` option, `rdbg -c <name>` means that `<name>` is command in `PATH` and simply invoke it with the debugger.
 
-```
-$ rdbg  ~/src/rb/target.rb
+Examples:
+* `rdbg -c -- rails server`
+* `rdbg -c -- bundle exec ruby foo.rb`
+* `rdbg -c -- bundle exec rake test`
+* `rdbg -c -- ruby target.rb` is same as `rdbg target.rb`
 
-[1, 5] in /home/ko1/src/rb/target.rb
-=>    1| a = 1
-      2| b = 2
-      3| c = 3
-      4| p [a + b + c]
-      5|
---> #0  /home/ko1/src/rb/target.rb:1:in `<main>'
+NOTE: `--` is needed to separate the command line options for `rdbg` and invoking command. For example, `rdbg -c rake -T` is recognized like `rdbg -c -T -- rake`. It should be `rdbg -c -- rake -T`.
 
-(rdbg) info                                             # Show all local variables
- %self => main
- a => nil
- b => nil
- c => nil
+NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
 
-(rdbg) p a                                              # Same as p(a)
-=> nil
+### Using VSCode
 
-(rdbg) s                                                # Step in ("s" is a short name of "step")
+Like other languages, you can use this debugger on the VSCode.
 
-[1, 5] in /home/ko1/src/rb/target.rb
-      1| a = 1
-=>    2| b = 2
-      3| c = 3
-      4| p [a + b + c]
-      5|
---> #0  /home/ko1/src/rb/target.rb:2:in `<main>'
+1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
+2. Open `.rb` file (e.g. `target.rb`)
+3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key)
+4. Choose "Start debugging" in "Run" menu (or type F5 key)
+5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
+6. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints.
 
-(rdbg) <Enter>                                          # Repeat the last command ("step")
+Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
 
-[1, 5] in /home/ko1/src/rb/target.rb
-      1| a = 1
-      2| b = 2
-=>    3| c = 3
-      4| p [a + b + c]
-      5|
---> #0  /home/ko1/src/rb/target.rb:3:in `<main>'
+You can configure the extension in `.vscode/launch.json`.
+Please see the extension page for more details.
 
-(rdbg)                                                  # Repeat the last command ("step")
+## Remote debugging
 
-[1, 5] in /home/ko1/src/rb/target.rb
-      1| a = 1
-      2| b = 2
-      3| c = 3
-=>    4| p [a + b + c]
-      5|
---> #0  /home/ko1/src/rb/target.rb:4:in `<main>'
-
-(rdbg) info                                             # Show all local variables
- %self => main
- a => 1
- b => 2
- c => 3
-
-(rdbg) c                                                # Continue the program ("c" is a short name of "continue")
-[6]
-```
+You can use this debugger as a remote debugger. For example, it will help the following situations:
 
-### Remote debug (1) UNIX domain socket
+* Your application does not run on TTY and it is hard to use `binding.pry` or `binding.irb`.
+  * Your application is running on Docker container and there is no TTY.
+  * Your application is running as a daemon.
+  * Your application uses pipe for STDIN or STDOUT.
+* Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
 
-#### (1) Use `rdbg` command
+You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime.
 
-```
-$ rdbg --open target.rb # or rdbg -O target.rb for shorthand
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
-```
+### Invoke as a remote debuggee
 
-#### (2) Use `-r debug/open` command line option
+There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
 
-```
-$ ruby -r debug/open target.rb
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
-```
+#### `rdbg --open` (or `rdbg -O` for short)
 
-#### (3) Write `require 'debug/open'` in .rb files
+You can run a script with `rdbg --open target.rb` command and run a `target.rb` as a debuggee program. It also opens the network port and suspends at the beginning of `target.rb`.
 
-```ruby
-# target.rb
-require 'debug/open' # open the debugger entry point by UNIX domain socket.
-
-# or
-
-require 'debug/server' # introduce remote debugging feature
-DEBUGGER__.open        # open the debugger entry point by UNIX domain socket.
-# or DEBUGGER__.open_unix to specify UNIX domain socket.
-```
-
-```
-$ ruby target.rb
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
+```shell
+$ exe/rdbg --open target.rb
+DEBUGGER: Session start (pid: 7773)
+DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773)
+DEBUGGER: wait for debugger connection...
 ```
 
-It runs target.rb and accept debugger connection within UNIX domain socket.
-The debuggee process waits for debugger connection at the beginning of `target.rb` like that:
+By default, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
 
-```
-$ rdbg -O ~/src/rb/target.rb
-DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-29828)
-DEBUGGER: wait for debugger connection...
-```
+You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
 
-You can attach the program with the following command:
+```shell
+$ rdbg -A
+[1, 7] in target.rb
+=>    1| a = 1
+      2| b = 2
+      3| c = 3
+      4| d = 4
+      5| p [a, b, c, d]
+      6|
+      7| __END__
+=>#0    <main> at target.rb:1
 
-```
-$ rdbg --attach # or rdbg -A for shorthand
-
-[1, 4] in /home/ko1/src/rb/target.rb
-      1| (1..).each do |i|
-=>    2|   sleep 0.5
-      3|   p i
-      4| end
---> #0  [C] /home/ko1/src/rb/target.rb:2:in `sleep'
-    #1  /home/ko1/src/rb/target.rb:2:in `block in <main>' {|i=17|}
-    #2  [C] /home/ko1/src/rb/target.rb:1:in `each'
-    # and 1 frames (use `bt' command for all frames)
-
-(rdb)
+(rdbg:remote)
 ```
 
-and you can input any debug commands. `c` (or `continue`) continues the debuggee process.
+If there is no other opening ports on the default directory, `rdbg --attach` command chooses the only one opening UNIX domain socket and connect to it. If there are more files, you need to specify the file.
 
-You can detach the debugger from the debugger process with `quit` command.
-You can re-connect to the debuggee process by `rdbg -A` command again, and the debuggee process suspends the execution (and debugger can input any debug commands).
+When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program and so on) like local debug console. When an debuggee program exits, the remote console will also terminate.
 
-If you don't want to stop the debuggee process at the beginning of debuggee process (`target.rb`), you can use the following to specify "non-stop" option.
+NOTE: If you use `quit` command, only remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command.
 
-* Use `rdbg -n` option
-* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
+If you want to use TCP/IP for the remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
 
-If you are running multiple debuggee processes, the attach command (`rdbg -A`) shows the options like that:
+To connect to the debuggee, you need to specify the port.
 
-```
-$ rdbg --attach
-Please select a debug session:
-  ruby-debug-ko1-19638
-  ruby-debug-ko1-19603
+```shell
+$ rdbg --attach 12345
 ```
 
-and you need to specify one (copy and paste the name):
-
-```
-$ rdbg --attach ruby-debug-ko1-19638
-```
+If you want to choose the host to bind, you can use `--host` option.
+Note that all messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
 
-The socket file is located at
-* `RUBY_DEBUG_SOCK_DIR` environment variable if available.
-* `XDG_RUNTIME_DIR` environment variable if available.
-* `$HOME/.ruby-debug-sock` if `$HOME` is available.
+#### `require 'debug/open'` in a program
 
-### Remote debug (2) TCP/IP
+If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
 
-You can open the TCP/IP port instead of using UNIX domain socket.
+If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
+Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
+However, it is also danger because it can become another vulnerability.
+Please use it carefully.
 
-#### (1) Use `rdbg` command
+By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
 
-```
-$ rdbg -O --port=12345 target.rb
-# or
-$ rdbg --open --port=12345 target.rb
-Debugger can attach via TCP/IP (localhost:12345)
+```shell
+$ RUBY_DEBUG_PORT=12345 ruby target.rb
 ```
 
-#### (2) Use `-r debug/open` command line option
+## Configuration
 
+You can configure the debugger's behavior with debug commands and environment variables.
+When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts.
 
-```
-$ RUBY_DEBUG_PORT=12345 ruby -r debug/open target.rb
-Debugger can attach via TCP/IP (localhost:12345)
-```
+### Configuration list
 
-#### (3) Write `require 'debug/open'` in .rb files
+You can configure debugger's behavior with environment variables and `config` command. Each configuration has environment variable and the name which can be specified by `config` command.
 
-```ruby
-# target.rb
-require 'debug/open' # open the debugger entry point.
 ```
-
-and run with environment variable RUBY_DEBUG_PORT
-
-```
-$ RUBY_DEBUG_PORT=12345 ruby target.rb
-Debugger can attach via TCP/IP (localhost:12345)
+# configuration example
+config set log_level INFO
+config set no_color true
 ```
 
-or
 
-```ruby
-# target.rb
-require 'debug/server' # introduce remote debugging feature
-DEBUGGER__.open(port: 12345)
-# or DEBUGGER__.open_tcp(port: 12345)
-```
 
-```
-$ ruby target.rb
-Debugger can attach via TCP/IP (localhost:12345)
-```
+* UI
+  * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
+  * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
+  * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
+  * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shoten PATH (like $(Gem)/foo.rb)
+  * `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
+  * `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
+  * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
 
-You can also specify the host with the `RUBY_DEBUG_HOST` environment variable. And also `DEBUGGER__.open` method accepts a `host:` keyword parameter. If the host is not given, `localhost` will be used.
+* CONTROL
+  * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths (default: [])
+  * `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
+  * `RUBY_DEBUG_KEEP_ALLOC_SITE` (`keep_alloc_site`): Keep allocation site and p, pp shows it (default: false)
+  * `RUBY_DEBUG_POSTMORTEM` (`postmortem`): Enable postmortem debug (default: false)
+  * `RUBY_DEBUG_PARENT_ON_FORK` (`parent_on_fork`): Keep debugging parent process on fork (default: false)
+  * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: disabled)
 
-To attach the debuggee process, specify the port number (and hostname if needed) for the `rdbg --attach` (or `rdbg -A`) command.
+* BOOT
+  * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
+  * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
+  * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
+  * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
 
-```
-$ rdbg --attach 12345
-$ rdbg --attach hostname 12345
-```
+* REMOTE
+  * `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
+  * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (localhost if not given)
+  * `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
+  * `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
+  * `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
 
 ### Initial scripts
 
-If there are `.rdbgrc` files are there at the current directory and the home directory, files are loaded as initial scripts which contains debugger commands. `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
-
-Initial scripts are evaluated at the first suspend timing (generally, it is the beginning of the target script). For example, you can set break points with `break file:123`.
+If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
 
-If there are `.rdbgrc.rb` files at the current directory and the home directory, files are loaded as a ruby script at the initializing timing.
+* `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
+* You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
 
-### Environment variables
+Initial scripts are useful to write your favorite configurations.
+For example, you can set break points with `break file:123` in `~/.rdbgrc`.
 
-You can control debuggee's behavior with environment variables:
-
-* `RUBY_DEBUG_NONSTOP`: 1 for nonstop at the beginning of program.
-* `RUBY_DEBUG_INIT_SCRIPT`: Initial script path loaded at the first stop.
-* `RUBY_DEBUG_COMMANDS`: Debug commands invoked at the first stop. Commands should be separated by ';;'.
-* `RUBY_DEBUG_SHOW_SRC_LINES`: Show n lines source code on breakpoint (default: 10 lines).
-* `RUBY_DEBUG_SHOW_FRAMES`: Show n frames on breakpoint (default: 2 frames).
-* Remote debugging
-  * `RUBY_DEBUG_PORT`: TCP/IP remote debugging: port to open.
-  * `RUBY_DEBUG_HOST`: TCP/IP remote debugging: host (localhost if not given) to open.
-  * `RUBY_DEBUG_SOCK_PATH`: UNIX Domain Socket remote debugging: socket path to open.
-  * `RUBY_DEBUG_SOCK_DIR`: UNIX Domain Socket remote debugging: socket directory to open.
+If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
 
 ## Debug command on the debug console
 
+On the debug console, you can use the following debug commands.
+
 * `Enter` repeats the last command (useful when repeating `step`s).
 * `Ctrl-D` is equal to `quit` command.
 * [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
@@ -335,10 +409,16 @@ The `<...>` notation means the argument.
 
 * `s[tep]`
   * Step in. Resume the program until next breakable point.
+* `s[tep] <n>`
+  * Step in, resume the program at `<n>`th breakable point.
 * `n[ext]`
   * Step over. Resume the program until next line.
+* `n[ext] <n>`
+  * Step over, same as `step <n>`.
 * `fin[ish]`
   * Finish this frame. Resume the program until the current frame is finished.
+* `fin[ish] <n>`
+  * Finish frames, same as `step <n>`.
 * `c[ontinue]`
   * Resume the program.
 * `q[uit]` or `Ctrl-D`
@@ -362,10 +442,14 @@ The `<...>` notation means the argument.
    * Set breakpoint on the method `<class>#<name>`.
 * `b[reak] <expr>.<name>`
    * Set breakpoint on the method `<expr>.<name>`.
-* `b[reak] ... if <expr>`
+* `b[reak] ... if: <expr>`
   * break if `<expr>` is true at specified location.
-* `b[reak] if <expr>`
-  * break if `<expr>` is true at any lines.
+* `b[reak] ... pre: <command>`
+  * break and run `<command>` before stopping.
+* `b[reak] ... do: <command>`
+  * break and run `<command>`, and continue.
+* `b[reak] if: <expr>`
+  * break if: `<expr>` is true at any lines.
   * Note that this feature is super slow.
 * `catch <Error>`
   * Set breakpoint on raising `<Error>`.
@@ -381,6 +465,12 @@ The `<...>` notation means the argument.
 
 * `bt` or `backtrace`
   * Show backtrace (frame) information.
+* `bt <num>` or `backtrace <num>`
+  * Only shows first `<num>` frames.
+* `bt /regexp/` or `backtrace /regexp/`
+  * Only shows frames with method name or location info that matches `/regexp/`.
+* `bt <num> /regexp/` or `backtrace <num> /regexp/`
+  * Only shows first `<num>` frames with method name or location info that matches `/regexp/`.
 * `l[ist]`
   * Show current frame's source code.
   * Next `list` command shows the successor lines.
@@ -393,11 +483,26 @@ The `<...>` notation means the argument.
   * Note that edited file will not be reloaded.
 * `edit <file>`
   * Open <file> on the editor.
-* `i[nfo]`, `i[nfo] l[ocal[s]]`
+* `i[nfo]`
+   * Show information about current frame (local/instance variables and defined constants).
+* `i[nfo] l[ocal[s]]`
   * Show information about the current frame (local variables)
   * It includes `self` as `%self` and a return value as `%return`.
+* `i[nfo] i[var[s]]` or `i[nfo] instance`
+  * Show information about insttance variables about `self`.
+* `i[nfo] c[onst[s]]` or `i[nfo] constant[s]`
+  * 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] th[read[s]]`
   * Show all threads (same as `th[read]`).
+* `o[utline]` or `ls`
+  * Show you available methods, constants, local variables, and instance variables in the current scope.
+* `o[utline] <expr>` or `ls <expr>`
+  * Show you available methods and instance variables of the given object.
+  * If the object is a class/module, it also lists its constants.
 * `display`
   * Show display setting.
 * `display <expr>`
@@ -406,8 +511,6 @@ The `<...>` notation means the argument.
   * Remove all display settings.
 * `undisplay <displaynum>`
   * Remove a specified display setting.
-* `trace [on|off]`
-  * enable or disable line tracer.
 
 ### Frame control
 
@@ -431,6 +534,36 @@ The `<...>` notation means the argument.
 * `irb`
   * Invoke `irb` on the current frame.
 
+### Trace
+
+* `trace`
+  * Show available tracers list.
+* `trace line`
+  * Add a line tracer. It indicates line events.
+* `trace call`
+  * Add a call tracer. It indicate call/return events.
+* `trace exception`
+  * 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 ... into: <file>`
+  * Save trace information into: `<file>`.
+* `trace off <num>`
+  * Disable tracer specified by `<num>` (use `trace` command to check the numbers).
+* `trace off [line|call|pass]`
+  * Disable all tracers. If `<type>` is provided, disable specified type tracers.
+* `record`
+  * Show recording status.
+* `record [on|off]`
+  * Start/Stop recording.
+* `step back`
+  * Start replay. Step back with the last execution log.
+  * `s[tep]` does stepping forward with the last log.
+* `step reset`
+  * Stop replay .
+
 ### Thread control
 
 * `th[read]`
@@ -438,6 +571,21 @@ The `<...>` notation means the argument.
 * `th[read] <thnum>`
   * Switch thread specified by `<thnum>`.
 
+### Configuration
+
+* `config`
+  * Show all configuration with description.
+* `config <name>`
+  * Show current configuration of <name>.
+* `config set <name> <val>` or `config <name> = <val>`
+  * Set <name> to <val>.
+* `config append <name> <val>` or `config <name> << <val>`
+  * Append `<val>` to `<name>` if it is an array.
+* `config unset <name>`
+  * Set <name> to default.
+* `source <file>`
+  * Evaluate lines in `<file>` as debug commands.
+
 ### Help
 
 * `h[elp]`
@@ -446,6 +594,83 @@ The `<...>` notation means the argument.
   * Show help for the given command.
 
 
+## Debugger API
+
+### Start debugging
+
+#### Start by requiring a library
+
+You can start debugging without `rdbg` command by requiring the following libraries:
+
+* `require 'debug'`: Same as `rdbg --nonstop --no-sigint-hook`.
+* `require 'debug/start'`: Same as `rdbg`.
+* `require 'debug/open'`: Same as `rdbg --open`.
+* `require 'debug/open_nonstop'`: Same as `rdbg --open --nonstop`.
+
+You need to require one of them at the very beginning of the application.
+Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
+
+NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bundle exec` is used, you will see the following output:
+
+```shell
+$ ruby -r debug -e0
+.../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
+Debug.rb
+Emacs support available.
+
+.../2.7.3/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:162:    if RUBYGEMS_ACTIVATION_MONITOR.respond_to?(:mon_owned?)
+(rdb:1)
+```
+
+`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
+
+#### Start by method
+
+After loading `debug/session`, you can start debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
+
+* `DEBUGGER__.start(**kw)`: start debug session with local console.
+* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
+* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
+* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
+
+For example:
+
+```ruby
+require 'debug/session'
+DEBUGGER__.start(no_color: true,    # disable colorize
+                 log_level: 'INFO') # Change log_level to INFO
+
+... # your application code
+```
+
+### `binding.break` method
+
+`binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
+
+If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
+It is useful if you only want to call a debug command and don't want to stop there.
+
+```
+def initialize
+  @a = 1
+  binding.b do: 'watch @a'
+end
+```
+
+On this case, register a watch breakpoint for `@a` and continue to run.
+
+If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend.
+It is useful if you have operations before suspend.
+
+```
+def foo
+  binding.b pre: 'p bar()'
+  ...
+end
+```
+
+On this case, you can see the result of `bar()` every time you stop there.
+
 ## rdbg command help
 
 ```
@@ -453,13 +678,19 @@ exe/rdbg [options] -- [debuggee options]
 
 Debug console mode:
     -n, --nonstop                    Do not stop at the beginning of the script.
-    -e COMMAND                       execute debug command at the beginning of the script.
-    -x, --init-script=FILE           execute debug command in the FILE.
+    -e DEBUG_COMMAND                 Execute debug command at the beginning of the script.
+    -x, --init-script=FILE           Execute debug command in the FILE.
+        --no-rc                      Ignore ~/.rdbgrc
+        --no-color                   Disable colorize
+        --no-sigint-hook             Disable to trap SIGINT
+    -c, --command                    Enable command mode.
+                                     The first argument should be a command name in $PATH.
+                                     Example: 'rdbg -c bundle exec rake test'
 
     -O, --open                       Start remote debugging with opening the network port.
                                      If TCP/IP options are not given,
                                      a UNIX domain socket will be used.
-        --sock-path=SOCK_PATH        UNIX Doman socket path
+        --sock-path=SOCK_PATH        UNIX Domain socket path
         --port=PORT                  Listening TCP/IP port
         --host=HOST                  Listening TCP/IP host
         --cookie=COOKIE              Set a cookie for connection
@@ -468,6 +699,9 @@ Debug console mode:
 
   'rdbg target.rb foo bar'                starts like 'ruby target.rb foo bar'.
   'rdbg -- -r foo -e bar'                 starts like 'ruby -r foo -e bar'.
+  'rdbg -c rake test'                     starts like 'rake test'.
+  'rdbg -c -- rake test -t'               starts like 'rake test -t'.
+  'rdbg -c bundle exec rake test'         starts like 'bundle exec rake test'.
   'rdbg -O target.rb foo bar'             starts and accepts attaching with UNIX domain socket.
   'rdbg -O --port 1234 target.rb foo bar' starts accepts attaching with TCP/IP localhost:1234.
   'rdbg -O --port 1234 -- -r foo -e bar'  starts accepts attaching with TCP/IP localhost:1234.
@@ -486,7 +720,6 @@ Attach mode:
 
 Other options:
     -h, --help                       Print help
-    -c, --command                    Command mode (first argument is command name)
         --util=NAME                  Utility mode (used by tools)
 
 NOTE
@@ -498,6 +731,7 @@ NOTE
 # Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
+This debugger is not mature so your feedback will help us.
 
 Please also check the [contributing guideline](/CONTRIBUTING.md).