debug 1.0.0.alpha1 → 1.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c921a03e7629b04e9629e77c5c6dac3adfa4acb33f4f72d325315a358d07058c
-  data.tar.gz: eac06881f18621e16ac00f7ce628ff64c5aa7b60d99b725cdc30528e4c41b399
+  metadata.gz: '039bd2cbfdb3a67bbd91603b077a4f4784235fb0c7b48721a4b9f27b493231c6'
+  data.tar.gz: f9605d076dff9d8571e70245baa5c2e97c2377cc7f92ee627cbc1f051361217b
 SHA512:
-  metadata.gz: 299218c5bbfa513df144365e8172ae270a681b3e8e0ab6b7953834d99454947c1a31ce2f6f9aa85b3ae798ac501ea8e4f8892deabf96ca835cb35112fd26a54b
-  data.tar.gz: cac005fa02d12e187f586b2718d27d0c1463d03219a050102c9767540692cd609666cd6ea65db83a3bda54471c4a5ff10f06e1305b8ec013d5735b2633a2eebe
+  metadata.gz: f222a8b1ec58fd6f5264e61ee8613e6ed229c9ebff73c6b4904c4c6c2bded0d625b776fb510b23dec57636cf576a68d471f0b91d7b01d36f8baad741ff64fd38
+  data.tar.gz: 152431ba38203334bbf1c7449ff36a6d49f5116aaa78c017ca5ffa6d695ca87be06bc011822d0bbd325e15c46504385adf4ef94e74ebd37f97468f049da910e8

data/.github/workflows/ruby.yml

@@ -0,0 +1,34 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0', 'head', 'debug']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -6,3 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.bundle
+/Gemfile.lock
+/lib/debug/debug.so
+.ruby-version

data/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+## Set Up a Development Environment
+
+1. `$ git clone git@github.com:ruby/debug.git`
+2. `$ bundle install`
+3. `$ rake` - this will
+    - Compile the C extension locally (which can also be done solely with `rake compile`).
+    - Run tests.
+    - Re-generate `README.md`.
+
+If you spot any problem, please open an issue.
+
+## Run Tests
+
+### Run all tests
+
+```bash
+$ rake test
+# or
+$ ruby bin/test-unit.rb
+```
+
+### Run specific test(s)
+
+
+```bash
+$ 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
+```
+
+## To Update README
+
+This project generates `README.md` from the template `misc/README.md.erb`
+
+So **do not** directly update `README.md`. Instead, you should update the template's source and run
+
+```bash
+$ rake
+```
+
+to reflect the changes on `README.md`.
+
+
+### When to re-generate `README.md`
+
+- After updating `misc/README.md.erb`.
+- After updating `rdbg` executable's options.
+- After updating comments of debugger's commands.
+
+## Manually Test Your Changes
+
+You can manually test your changes with a simple Ruby script + a line of command. The following example will help you check:
+
+- Breakpoint insertion.
+- Resume from the breakpoint.
+- Backtrace display.
+- Information (local variables, ivars..etc.) display.
+- Debugger exit.
+
+
+### Script
+
+```ruby
+# target.rb
+class Foo
+  def first_call
+    second_call(20)
+  end
+
+  def second_call(num)
+    third_call_with_block do |ten|
+      forth_call(num, ten)
+    end
+  end
+
+  def third_call_with_block(&block)
+    @ivar1 = 10; @ivar2 = 20
+
+    yield(10)
+  end
+
+  def forth_call(num1, num2)
+    num1 + num2
+  end
+end
+
+Foo.new.first_call
+```
+
+### Command
+
+```
+$ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
+```
+
+### Expect Result
+
+```
+❯ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
+[1, 10] in target.rb
+=>    1| class Foo
+      2|   def first_call
+      3|     second_call(20)
+      4|   end
+      5|
+      6|   def second_call(num)
+      7|     third_call_with_block do |ten|
+      8|       forth_call(num, ten)
+      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
+     15|     yield(10)
+     16|   end
+     17|
+     18|   def forth_call(num1, num2)
+     19|     num1 + num2
+=>   20|   end
+     21| end
+     22|
+     23| Foo.new.first_call
+=>#0    Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
+  #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
+=>#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
+  #3    Foo#second_call(num=20) at target.rb:7
+  #4    first_call at target.rb:3
+  #5    <main> at target.rb:23
+(rdbg:init) 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!
+```

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem "rake"
+gem "rake-compiler"
+gem "test-unit", "~> 3.0"

data/LICENSE.txt

@@ -1,21 +1,22 @@
-The MIT License (MIT)
+Copyright (C) 1993-2013 Yukihiro Matsumoto. All rights reserved.
 
-Copyright (c) 2021 Koichi Sasada
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README.md

@@ -1,86 +1,335 @@
+[![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)
+
 # debug.rb
 
-## How to install
+This library provides debugging functionality to Ruby.
+
+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:
+
+* Fast: No performance penalty on non-stepping mode and non-breakpoints.
+* Remote debugging: Support remote debugging natively.
+  * UNIX domain socket
+  * TCP/IP
+  * VSCode/DAP integration (TODO)
+* Extensible: application can introduce debugging support with several methods
+  * By `rdbg` command
+  * By loading libraries with `-r` command line option
+  * By calling Ruby's method explicitly
+* Misc
+  * 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.
+
+# Installation
 
 ```
-$ gem install debug
+$ gem install debug --pre
 ```
 
-or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line options for development.
+or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
 
 # How to use
 
 ## Invoke with debugger
 
-### REPL debug
+You can run ruby program on debugger with the local debug console or the remote debug console.
+
+* (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
+
+(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.
+
+To use debugging feature, you can have 3 ways.
+
+* (1) Use `rdbg` command
+* (2) Use `ruby -r debug...` command line option
+* (3) Write `require 'debug...'` in .rb files
+
+### Local debug console
+
+#### (1) Use `rdbg` command
 
 ```
-$ ruby -r debug/repl target.rb
+$ rdbg target.rb
+$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
 ```
 
-and you can see the debugger prompt. The program was suspended at the beggining of target.rb. To continue the program, type `c` (or `continue`). See other debug commands below.
+#### (2) Use `-r debug/run` command line option
+
+```
+$ ruby -r debug/run target.rb
+```
+
+#### (3) Write `require 'debug...'` in .rb files
+
+```ruby
+# target.rb
+require 'debug/run' # start the debug console
 
-You can re-enable debug command mode by `Ctrl-C`.
+# or
+
+require 'debug/session'  # introduce the functionality
+DEBUGGER__.console       # and start the debug console
+# ... rest of program ...
+```
+
+```
+$ ruby target.rb
+```
+
+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`.
+
+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`.
+
+The following example shows simple usage of the debug console. You can show the all variables
+
+```
+$ rdbg  ~/src/rb/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>'
+
+(rdbg) info                                             # Show all local variables
+ %self => main
+ a => nil
+ b => nil
+ c => nil
+
+(rdbg) p a                                              # Same as p(a)
+=> nil
+
+(rdbg) s                                                # Step in ("s" is a short name of "step")
+
+[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")
+
+[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>'
+
+(rdbg)                                                  # Repeat the last command ("step")
+
+[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]
+```
 
 ### Remote debug (1) UNIX domain socket
 
+#### (1) Use `rdbg` command
+
+```
+$ 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)
+```
+
+#### (2) Use `-r debug/open` command line option
+
 ```
-$ ruby -r debug/unixserver target.rb
+$ ruby -r debug/open target.rb
+Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
+```
+
+#### (3) Write `require 'debug/open'` in .rb files
+
+```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)
 ```
 
 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:
 
-You can attach the program with the folliowing command:
+```
+$ 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 attach the program with the following command:
 
 ```
-$ ruby -r debug/client -e connect
-Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-20642)
-...
+$ 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)
 ```
 
-The debugee process will be suspended and wait for the debug command.
+and you can input any debug commands. `c` (or `continue`) continues the debuggee process.
+
+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).
+
+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.
 
-If you are running multiple debuggee processes, this command shows the selection like that:
+* Use `rdbg -n` option
+* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
+
+If you are running multiple debuggee processes, the attach command (`rdbg -A`) shows the options like that:
 
 ```
-$ ruby -r debug/client -e connect
+$ rdbg --attach
 Please select a debug session:
   ruby-debug-ko1-19638
   ruby-debug-ko1-19603
 ```
 
-and you need to specify one:
+and you need to specify one (copy and paste the name):
 
 ```
-$ ruby -r debug/client -e connect ruby-debug-ko1-19638
+$ rdbg --attach ruby-debug-ko1-19638
 ```
 
 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.
+* `$HOME/.ruby-debug-sock` if `$HOME` is available.
 
 ### Remote debug (2) TCP/IP
 
+You can open the TCP/IP port instead of using UNIX domain socket.
+
+#### (1) Use `rdbg` command
+
 ```
-$ RUBY_DEBUG_PORT=12345 RUBY_DEBUG_HOST=localhost ruby -r debug/tcpserver target.rb
+$ rdbg -O --port=12345 target.rb
+# or
+$ rdbg --open --port=12345 target.rb
 Debugger can attach via TCP/IP (localhost:12345)
-...
 ```
 
-This command invoke target.rb with TCP/IP attach server with given port and host. If host is not given, `localhost` will be used. 
+#### (2) Use `-r debug/open` command line option
+
 
 ```
-$ ruby -r debug/client -e connect localhost 12345
+$ RUBY_DEBUG_PORT=12345 ruby -r debug/open target.rb
+Debugger can attach via TCP/IP (localhost:12345)
+```
+
+#### (3) Write `require 'debug/open'` in .rb files
+
+```ruby
+# target.rb
+require 'debug/open' # open the debugger entry point.
 ```
 
-tries to connect with given host (`localhost`) and port (`12345`). You can eliminate host part and `localhost` will be used.
+and run with environment variable RUBY_DEBUG_PORT
 
+```
+$ RUBY_DEBUG_PORT=12345 ruby target.rb
+Debugger can attach via TCP/IP (localhost:12345)
+```
 
-## Debug command
+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)
+```
+
+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.
+
+To attach the debuggee process, specify the port number (and hostname if needed) for the `rdbg --attach` (or `rdbg -A`) command.
+
+```
+$ rdbg --attach 12345
+$ rdbg --attach hostname 12345
+```
+
+### 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 are `.rdbgrc.rb` files at the current directory and the home directory, files are loaded as a ruby script at the initializing timing.
+
+### Environment variables
+
+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.
+
+## 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.
 
 ### Control flow
 
@@ -93,9 +342,13 @@ tries to connect with given host (`localhost`) and port (`12345`). You can elimi
 * `c[ontinue]`
   * Resume the program.
 * `q[uit]` or `Ctrl-D`
-  * Finish debugger (with a process, if not remote debugging).
+  * Finish debugger (with the debuggee process on non-remote debugging).
+* `q[uit]!`
+  * Same as q[uit] but without the confirmation prompt.
 * `kill`
-  * Stop the debuggee program.
+  * Stop the debuggee process with `Kernal#exit!`.
+* `kill!`
+  * Same as kill but without the confirmation prompt.
 
 ### Breakpoint
 
@@ -103,27 +356,69 @@ tries to connect with given host (`localhost`) and port (`12345`). You can elimi
   * Show all breakpoints.
 * `b[reak] <line>`
   * Set breakpoint on `<line>` at the current frame's file.
-* `b[reak] <file>:<line>`
+* `b[reak] <file>:<line>` or `<file> <line>`
   * Set breakpoint on `<file>:<line>`.
+* `b[reak] <class>#<name>`
+   * Set breakpoint on the method `<class>#<name>`.
+* `b[reak] <expr>.<name>`
+   * Set breakpoint on the method `<expr>.<name>`.
+* `b[reak] ... if <expr>`
+  * break if `<expr>` is true at specified location.
+* `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>`.
+* `watch @ivar`
+  * Stop the execution when the result of current scope's `@ivar` is changed.
+  * Note that this feature is super slow.
 * `del[ete]`
   * delete all breakpoints.
 * `del[ete] <bpnum>`
   * delete specified breakpoint.
 
-### Frame control
+### Information
 
 * `bt` or `backtrace`
-  * Show backtrace information.
+  * Show backtrace (frame) information.
+* `l[ist]`
+  * Show current frame's source code.
+  * Next `list` command shows the successor lines.
+* `l[ist] -`
+  * Show predecessor lines as opposed to the `list` command.
+* `l[ist] <start>` or `l[ist] <start>-<end>`
+  * Show current frame's source code from the line <start> to <end> if given.
+* `edit`
+  * Open the current file on the editor (use `EDITOR` environment variable).
+  * Note that edited file will not be reloaded.
+* `edit <file>`
+  * Open <file> on the editor.
+* `i[nfo]`, `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] th[read[s]]`
+  * Show all threads (same as `th[read]`).
+* `display`
+  * Show display setting.
+* `display <expr>`
+  * Show the result of `<expr>` at every suspended timing.
+* `undisplay`
+  * Remove all display settings.
+* `undisplay <displaynum>`
+  * Remove a specified display setting.
+* `trace [on|off]`
+  * enable or disable line tracer.
+
+### Frame control
+
 * `f[rame]`
-  * Show current frame.
+  * Show the current frame.
 * `f[rame] <framenum>`
-  * Specify frame. Evaluation are run on this frame environement.
+  * Specify a current frame. Evaluation are run on specified frame.
 * `up`
-  * Specify upper frame.
+  * Specify the upper frame.
 * `down`
-  * Specify down frame.
+  * Specify the lower frame.
 
 ### Evaluate
 
@@ -133,30 +428,79 @@ tries to connect with given host (`localhost`) and port (`12345`). You can elimi
   * Evaluate like `pp <expr>` on the current frame.
 * `e[val] <expr>`
   * Evaluate `<expr>` on the current frame.
-
-### Information
-
-* `list`
-  * Show current frame's source code.
-* `info l[ocal[s]]`
-  * Show current frame's local variables. It includes `self` as `%self` and a return value as `%return`.
-* `info i[nstance]` or `info ivars`
-  * Show current frame's insntance variables.
-* `display`
-  * Show display setting.
-* `display <expr>`
-  * Add `<expr>` at suspended timing.
-* `undisplay`
-  * Remove all display settings.
-* `undisplay <displaynum>`
-  * Remove a specified display setting.
-* `trace [on|off]`
-  * enable or disable line tracer.
+* `irb`
+  * Invoke `irb` on the current frame.
 
 ### Thread control
 
-* `th[read] [l[ist]]`
+* `th[read]`
   * Show all threads.
 * `th[read] <thnum>`
-  * Switch thread specified by `<thnum>`
+  * Switch thread specified by `<thnum>`.
+
+### Help
+
+* `h[elp]`
+  * Show help for all commands.
+* `h[elp] <command>`
+  * Show help for the given command.
+
+
+## rdbg command help
+
+```
+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.
+
+    -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
+        --port=PORT                  Listening TCP/IP port
+        --host=HOST                  Listening TCP/IP host
+        --cookie=COOKIE              Set a cookie for connection
+
+  Debug console mode runs Ruby program with the debug console.
+
+  '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 -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.
+
+Attach mode:
+    -A, --attach                     Attach to debuggee process.
+
+  Attach mode attaches the remote debug console to the debuggee process.
+
+  'rdbg -A'           tries to connect via UNIX domain socket.
+                      If there are multiple processes are waiting for the
+                      debugger connection, list possible debuggee names.
+  'rdbg -A path'      tries to connect via UNIX domain socket with given path name.
+  'rdbg -A port'      tries to connect to localhost:port via TCP/IP.
+  'rdbg -A host port' tries to connect to host:port via TCP/IP.
+
+Other options:
+    -h, --help                       Print help
+    -c, --command                    Command mode (first argument is command name)
+        --util=NAME                  Utility mode (used by tools)
+
+NOTE
+  All messages communicated between a debugger and a debuggee are *NOT* encrypted.
+  Please use the remote debugging feature carefully.
+
+```
+
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
+
+Please also check the [contributing guideline](/CONTRIBUTING.md).
+
+# Acknowledgement
 
+* Some tests are based on [deivid-rodriguez/byebug: Debugging in Ruby 2](https://github.com/deivid-rodriguez/byebug)