debug 1.0.0.beta7 → 1.0.0

data/lib/debug/tracer.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module DEBUGGER__
+  class Tracer
+    include SkipPathHelper
+    include Color
+
+    def colorize(str, color)
+      # don't colorize trace sent into a file
+      if @into
+        str
+      else
+        super
+      end
+    end
+
+    attr_reader :type
+
+    def initialize ui, pattern: nil, into: nil
+      if /\ADEBUGGER__::(([A-Z][a-z]+?)[A-Z][a-z]+)/ =~ self.class.name
+        @name = $1
+        @type = $2.downcase
+      end
+
+      setup
+
+      if pattern
+        @pattern = Regexp.compile(pattern)
+      else
+        @pattern = nil
+      end
+
+      if @into = into
+        @output = File.open(into, 'w')
+        @output.puts "PID:#{Process.pid} #{self}"
+      else
+        @output = ui
+      end
+
+      enable
+    end
+
+    def header depth
+      "DEBUGGER (trace/#{@type}) \#th:#{Thread.current.instance_variable_get(:@__thread_client_id)} \#depth:#{'%-2d'%depth}"
+    end
+
+    def enable
+      @tracer.enable
+    end
+
+    def disable
+      @tracer.disable
+    end
+
+    def description
+      nil
+    end
+
+    def to_s
+      s = "#{@name}#{description} (#{@tracer.enabled? ? 'enabled' : 'disabled'})"
+      s += " with pattern #{@pattern.inspect}" if @pattern
+      s += " into: #{@into}" if @into
+      s
+    end
+
+    def skip? tp
+      if tp.path.start_with?(__dir__) ||
+         tp.path.start_with?('<internal:') ||
+         ThreadClient.current.management? ||
+         skip_path?(tp.path) ||
+         skip_with_pattern?(tp)
+        true
+      else
+        false
+      end
+    end
+
+    def skip_with_pattern?(tp)
+      @pattern && !tp.path.match?(@pattern)
+    end
+
+    def out tp, msg = nil, depth = caller.size - 1
+      location_str = colorize("#{tp.path}:#{tp.lineno}", [:GREEN])
+      buff = "#{header(depth)}#{msg} at #{location_str}"
+
+      if false # TODO: Ractor.main?
+        ThreadClient.current.on_trace self.object_id, buff
+      else
+        @output.puts buff
+      end
+    end
+
+    def puts msg
+      @output.puts msg
+    end
+
+    def minfo tp
+      klass = tp.defined_class
+
+      if klass.singleton_class?
+        "#{tp.self}.#{tp.method_id}"
+      else
+        "#{klass}\##{tp.method_id}"
+      end
+    end
+  end
+
+  class LineTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:line){|tp|
+        next if skip?(tp)
+        # pp tp.object_id, caller(0)
+        out tp
+      }
+    end
+  end
+
+  class CallTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:a_call, :a_return){|tp|
+        next if skip?(tp)
+
+        depth = caller.size
+        sp = ' ' * depth
+
+        call_identifier_str =
+          if tp.defined_class
+            minfo(tp)
+          else
+            "block"
+          end
+
+        call_identifier_str = colorize_blue(call_identifier_str)
+
+        case tp.event
+        when :call, :c_call, :b_call
+          depth += 1 if tp.event == :c_call
+          out tp, ">#{sp}#{call_identifier_str}", depth
+        when :return, :c_return, :b_return
+          depth += 1 if tp.event == :c_return
+          return_str = colorize_magenta(DEBUGGER__.short_inspect(tp.return_value))
+          out tp, "<#{sp}#{call_identifier_str} #=> #{return_str}", depth
+        end
+      }
+    end
+
+    def skip_with_pattern?(tp)
+      super && !tp.method_id&.match?(@pattern)
+    end
+  end
+
+  class ExceptionTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:raise) do |tp|
+        next if skip?(tp)
+
+        exc = tp.raised_exception
+
+        out tp, " #{colorize_magenta(exc.inspect)}"
+      rescue Exception => e
+        p e
+      end
+    end
+
+    def skip_with_pattern?(tp)
+      super && !tp.raised_exception.inspect.match?(@pattern)
+    end
+  end
+
+  class ObjectTracer < Tracer
+    def initialize ui, obj_id, obj_inspect, **kw
+      @obj_id = obj_id
+      @obj_inspect = obj_inspect
+      super(ui, **kw)
+    end
+
+    def description
+      " for #{@obj_inspect}"
+    end
+
+    def colorized_obj_inspect
+      colorize_magenta(@obj_inspect)
+    end
+
+    def setup
+      @tracer = TracePoint.new(:a_call){|tp|
+        next if skip?(tp)
+
+        if tp.self.object_id == @obj_id
+          klass = tp.defined_class
+          method = tp.method_id
+          method_info =
+            if klass.singleton_class?
+              if tp.self.is_a?(Class)
+                ".#{method} (#{klass}.#{method})"
+              else
+                ".#{method}"
+              end
+            else
+              "##{method} (#{klass}##{method})"
+            end
+
+          out tp, " #{colorized_obj_inspect} receives #{colorize_blue(method_info)}"
+        else
+          b = tp.binding
+          method_info = colorize_blue(minfo(tp))
+
+          tp.parameters.each{|type, name|
+            next unless name
+
+            colorized_name = colorize_cyan(name)
+
+            case type
+            when :req, :opt, :key, :keyreq
+              if b.local_variable_get(name).object_id == @obj_id
+                out tp, " #{colorized_obj_inspect} is used as a parameter #{colorized_name} of #{method_info}"
+              end
+            when :rest
+              next name == :"*"
+
+              ary = b.local_variable_get(name)
+              ary.each{|e|
+                if e.object_id == @obj_id
+                  out tp, " #{colorized_obj_inspect} is used as a parameter in #{colorized_name} of #{method_info}"
+                end
+              }
+            when :keyrest
+              next if name == :'**'
+              h = b.local_variable_get(name)
+              h.each{|k, e|
+                if e.object_id == @obj_id
+                  out tp, " #{colorized_obj_inspect} is used as a parameter in #{colorized_name} of #{method_info}"
+                end
+              }
+            end
+          }
+        end
+      }
+    end
+  end
+end
+

data/lib/debug/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DEBUGGER__
-  VERSION = "1.0.0.beta7"
+  VERSION = "1.0.0"
 end

data/misc/README.md.erb

@@ -12,7 +12,7 @@ New debug.rb has several advantages:
   * UNIX domain socket
   * TCP/IP
   * 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 methods
+* 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,340 +20,447 @@ 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
 
 ```
-$ gem install debug --pre
+$ gem install debug
 ```
 
 or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
 
-If you use Bundler, write the following line to your Gemfile. And use rdbg command with -c option.
+If you use Bundler, write the following line to your Gemfile.
+
+```
+gem "debug", ">= 1.0.0"
+```
+
+# 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
 
-```
-gem "debug", ">= 1.0.0.beta"
+(rdbg)
 ```
 
-```
-$ rdbg -c bundle exec ruby target.rb
+`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).
+
+```shell
+(rdbg) break 3                         # set breakpoint at line 3
+#0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
+
+(rdbg) b 5                             # set breakpoint at line 5
+#1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
+
+(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)
 ```
 
-# How to use
+You can see that two breakpoints are registered. Let's continue the program by `continue` command.
 
-## Invoke with debugger
+```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
 
-You can run ruby program on debugger with the local debug console or the remote debug console.
+Stop by #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 
-* (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
+(rdbg)
+```
 
-(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.
+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.
 
-To use debugging feature, you can have 3 ways.
+```shell
+(rdbg) info
+=>#0    <main> at target.rb:3
+%self => main
+a => 1
+b => 2
+c => nil
+d => nil
 
-* (1) Use `rdbg` command
-* (2) Use `ruby -r debug...` command line option
-* (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
 
-### Local debug console
+Stop by #1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
 
-#### (1) Use `rdbg` command
+(rdbg) info
+=>#0    <main> at target.rb:5
+%self => main
+a => 1
+b => 2
+c => 3
+d => 4
 
-```
-$ rdbg target.rb
-$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
+(rdbg) continue
+[1, 2, 3, 4]
 ```
 
-#### (2) Use `-r debug/run` command line option
+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.
 
-```
-$ ruby -r debug/run target.rb
-```
+### Use `rdbg` with commands written in Ruby
 
-#### (3) Write `require 'debug...'` in .rb files
+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.
 
-```ruby
-# target.rb
-require 'debug/run' # start the debug console
+* 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.
 
-# ... rest of program ...
-```
+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`
 
+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`.
 
-```
-$ ruby target.rb
-```
+NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
 
-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`.
+### Using VSCode
 
+Like other languages, you can use this debugger on the VSCode.
 
-Alternatively, start the debugger at a specific location in your program using `binding.break` (`binding.b` for short).
+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.
 
-```ruby
-# target.rb
-require 'debug' # start the debugger
+Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
 
-# ... program ...
+You can configure the extension in `.vscode/launch.json`.
+Please see the extension page for more details.
 
-binding.break # setup a breakpoint at this line
+## Remote debugging
 
-# ... rest of program ...
-```
+You can use this debugger as a remote debugger. For example, it will help the following situations:
 
-```
-$ ruby target.rb
-```
+* 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).
+
+You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime.
 
-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`.
+### Invoke as a remote debuggee
 
-The following example shows simple usage of the debug console. You can show the all variables
+There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
 
+#### `rdbg --open` (or `rdbg -O` for short)
+
+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`.
+
+```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...
 ```
-$ rdbg  ~/src/rb/target.rb
 
-[1, 5] in /home/ko1/src/rb/target.rb
+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).
+
+You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
+
+```shell
+$ rdbg -A
+[1, 7] in 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>'
+      4| d = 4
+      5| p [a, b, c, d]
+      6|
+      7| __END__
+=>#0    <main> at target.rb:1
 
-(rdbg) info                                             # Show all local variables
- %self => main
- a => nil
- b => nil
- c => nil
+(rdbg:remote)
+```
 
-(rdbg) p a                                              # Same as p(a)
-=> nil
+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.
 
-(rdbg) s                                                # Step in ("s" is a short name of "step")
+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.
 
-[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>'
-
-(rdbg) <Enter>                                          # Repeat the last command ("step")
+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.
 
-[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>'
+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`.
 
-(rdbg)                                                  # Repeat the last command ("step")
+To connect to the debuggee, you need to specify the port.
 
-[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]
+```shell
+$ rdbg --attach 12345
 ```
 
-### Remote debug (1) UNIX domain socket
+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.
 
-#### (1) Use `rdbg` command
+#### `require 'debug/open'` in a program
 
-```
-$ 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)
-```
+If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
 
-#### (2) Use `-r debug/open` command line option
+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.
 
-```
-$ ruby -r debug/open target.rb
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
+By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
+
+```shell
+$ RUBY_DEBUG_PORT=12345 ruby target.rb
 ```
 
-#### (3) Write `require 'debug/open'` in .rb files
+## Configuration
 
-```ruby
-# target.rb
-require 'debug/open' # open the debugger entry point by UNIX domain socket.
+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.
 
-# or
+### Configuration list
 
-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.
-```
+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
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
+# configuration example
+config set log_level INFO
+config set no_color true
 ```
 
-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:
+<% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %>
+<% /\A(\w+): (.+)/ =~ desc; if cat != $1; cat = 1 %>
+* <%= $1 %>
+<% cat = $1; end %>  * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %>
+
+### Initial scripts
 
-```
-$ 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...
-```
+If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
 
-You can attach the program with the following command:
+* `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).
 
-```
-$ 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)
-```
+Initial scripts are useful to write your favorite configurations.
+For example, you can set break points with `break file:123` in `~/.rdbgrc`.
 
-and you can input any debug commands. `c` (or `continue`) continues the debuggee process.
+If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
 
-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).
+## Debug command on the debug console
 
-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.
+On the debug console, you can use the following debug commands.
 
-* Use `rdbg -n` option
-* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
+There are additional features:
 
-If you are running multiple debuggee processes, the attach command (`rdbg -A`) shows the options like that:
+* `<expr>` without debug command is almost same as `pp <expr>`.
+  * If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression and the result will be printed with `pp` method. So that the input `foo.bar` is same as `pp foo.bar`.
+  * If `<expr>` is recognized as a debug command, of course it is not evaluated as a Ruby expression, but is executed as debug command. For example, you can not evaluate such single letter local variables `i`, `b`, `n`, `c` because they are single letter debug commands. Use `p i` instead.
+* `Enter` without any input 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)
 
-```
-$ rdbg --attach
-Please select a debug session:
-  ruby-debug-ko1-19638
-  ruby-debug-ko1-19603
-```
+You can use the following debug commands. Each command should be written in 1 line.
+The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
+The `<...>` notation means the argument.
 
-and you need to specify one (copy and paste the name):
+<%= DEBUGGER__.help %>
 
-```
-$ rdbg --attach ruby-debug-ko1-19638
-```
+## Debugger API
 
-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.
+### Start debugging
 
-### Remote debug (2) TCP/IP
+#### Start by requiring a library
 
-You can open the TCP/IP port instead of using UNIX domain socket.
+You can start debugging without `rdbg` command by requiring the following libraries:
 
-#### (1) Use `rdbg` command
+* `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`.
 
-```
-$ rdbg -O --port=12345 target.rb
-# or
-$ rdbg --open --port=12345 target.rb
-Debugger can attach via TCP/IP (localhost:12345)
-```
+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.
 
-#### (2) Use `-r debug/open` command line option
+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.
 
-```
-$ RUBY_DEBUG_PORT=12345 ruby -r debug/open target.rb
-Debugger can attach via TCP/IP (localhost:12345)
+.../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)
 ```
 
-#### (3) Write `require 'debug/open'` in .rb files
+`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.
 
-```ruby
-# target.rb
-require 'debug/open' # open the debugger entry point.
-```
+#### Start by method
 
-and run with environment variable RUBY_DEBUG_PORT
+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.
 
-```
-$ RUBY_DEBUG_PORT=12345 ruby target.rb
-Debugger can attach via TCP/IP (localhost:12345)
-```
+* `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
 
-or
+For example:
 
 ```ruby
-# target.rb
-require 'debug/server' # introduce remote debugging feature
-DEBUGGER__.open(port: 12345)
-# or DEBUGGER__.open_tcp(port: 12345)
-```
+require 'debug/session'
+DEBUGGER__.start(no_color: true,    # disable colorize
+                 log_level: 'INFO') # Change log_level to INFO
 
-```
-$ ruby target.rb
-Debugger can attach via TCP/IP (localhost:12345)
+... # your application code
 ```
 
-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.
+### `binding.break` method
 
-To attach the debuggee process, specify the port number (and hostname if needed) for the `rdbg --attach` (or `rdbg -A`) command.
+`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.
 
 ```
-$ rdbg --attach 12345
-$ rdbg --attach hostname 12345
+def initialize
+  @a = 1
+  binding.b do: 'watch @a'
+end
 ```
 
-### Initial scripts
+On this case, register a watch breakpoint for `@a` and continue to run.
 
-If there are `~/.rdbgrc`, the file is loaded as initial scripts which contains debugger commands at the beginning of debug session. `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file. You can write configurations in a file. For example, you can set break points with `break file:123` in `~/.rdbgrc`.
-
-If there are `~/.rdbgrc.rb` is available, it is loaded as a ruby script at same timing.
-
-### Configurations
-
-You can configure debugger's setting with environment variables and `config` command.
-You can write any configuration into `~/.rdbgrc` like:
+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.
 
 ```
-config set log_level INFO
-config set no_color true
+def foo
+  binding.b pre: 'p bar()'
+  ...
+end
 ```
-<% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %>
-<% /\A(\w+): (.+)/ =~ desc; if cat != $1; cat = 1 %>
-* <%= $1 %>
-<% cat = $1; end %>  * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %>
 
-## Debug command on the debug console
-
-* `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)
-
-You can use the following debug commands. Each command should be written in 1 line.
-The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
-The `<...>` notation means the argument.
-
-<%= DEBUGGER__.help %>
+On this case, you can see the result of `bar()` every time you stop there.
 
 ## rdbg command help
 
@@ -364,6 +471,7 @@ The `<...>` notation means the argument.
 # 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).