debug 1.0.0.beta8 → 1.0.0.rc1

data/debug.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |spec|
   spec.extensions    = ['ext/debug/extconf.rb']
 
   spec.add_dependency "irb" # for its color_printer class, which was added after 1.3
+  spec.add_dependency "reline", ">= 0.2.7"
 end

data/exe/rdbg

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require_relative '../lib/debug/config'
-config = DEBUGGER__.parse_argv(ARGV)
+config = DEBUGGER__::Config::parse_argv(ARGV)
 
 case config[:mode]
 when :start
@@ -11,17 +11,14 @@ when :start
   start_mode = config[:remote] ? "open" : 'start'
   cmd = config[:command] ? ARGV.shift : RbConfig.ruby
 
-  env = ::DEBUGGER__.config_to_env_hash(config)
+  env = ::DEBUGGER__::Config.config_to_env_hash(config)
   env['RUBYOPT'] = "-r #{libpath}/#{start_mode}"
 
   exec(env, cmd, *ARGV)
 
 when :attach
   require_relative "../lib/debug/client"
-
-  config.each{|k, v|
-    DEBUGGER__::CONFIG[k] = v
-  }
+  ::DEBUGGER__::CONFIG.update config
 
   begin
     if ARGV.empty? && config[:port]

data/ext/debug/debug.c

@@ -22,7 +22,17 @@ static VALUE rb_cFrameInfo;
 static VALUE
 di_entry(VALUE loc, VALUE self, VALUE binding, VALUE iseq, VALUE klass, VALUE depth)
 {
-    return rb_struct_new(rb_cFrameInfo, loc, self, binding, iseq, klass, depth, Qnil, Qnil, Qnil, Qnil, Qnil);
+    return rb_struct_new(rb_cFrameInfo,
+                         // :location, :self, :binding, :iseq, :class, :frame_depth,
+                         loc, self, binding, iseq, klass, depth,
+                         // :has_return_value, :return_value,
+                         Qnil, Qnil,
+                         // :has_raised_exception, :raised_exception,
+                         Qnil, Qnil,
+                         // :show_line, :local_variables
+                         Qnil,
+                         // :_local_variables, :_callee # for recorder
+                         Qnil, Qnil);
 }
 
 static int

data/lib/debug/breakpoint.rb

@@ -82,6 +82,11 @@ module DEBUGGER__
     end
   end
 
+  if RUBY_VERSION.to_f <= 2.7
+    # workaround for https://bugs.ruby-lang.org/issues/17302
+    TracePoint.new(:line){}.enable{}
+  end
+
   class LineBreakpoint < Breakpoint
     attr_reader :path, :line, :iseq
 
@@ -113,7 +118,6 @@ module DEBUGGER__
           next unless safe_eval tp.binding, @cond
         end
         delete if @oneshot
-
         suspend
       end
     end
@@ -231,19 +235,25 @@ module DEBUGGER__
 
   class CatchBreakpoint < Breakpoint
     attr_reader :last_exc
+    include SkipPathHelper
 
-    def initialize pat
+    def initialize pat, cond: nil, command: nil
       @pat = pat.freeze
       @key = [:catch, @pat].freeze
       @last_exc = nil
 
+      @cond = cond
+      @command = command
+
       super()
     end
 
     def setup
       @tp = TracePoint.new(:raise){|tp|
+        next if skip_path?(tp.path)
         exc = tp.raised_exception
         next if SystemExit === exc
+        next if !safe_eval(tp.binding, @cond) if @cond
         should_suspend = false
 
         exc.class.ancestors.each{|cls|
@@ -278,8 +288,6 @@ module DEBUGGER__
       @tp = TracePoint.new(:line){|tp|
         next if tp.path.start_with? __dir__
         next if tp.path.start_with? '<internal:'
-        # Skip when `JSON.generate` is called during tests
-        next if tp.defined_class.to_s == '#<Class:JSON>' and ENV['RUBY_DEBUG_TEST_MODE']
 
         if safe_eval tp.binding, @expr
           suspend
@@ -340,15 +348,17 @@ module DEBUGGER__
   class MethodBreakpoint < Breakpoint
     attr_reader :sig_method_name, :method
 
-    def initialize b, klass_name, op, method_name, cond, command: nil
+    def initialize b, klass_name, op, method_name, cond: nil, command: nil
       @sig_klass_name = klass_name
       @sig_op = op
       @sig_method_name = method_name
       @klass_eval_binding = b
+      @override_method = false
 
       @klass = nil
       @method = nil
       @cond = cond
+      @cond_class = nil
       @command = command
       @key = "#{klass_name}#{op}#{method_name}".freeze
 
@@ -356,16 +366,13 @@ module DEBUGGER__
     end
 
     def setup
-      if @cond
-        @tp = TracePoint.new(:call){|tp|
-          next unless safe_eval tp.binding, @cond
-          suspend
-        }
-      else
-        @tp = TracePoint.new(:call){|tp|
-          suspend
-        }
-      end
+      @tp = TracePoint.new(:call){|tp|
+        next if !safe_eval(tp.binding, @cond) if @cond
+        next if @cond_class && !tp.self.kind_of?(@cond_class)
+        next if @override_method ? (caller_locations(2, 1).first.to_s.start_with?(__dir__)) : tp.path.start_with?(__dir__)
+
+        suspend
+      }
     end
 
     def eval_class_name
@@ -390,31 +397,57 @@ module DEBUGGER__
       try_enable
     end
 
+    if RUBY_VERSION.to_f <= 2.6
+      def override klass
+        sig_method_name = @sig_method_name
+        klass.prepend Module.new{
+          define_method(sig_method_name) do |*args, &block|
+            super(*args, &block)
+          end
+        }
+      end
+    else
+      def override klass
+        sig_method_name = @sig_method_name
+        klass.prepend Module.new{
+          define_method(sig_method_name) do |*args, **kw, &block|
+            super(*args, **kw, &block)
+          end
+        }
+      end
+    end
+
     def try_enable added: false
       eval_class_name
       search_method
 
       begin
         retried = false
+
         @tp.enable(target: @method)
         DEBUGGER__.warn "#{self} is activated." if added
 
+        if @sig_op == '#'
+          @cond_class = @klass if @method.owner != @klass
+        else # '.'
+          @cond_class = @klass.singleton_class if @method.owner != @klass.singleton_class
+        end
+
       rescue ArgumentError
         raise if retried
         retried = true
-        sig_method_name = @sig_method_name
 
         # maybe C method
-        @klass.module_eval do
-          orig_name = sig_method_name + '__orig__'
-          alias_method orig_name, sig_method_name
-          define_method(sig_method_name) do |*args|
-            send(orig_name, *args)
-          end
+        case @sig_op
+        when '.'
+          override @klass.singleton_class
+        when '#'
+          override @klass
         end
 
         # re-collect the method object after the above patch
         search_method
+        @override_method = true if @method
         retry
       end
     rescue Exception

data/lib/debug/client.rb

@@ -5,6 +5,7 @@ require 'io/console/size'
 
 require_relative 'config'
 require_relative 'version'
+require_relative 'console'
 
 # $VERBOSE = true
 
@@ -12,21 +13,11 @@ module DEBUGGER__
   class CommandLineOptionError < Exception; end
 
   class Client
-    begin
-      require 'readline'
-      def readline
-        Readline.readline("\n(rdbg:remote) ", true)
-      end
-    rescue LoadError
-      def readline
-        print "\n(rdbg:remote) "
-        gets
-      end
-    end
-
     def initialize argv
       return util(argv) if String === argv
 
+      @console = Console.new
+
       case argv.size
       when 0
         connect_unix
@@ -53,6 +44,10 @@ module DEBUGGER__
       send "version: #{VERSION} width: #{@width} cookie: #{CONFIG[:cookie]}"
     end
 
+    def readline
+      @console.readline "(rdbg:remote) "
+    end
+
     def util name
       case name
       when 'gen-sockpath'

data/lib/debug/color.rb

@@ -2,6 +2,13 @@
 
 begin
   require 'irb/color'
+
+  module IRB
+    module Color
+      DIM = 2 unless defined? DIM
+    end
+  end
+
   require "irb/color_printer"
 rescue LoadError
   warn "DEBUGGER: can not load newer irb for coloring. Write 'gem \"debug\" in your Gemfile."
@@ -24,7 +31,7 @@ module DEBUGGER__
     end
 
     if defined? IRB::ColorPrinter.pp
-      def color_pp obj, width = SESSION.width
+      def color_pp obj, width
         if !CONFIG[:no_color]
           IRB::ColorPrinter.pp(obj, "".dup, width)
         else
@@ -32,14 +39,14 @@ module DEBUGGER__
         end
       end
     else
-      def color_pp obj
+      def color_pp obj, width
         obj.pretty_inspect
       end
     end
 
-    def colored_inspect obj, no_color: false
+    def colored_inspect obj, width: SESSION.width, no_color: false
       if !no_color
-        color_pp obj
+        color_pp obj, width
       else
         obj.pretty_inspect
       end
@@ -72,5 +79,13 @@ module DEBUGGER__
     def colorize_blue(str)
       colorize(str, [:BLUE, :BOLD])
     end
+
+    def colorize_magenta(str)
+      colorize(str, [:MAGENTA, :BOLD])
+    end
+
+    def colorize_dim(str)
+      colorize(str, [:DIM])
+    end
   end
 end

data/lib/debug/config.rb

@@ -1,46 +1,23 @@
 # frozen_string_literal: true
 
 module DEBUGGER__
-  def self.unix_domain_socket_dir
-    case
-    when path = ::DEBUGGER__::CONFIG[:sock_dir]
-    when path = ENV['XDG_RUNTIME_DIR']
-    when home = ENV['HOME']
-      path = File.join(home, '.ruby-debug-sock')
-
-      case
-      when !File.exist?(path)
-        Dir.mkdir(path, 0700)
-      when !File.directory?(path)
-        raise "#{path} is not a directory."
-      end
-    else
-      raise 'specify RUBY_DEBUG_SOCK_DIR environment variable for UNIX domain socket directory.'
-    end
-
-    path
-  end
-
-  def self.create_unix_domain_socket_name_prefix(base_dir = unix_domain_socket_dir)
-    user = ENV['USER'] || 'ruby-debug'
-    File.join(base_dir, "ruby-debug-#{user}")
-  end
-
-  def self.create_unix_domain_socket_name(base_dir = unix_domain_socket_dir)
-    create_unix_domain_socket_name_prefix(base_dir) + "-#{Process.pid}"
-  end
-
   CONFIG_SET = {
     # UI setting
     log_level:      ['RUBY_DEBUG_LOG_LEVEL',      "UI: Log level same as Logger (default: WARN)",                   :loglevel],
     show_src_lines: ['RUBY_DEBUG_SHOW_SRC_LINES', "UI: Show n lines source code on breakpoint (default: 10 lines)", :int],
     show_frames:    ['RUBY_DEBUG_SHOW_FRAMES',    "UI: Show n frames on breakpoint (default: 2 frames)",            :int],
-    show_info_lines:['RUBY_DEBUG_SHOW_INFO_LINES',"UI: Show n lines on info command (default: 10 lines, 0 for unlimited)",   :int],
     use_short_path: ['RUBY_DEBUG_USE_SHORT_PATH', "UI: Show shoten PATH (like $(Gem)/foo.rb)",                      :bool],
-    skip_nosrc:     ['RUBY_DEBUG_SKIP_NOSRC',     "UI: Skip on no source code lines (default: false)",              :bool],
-    skip_path:      ['RUBY_DEBUG_SKIP_PATH',      "UI: Skip showing frames for given paths (default: [])",          :path],
     no_color:       ['RUBY_DEBUG_NO_COLOR',       "UI: Do not use colorize (default: false)",                       :bool],
     no_sigint_hook: ['RUBY_DEBUG_NO_SIGINT_HOOK', "UI: Do not suspend on SIGINT (default: false)",                  :bool],
+    no_reline:      ['RUBY_DEBUG_NO_RELINE',      "UI: Do not use Reline library (default: false)",                 :bool],
+
+    # control setting
+    skip_path:      ['RUBY_DEBUG_SKIP_PATH',      "CONTROL: Skip showing/entering frames for given paths (default: [])", :path],
+    skip_nosrc:     ['RUBY_DEBUG_SKIP_NOSRC',     "CONTROL: Skip on no source code lines (default: false)",              :bool],
+    keep_alloc_site:['RUBY_DEBUG_KEEP_ALLOC_SITE',"CONTROL: Keep allocation site and p, pp shows it (default: false)",   :bool],
+    postmortem:     ['RUBY_DEBUG_POSTMORTEM',     "CONTROL: Enable postmortem debug (default: false)",                   :bool],
+    parent_on_fork: ['RUBY_DEBUG_PARENT_ON_FORK', "CONTROL: Keep debugging parent process on fork (default: false)",     :bool],
+    sigdump_sig:    ['RUBY_DEBUG_SIGDUMP_SIG',    "CONTROL: Sigdump signal (default: disabled)"],
 
     # boot setting
     nonstop:        ['RUBY_DEBUG_NONSTOP',     "BOOT: Nonstop mode",                                                :bool],
@@ -58,188 +35,388 @@ module DEBUGGER__
 
   CONFIG_MAP = CONFIG_SET.map{|k, (ev, desc)| [k, ev]}.to_h.freeze
 
-  def self.config_to_env_hash config
-    CONFIG_MAP.each_with_object({}){|(key, evname), env|
-      env[evname] = config[key].to_s if config[key]
-    }
-  end
-
-  def self.parse_config_value name, valstr
-    return valstr unless valstr.kind_of? String
+  class Config
+    def self.config
+      @config
+    end
 
-    case CONFIG_SET[name][2]
-    when :bool
-      case valstr
-      when '1', 'true', 'TRUE', 'T'
-        true
-      else
-        false
+    def initialize argv
+      if self.class.instance_variable_defined? :@config
+        raise 'Can not make multiple configurations in one process'
       end
-    when :int
-      valstr.to_i
-    when :loglevel
-      if DEBUGGER__::LOG_LEVELS[s = valstr.to_sym]
-        s
-      else
-        raise "Unknown loglevel: #{valstr}"
-      end
-    when :path # array of String
-      valstr.split(/:/).map{|e|
-        if /\A\/(.+)\/\z/ =~ e
-          Regexp.compile $1
+
+      update self.class.parse_argv(argv)
+    end
+
+    def [](key)
+      config[key]
+    end
+
+    def []=(key, val)
+      set_config(key => val)
+    end
+
+    def set_config(**kw)
+      conf = config.dup
+      kw.each{|k, v|
+        if CONFIG_MAP[k]
+          conf[k] = parse_config_value(k, v) # TODO: ractor support
         else
-          e
+          raise "Unknown configuration: #{k}"
         end
       }
-    else
-      valstr
+
+      update conf
     end
-  end
 
-  def self.parse_argv argv
-    config = {
-      mode: :start,
-    }
-    CONFIG_MAP.each{|key, evname|
-      if val = ENV[evname]
-        config[key] = parse_config_value(key, val)
+    def append_config key, val
+      conf = self.config.dup
+
+      if CONFIG_SET[key]
+        if CONFIG_SET[key][2] == :path
+          conf[key] = [*conf[key], *parse_config_value(key, val)];
+        else
+          raise "not an Array type: #{key}"
+        end
+      else
+        raise "Unknown configuration: #{key}"
       end
-    }
-    return config if !argv || argv.empty?
 
-    require 'optparse'
-    require_relative 'version'
+      update conf
+    end
 
-    opt = OptionParser.new do |o|
-      o.banner = "#{$0} [options] -- [debuggee options]"
-      o.separator ''
-      o.version = ::DEBUGGER__::VERSION
+    def update conf
+      old_conf = self.class.instance_variable_get(:@config) || {}
 
-      o.separator 'Debug console mode:'
-      o.on('-n', '--nonstop', 'Do not stop at the beginning of the script.') do
-        config[:nonstop] = '1'
-      end
+      # TODO: Use Ractor.make_shareable(conf)
+      self.class.instance_variable_set(:@config, conf.freeze)
 
-      o.on('-e DEBUG_COMMAND', 'Execute debug command at the beginning of the script.') do |cmd|
-        config[:commands] ||= ''
-        config[:commands] += cmd + ';;'
+      # Post process
+      if_updated old_conf, conf, :keep_alloc_site do |_, new|
+        if new
+          require 'objspace'
+          ObjectSpace.trace_object_allocations_start
+        else
+          ObjectSpace.trace_object_allocations_stop
+        end
       end
 
-      o.on('-x FILE', '--init-script=FILE', 'Execute debug command in the FILE.') do |file|
-        config[:init_script] = file
-      end
-      o.on('--no-rc', 'Ignore ~/.rdbgrc') do
-        config[:no_rc] = true
-      end
-      o.on('--no-color', 'Disable colorize') do
-        config[:no_color] = true
-      end
-      o.on('--no-sigint-hook', 'Disable to trap SIGINT') do
-        config[:no_sigint_hook] = true
+      if_updated old_conf, conf, :postmortem do |_, new_p|
+        SESSION.postmortem = new_p
       end
 
-      o.on('-c', '--command', 'Enable command mode.',
-                              'The first argument should be a command name in $PATH.',
-                              'Example: \'rdbg -c bundle exec rake test\'') do
-        config[:command] = true
+      if_updated old_conf, conf, :sigdump_sig do |old_sig, new_sig|
+        setup_sigdump old_sig, new_sig
       end
+    end
 
-      o.separator ''
+    private def if_updated old_conf, new_conf, key
+      old, new = old_conf[key], new_conf[key]
+      yield old, new if old != new
+    end
 
-      o.on('-O', '--open', 'Start remote debugging with opening the network port.',
-                           'If TCP/IP options are not given,',
-                           'a UNIX domain socket will be used.') do
-        config[:remote] = true
-      end
-      o.on('--sock-path=SOCK_PATH', 'UNIX Doman socket path') do |path|
-        config[:sock_path] = path
-      end
-      o.on('--port=PORT', 'Listening TCP/IP port') do |port|
-        config[:port] = port
-      end
-      o.on('--host=HOST', 'Listening TCP/IP host') do |host|
-        config[:host] = host
+    private def enable_sigdump sig
+      @sigdump_sig_prev = trap(sig) do
+        str = []
+        str << "Simple sigdump on #{Process.pid}"
+        Thread.list.each{|th|
+          str << "Thread: #{th}"
+          th.backtrace.each{|loc|
+            str << "  #{loc}"
+          }
+          str << ''
+        }
+
+        STDERR.puts str
       end
-      o.on('--cookie=COOKIE', 'Set a cookie for connection') do |c|
-        config[:cookie] = c
+    end
+
+    private def disable_sigdump old_sig
+      trap(old_sig, @sigdump_sig_prev)
+      @sigdump_sig_prev = nil
+    end
+
+    # emergency simple sigdump.
+    # Use `sigdump` gem for more rich features.
+    private def setup_sigdump old_sig = nil, sig = CONFIG[:sigdump_sig]
+      if !old_sig && sig
+        enable_sigdump sig
+      elsif old_sig && !sig
+        disable_sigdump old_sig
+      elsif old_sig && sig
+        disable_sigdump old_sig
+        enable_sigdump sig
       end
+    end
 
-      rdbg = 'rdbg'
-
-      o.separator ''
-      o.separator '  Debug console mode runs Ruby program with the debug console.'
-      o.separator ''
-      o.separator "  '#{rdbg} target.rb foo bar'                starts like 'ruby target.rb foo bar'."
-      o.separator "  '#{rdbg} -- -r foo -e bar'                 starts like 'ruby -r foo -e bar'."
-      o.separator "  '#{rdbg} -c rake test'                     starts like 'rake test'."
-      o.separator "  '#{rdbg} -c -- rake test -t'               starts like 'rake test -t'."
-      o.separator "  '#{rdbg} -c bundle exec rake test'         starts like 'bundle exec rake test'."
-      o.separator "  '#{rdbg} -O target.rb foo bar'             starts and accepts attaching with UNIX domain socket."
-      o.separator "  '#{rdbg} -O --port 1234 target.rb foo bar' starts accepts attaching with TCP/IP localhost:1234."
-      o.separator "  '#{rdbg} -O --port 1234 -- -r foo -e bar'  starts accepts attaching with TCP/IP localhost:1234."
-
-      o.separator ''
-      o.separator 'Attach mode:'
-      o.on('-A', '--attach', 'Attach to debuggee process.') do
-        config[:mode] = :attach
+    private def config
+      self.class.config
+    end
+
+    private def parse_config_value name, valstr
+      self.class.parse_config_value name, valstr
+    end
+
+    def self.parse_config_value name, valstr
+      return valstr unless valstr.kind_of? String
+
+      case CONFIG_SET[name][2]
+      when :bool
+        case valstr
+        when '1', 'true', 'TRUE', 'T'
+          true
+        else
+          false
+        end
+      when :int
+        valstr.to_i
+      when :loglevel
+        if DEBUGGER__::LOG_LEVELS[s = valstr.to_sym]
+          s
+        else
+          raise "Unknown loglevel: #{valstr}"
+        end
+      when :path # array of String
+        valstr.split(/:/).map{|e|
+          if /\A\/(.+)\/\z/ =~ e
+            Regexp.compile $1
+          else
+            e
+          end
+        }
+      else
+        valstr
       end
+    end
+
+    def self.parse_argv argv
+      config = {
+        mode: :start,
+      }
+      CONFIG_MAP.each{|key, evname|
+        if val = ENV[evname]
+          config[key] = parse_config_value(key, val)
+        end
+      }
+      return config if !argv || argv.empty?
 
-      o.separator ''
-      o.separator '  Attach mode attaches the remote debug console to the debuggee process.'
-      o.separator ''
-      o.separator "  '#{rdbg} -A'           tries to connect via UNIX domain socket."
-      o.separator "  #{' ' * rdbg.size}                If there are multiple processes are waiting for the"
-      o.separator "  #{' ' * rdbg.size}                debugger connection, list possible debuggee names."
-      o.separator "  '#{rdbg} -A path'      tries to connect via UNIX domain socket with given path name."
-      o.separator "  '#{rdbg} -A port'      tries to connect to localhost:port via TCP/IP."
-      o.separator "  '#{rdbg} -A host port' tries to connect to host:port via TCP/IP."
-
-      o.separator ''
-      o.separator 'Other options:'
-
-      o.on("-h", "--help", "Print help") do
-        puts o
-        exit
+      if argv.kind_of? String
+        require 'shellwords'
+        argv = Shellwords.split(argv)
       end
 
-      o.on('--util=NAME', 'Utility mode (used by tools)') do |name|
-        require_relative 'client'
-        Client.new(name)
-        exit
+      require 'optparse'
+      require_relative 'version'
+
+      opt = OptionParser.new do |o|
+        o.banner = "#{$0} [options] -- [debuggee options]"
+        o.separator ''
+        o.version = ::DEBUGGER__::VERSION
+
+        o.separator 'Debug console mode:'
+        o.on('-n', '--nonstop', 'Do not stop at the beginning of the script.') do
+          config[:nonstop] = '1'
+        end
+
+        o.on('-e DEBUG_COMMAND', 'Execute debug command at the beginning of the script.') do |cmd|
+          config[:commands] ||= ''
+          config[:commands] += cmd + ';;'
+        end
+
+        o.on('-x FILE', '--init-script=FILE', 'Execute debug command in the FILE.') do |file|
+          config[:init_script] = file
+        end
+        o.on('--no-rc', 'Ignore ~/.rdbgrc') do
+          config[:no_rc] = true
+        end
+        o.on('--no-color', 'Disable colorize') do
+          config[:no_color] = true
+        end
+        o.on('--no-sigint-hook', 'Disable to trap SIGINT') do
+          config[:no_sigint_hook] = true
+        end
+
+        o.on('-c', '--command', 'Enable command mode.',
+                                'The first argument should be a command name in $PATH.',
+                                'Example: \'rdbg -c bundle exec rake test\'') do
+          config[:command] = true
+        end
+
+        o.separator ''
+
+        o.on('-O', '--open', 'Start remote debugging with opening the network port.',
+                             'If TCP/IP options are not given,',
+                             'a UNIX domain socket will be used.') do
+          config[:remote] = true
+        end
+        o.on('--sock-path=SOCK_PATH', 'UNIX Domain socket path') do |path|
+          config[:sock_path] = path
+        end
+        o.on('--port=PORT', 'Listening TCP/IP port') do |port|
+          config[:port] = port
+        end
+        o.on('--host=HOST', 'Listening TCP/IP host') do |host|
+          config[:host] = host
+        end
+        o.on('--cookie=COOKIE', 'Set a cookie for connection') do |c|
+          config[:cookie] = c
+        end
+
+        rdbg = 'rdbg'
+
+        o.separator ''
+        o.separator '  Debug console mode runs Ruby program with the debug console.'
+        o.separator ''
+        o.separator "  '#{rdbg} target.rb foo bar'                starts like 'ruby target.rb foo bar'."
+        o.separator "  '#{rdbg} -- -r foo -e bar'                 starts like 'ruby -r foo -e bar'."
+        o.separator "  '#{rdbg} -c rake test'                     starts like 'rake test'."
+        o.separator "  '#{rdbg} -c -- rake test -t'               starts like 'rake test -t'."
+        o.separator "  '#{rdbg} -c bundle exec rake test'         starts like 'bundle exec rake test'."
+        o.separator "  '#{rdbg} -O target.rb foo bar'             starts and accepts attaching with UNIX domain socket."
+        o.separator "  '#{rdbg} -O --port 1234 target.rb foo bar' starts accepts attaching with TCP/IP localhost:1234."
+        o.separator "  '#{rdbg} -O --port 1234 -- -r foo -e bar'  starts accepts attaching with TCP/IP localhost:1234."
+
+        o.separator ''
+        o.separator 'Attach mode:'
+        o.on('-A', '--attach', 'Attach to debuggee process.') do
+          config[:mode] = :attach
+        end
+
+        o.separator ''
+        o.separator '  Attach mode attaches the remote debug console to the debuggee process.'
+        o.separator ''
+        o.separator "  '#{rdbg} -A'           tries to connect via UNIX domain socket."
+        o.separator "  #{' ' * rdbg.size}                If there are multiple processes are waiting for the"
+        o.separator "  #{' ' * rdbg.size}                debugger connection, list possible debuggee names."
+        o.separator "  '#{rdbg} -A path'      tries to connect via UNIX domain socket with given path name."
+        o.separator "  '#{rdbg} -A port'      tries to connect to localhost:port via TCP/IP."
+        o.separator "  '#{rdbg} -A host port' tries to connect to host:port via TCP/IP."
+
+        o.separator ''
+        o.separator 'Other options:'
+
+        o.on("-h", "--help", "Print help") do
+          puts o
+          exit
+        end
+
+        o.on('--util=NAME', 'Utility mode (used by tools)') do |name|
+          require_relative 'client'
+          Client.new(name)
+          exit
+        end
+
+        o.separator ''
+        o.separator 'NOTE'
+        o.separator '  All messages communicated between a debugger and a debuggee are *NOT* encrypted.'
+        o.separator '  Please use the remote debugging feature carefully.'
       end
 
-      o.separator ''
-      o.separator 'NOTE'
-      o.separator '  All messages communicated between a debugger and a debuggee are *NOT* encrypted.'
-      o.separator '  Please use the remote debugging feature carefully.'
-    end
+      opt.parse!(argv)
 
-    opt.parse!(argv)
+      config
+    end
 
-    config
+    def self.config_to_env_hash config
+      CONFIG_MAP.each_with_object({}){|(key, evname), env|
+        unless config[key].nil?
+          case CONFIG_SET[key][2]
+          when :path
+            valstr = config[key].map{|e| e.kind_of?(Regexp) ? e.inspect : e}.join(':')
+          else
+            valstr = config[key].to_s
+          end
+          env[evname] = valstr
+        end
+      }
+    end
   end
 
-  CONFIG = ::DEBUGGER__.parse_argv(ENV['RUBY_DEBUG_OPT'])
+  CONFIG = Config.new ENV['RUBY_DEBUG_OPT']
 
-  def self.set_config kw
-    kw.each{|k, v|
-      if CONFIG_MAP[k]
-        CONFIG[k] = parse_config_value(k, v) # TODO: ractor support
-      else
-        raise "Unknown configuration: #{k}"
+  ## Unix domain socket configuration
+
+  def self.unix_domain_socket_dir
+    case
+    when path = CONFIG[:sock_dir]
+    when path = ENV['XDG_RUNTIME_DIR']
+    when home = ENV['HOME']
+      path = File.join(home, '.ruby-debug-sock')
+
+      case
+      when !File.exist?(path)
+        Dir.mkdir(path, 0700)
+      when !File.directory?(path)
+        raise "#{path} is not a directory."
       end
-    }
+    else
+      raise 'specify RUBY_DEBUG_SOCK_DIR environment variable for UNIX domain socket directory.'
+    end
+
+    path
   end
 
-  def self.append_config key, val
-    if CONFIG_SET[key]
-      if CONFIG_SET[key][2] == :path
-        CONFIG[key] = [*CONFIG[key], *parse_config_value(key, val)];
-      else
-        raise "not an Array type: #{key}"
+  def self.create_unix_domain_socket_name_prefix(base_dir = unix_domain_socket_dir)
+    user = ENV['USER'] || 'ruby-debug'
+    File.join(base_dir, "ruby-debug-#{user}")
+  end
+
+  def self.create_unix_domain_socket_name(base_dir = unix_domain_socket_dir)
+    create_unix_domain_socket_name_prefix(base_dir) + "-#{Process.pid}"
+  end
+
+  ## Help
+
+  def self.parse_help
+    helps = Hash.new{|h, k| h[k] = []}
+    desc = cat = nil
+    cmds = Hash.new
+
+    File.read(File.join(__dir__, 'session.rb')).each_line do |line|
+      case line
+      when /\A\s*### (.+)/
+        cat = $1
+        break if $1 == 'END'
+      when /\A      when (.+)/
+        next unless cat
+        next unless desc
+        ws = $1.split(/,\s*/).map{|e| e.gsub('\'', '')}
+        helps[cat] << [ws, desc]
+        desc = nil
+        max_w = ws.max_by{|w| w.length}
+        ws.each{|w|
+          cmds[w] = max_w
+        }
+      when /\A\s+# (\s*\*.+)/
+        if desc
+          desc << "\n" + $1
+        else
+          desc = $1
+        end
       end
-    else
-      raise "Unknown configuration: #{key}"
     end
+    @commands = cmds
+    @helps = helps
+  end
+
+  def self.helps
+    (defined?(@helps) && @helps) || parse_help
+  end
+
+  def self.commands
+    (defined?(@commands) && @commands) || (parse_help; @commands)
+  end
+
+  def self.help
+    r = []
+    self.helps.each{|cat, cmds|
+      r << "### #{cat}"
+      r << ''
+      cmds.each{|ws, desc|
+        r << desc
+      }
+      r << ''
+    }
+    r.join("\n")
   end
 end