debug 1.0.0.beta2 → 1.0.0.beta7

data/lib/debug/version.rb

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

data/misc/README.md.erb

@@ -1,3 +1,5 @@
+[![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
 
 This library provides debugging functionality to Ruby.
@@ -9,7 +11,7 @@ New debug.rb has several advantages:
 * Remote debugging: Support remote debugging natively.
   * UNIX domain socket
   * TCP/IP
-  * VSCode/DAP integration (TODO)
+  * 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
   * By `rdbg` command
   * By loading libraries with `-r` command line option
@@ -27,6 +29,16 @@ $ gem install debug --pre
 
 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.
+
+```
+gem "debug", ">= 1.0.0.beta"
+```
+
+```
+$ rdbg -c bundle exec ruby target.rb
+```
+
 # How to use
 
 ## Invoke with debugger
@@ -49,33 +61,54 @@ To use debugging feature, you can have 3 ways.
 
 ### Local debug console
 
+#### (1) Use `rdbg` command
+
 ```
-# (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
+#### (2) Use `-r debug/run` command line option
 
+```
 $ ruby -r debug/run target.rb
+```
 
-# (3) Write `require 'debug...' in .rb files
+#### (3) Write `require 'debug...'` in .rb files
 
-$ cat target.rb
+```ruby
+# target.rb
 require 'debug/run' # start the debug console
-...
 
-# or
+# ... rest of program ...
+```
 
-$ cat target.rb
-require 'debug/session'  # introduce the functionality
-DEBUGGER__.console       # and start the debug console
 
+```
 $ 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`.
 
+
+Alternatively, start the debugger at a specific location in your program using `binding.break` (`binding.b` for short).
+
+```ruby
+# target.rb
+require 'debug' # start the debugger
+
+# ... program ...
+
+binding.break # setup a breakpoint at this line
+
+# ... rest of program ...
+```
+
+```
+$ ruby 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`.
 
@@ -143,33 +176,36 @@ $ rdbg  ~/src/rb/target.rb
 
 ### Remote debug (1) UNIX domain socket
 
+#### (1) Use `rdbg` command
+
 ```
-# (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
+#### (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
 
-# (3) Write `require 'debug/open' in .rb files
-$ cat target.rb
+```ruby
+# 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.
@@ -233,40 +269,49 @@ The socket file is located at
 
 You can open the TCP/IP port instead of using UNIX domain socket.
 
+#### (1) Use `rdbg` command
+
 ```
-# (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
 
-# (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
 
-# (3) Write `require 'debug/open' in .rb files
-$ cat target.rb
+```ruby
+# target.rb
 require 'debug/open' # open the debugger entry point.
-...
+```
 
-# and run with environment variable RUBY_DEBUG_PORT
+and run with environment variable RUBY_DEBUG_PORT
+
+```
 $ RUBY_DEBUG_PORT=12345 ruby target.rb
 Debugger can attach via TCP/IP (localhost:12345)
-...
+```
 
-# or
+or
 
-$ cat target.rb
+```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.
@@ -280,26 +325,23 @@ $ 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`, 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` files at the current directory and the home directory, files are loaded as a ruby script at the initializing timing.
+If there are `~/.rdbgrc.rb` is available, it is loaded as a ruby script at same timing.
 
-### Environment variables
+### Configurations
 
-You can control debuggee's behavior with environment variables:
+You can configure debugger's setting with environment variables and `config` command.
+You can write any configuration into `~/.rdbgrc` like:
 
-* `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_DIR`: UNIX Domain Socket remote debugging: socket directory to open.
+```
+config set log_level INFO
+config set no_color true
+```
+<% 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
 
@@ -322,3 +364,9 @@ The `<...>` notation means the argument.
 # 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)

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: debug
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0.beta7
 platform: ruby
 authors:
 - Koichi Sasada
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-10 00:00:00.000000000 Z
-dependencies: []
+date: 2021-07-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Debugging functionality for Ruby. This is completely rewritten debug.rb
   which was contained by the encient Ruby versions.
 email:
@@ -20,12 +34,16 @@ extensions:
 - ext/debug/extconf.rb
 extra_rdoc_files: []
 files:
+- ".github/workflows/ruby.yml"
 - ".gitignore"
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - bin/console
+- bin/gentest
 - bin/setup
 - debug.gemspec
 - exe/rdbg
@@ -36,11 +54,14 @@ files:
 - lib/debug/bp.vim
 - lib/debug/breakpoint.rb
 - lib/debug/client.rb
+- lib/debug/color.rb
 - lib/debug/config.rb
 - lib/debug/console.rb
+- lib/debug/frame_info.rb
 - lib/debug/open.rb
 - lib/debug/run.rb
 - lib/debug/server.rb
+- lib/debug/server_dap.rb
 - lib/debug/session.rb
 - lib/debug/source_repository.rb
 - lib/debug/thread_client.rb