debug 1.0.0.alpha1 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c921a03e7629b04e9629e77c5c6dac3adfa4acb33f4f72d325315a358d07058c
-  data.tar.gz: eac06881f18621e16ac00f7ce628ff64c5aa7b60d99b725cdc30528e4c41b399
+  metadata.gz: 99f9de5fc37782d330788a745b34666e07d37c9e168eb7b0361d3b51b8247b56
+  data.tar.gz: 3e6941a9b066ec0965e576b87c8e0cc0bc787571fa5331ca962d906611c368e5
 SHA512:
-  metadata.gz: 299218c5bbfa513df144365e8172ae270a681b3e8e0ab6b7953834d99454947c1a31ce2f6f9aa85b3ae798ac501ea8e4f8892deabf96ca835cb35112fd26a54b
-  data.tar.gz: cac005fa02d12e187f586b2718d27d0c1463d03219a050102c9767540692cd609666cd6ea65db83a3bda54471c4a5ff10f06e1305b8ec013d5735b2633a2eebe
+  metadata.gz: a279de53e047d52c18c0b1c726da4bbf6efbd116f2957f3fa1c106fec929bb0dc903274d9fce8bb03a787f7ca31edd09d54a09b572027485c5a985205e518582
+  data.tar.gz: 5c436bdfa54ab8d2ece8c07fdac31481f0a9e4922ac433e871c09dd0b161d812eaf7c417189e0e9582421d8405a5169ec826065930c3a7441fdd72953c2786de

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/Gemfile.lock

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rake-compiler"
+gem "minitest", "~> 5.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,315 @@
 # 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
 
 ```
-$ ruby -r debug/repl target.rb
+# (1) Use `rdbg` command
+$ rdbg target.rb
+$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
+
+# (2) Use `-r debug/run` command line option
+
+$ ruby -r debug/run target.rb
+
+# (3) Write `require 'debug...' in .rb files
+
+$ cat target.rb
+require 'debug/run' # start the debug console
+...
+
+# or
+
+$ cat target.rb
+require 'debug/session'  # introduce the functionality
+DEBUGGER__.console       # and start the debug console
+
+$ ruby target.rb
 ```
 
-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.
+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 beggining of `target.rb`.
 
-You can re-enable debug command mode by `Ctrl-C`.
+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                                                # Contineu the program ("c" is a short name of "continue")
+[6]
+```
 
 ### Remote debug (1) UNIX domain socket
 
 ```
-$ ruby -r debug/unixserver target.rb
+# (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/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
+$ cat target.rb
+require 'debug/open' # open the debugger entry point by UNIX domain socket.
+...
+
+# or
+
+$ cat target.rb
+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 beggining of `target.rb` like that:
+
+```
+$ 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 debuger connection...
+```
 
-You can attach the program with the folliowing command:
+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 beggining of debuggee process (`target.rb`), you can use the fowllowings 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.
+
 ```
-$ RUBY_DEBUG_PORT=12345 RUBY_DEBUG_HOST=localhost ruby -r debug/tcpserver target.rb
+# (1) Use `rdbg` command
+$ rdbg -O --port=12345 target.rb
+# or
+$ rdbg --open --port=12345 target.rb
+Debugger can attach via TCP/IP (localhost:12345)
+...
+
+# (2) Use `-r debug/open` command line option
+
+$ 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
+$ cat 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)
+...
+
+# or
+
+$ cat 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)
 ...
 ```
 
-This command invoke target.rb with TCP/IP attach server with given port and host. If host is not given, `localhost` will be used. 
+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.
 
 ```
-$ ruby -r debug/client -e connect localhost 12345
+$ rdbg --attach 12345
+$ rdbg --attach hostname 12345
 ```
 
-tries to connect with given host (`localhost`) and port (`12345`). You can eliminate host part and `localhost` will be used.
+### 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 evaluted at the first suspend timing (generally, it is the beggining of the target script). For example, you can set break points with `break file:123`.
 
-## Debug command
+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 beggining 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_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 elimiante. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
+The `<...>` notation means the argument.
 
 ### Control flow
 
@@ -92,10 +321,10 @@ tries to connect with given host (`localhost`) and port (`12345`). You can elimi
   * Finish this frame. Resume the program until the current frame is finished.
 * `c[ontinue]`
   * Resume the program.
-* `q[uit]` or `Ctrl-D`
-  * Finish debugger (with a process, if not remote debugging).
-* `kill`
-  * Stop the debuggee program.
+* `q[uit]` or exit or `Ctrl-D`
+  * Finish debugger (with the debuggee process on non-remote debugging).
+* `kill` or `q[uit]!`
+  * Stop the debuggee process.
 
 ### Breakpoint
 
@@ -103,19 +332,61 @@ 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 <expr>`
+  * Stop the execution when the result of <expr> 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 editted file will not be reloaded.
+* `edit <file>`
+  * Open <file> on the editor.
+* `i[nfo]`
+  * Show information about the current frame (local variables)
+  * It includes `self` as `%self` and a return value as `%return`.
+* `i[nfo] <expr>`
+  * Show information about the result of <expr>.
+* `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.
 * `f[rame] <framenum>`
@@ -133,30 +404,61 @@ 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 beggining of the script.
+    -e [COMMAND]                     execute debug command at the beggining of the script.
+    -O, --open                       Start debuggee with opning the debagger port.
+                                     If TCP/IP options are not given,
+                                     a UNIX domain socket will be used.
+        --port=[PORT]                Listening TCP/IP port
+        --host=[HOST]                Listening TCP/IP host
+
+  Debug console mode runs Ruby program with the debug console.
+
+  exe/rdbg target.rb foo bar                 starts like 'ruby target.rb foo bar'.
+  exe/rdbg -- -r foo -e bar                  starts like 'ruby -r foo -e bar'.
+  exe/rdbg -O target.rb foo bar              starts and accepts attaching with UNIX domain socket.
+  exe/rdbg -O --port 1234 target.rb foo bar  starts accepts attaching with TCP/IP localhost:1234.
+  exe/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.
+
+  'exe/rdbg -A' tries to connect via UNIX domain socket.
+                      If there are multiple processes are waiting for the
+                      debugger connection, list possible debuggee names.
+  'exe/rdbg -A path' tries to connect via UNIX domain socket with given path name.
+  'exe/rdbg -A port' tries to connect localhost:port via TCP/IP.
+  'exe/rdbg -A host port' tris to connect host:port via TCP/IP.
+
+```
+
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.