A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://github.com/ruby/debug below:

ruby/debug: Debugging functionality for Ruby

This library provides debugging functionality to Ruby (MRI) 2.7 and later.

This debug.rb is the replacement of traditional lib/debug.rb standard library, which is implemented by set_trace_func. New debug.rb has several advantages:

Alternatively, specify -Ipath/to/debug/lib in RUBYOPT, or as a Ruby command-line option This is especially useful for debugging this gem during development.

If using Bundler, add the following to your Gemfile:

(The version constraint is important; debug < 1.0.0 is an older, abandoned gem that is completely different from this product.)

To use the debugger, you will do roughly 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.

There are several ways to invoke the debugger, depending on your needs, preferences, and the environment.

Modify source code with binding.break (similar to binding.pry or binding.irb)

If you can modify the source code, you can use the debugger by adding require 'debug' at the top of your program and putting binding.break method into lines where you want to stop as breakpoints. This is similar to how binding.pry and binding.irb work.

binding.break has two aliases which do the same thing:

After that, run the program as usual and you will enter the debug console at breakpoints you inserted.

The following is an example of the binding.break method.

$ 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 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 use the rdbg command (or bundle exec rdbg) to run the program with the debugger. This is similar to how you'd launch a program with ruby program.rb. Then you can set breakpoints with the debug command break (b for short).

$ 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

(rdbg)

The rdbg command suspends the program at the beginning of the given script (target.rb in this case) and you can use debug commands to control execution from there. (rdbg) is the console prompt. Let's set breakpoints on line 3 and line 5 with break command (b for short).

(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)

You can see that two breakpoints are registered. Let's continue the program by using the continue command.

(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

Stop by #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)

(rdbg)

You can see that we stopped at line 3. Let's see the local variables with the info command, and continue execution with the continue. The program will then suspend at line 5 and you can use the info command again.

(rdbg) info
=>#0    <main> at target.rb:3
%self => main
a => 1
b => 2
c => nil
d => nil

(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

Stop by #1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)

(rdbg) info
=>#0    <main> at target.rb:5
%self => main
a => 1
b => 2
c => 3
d => 4

(rdbg) continue
[1, 2, 3, 4]

NOTE: When using rdbg you can suspend your application with C-c (SIGINT) and enter the debug console. It will help if you want to know what the program is doing.

Use rdbg with commands written in Ruby

If you want to run an executable written in Ruby like rake, rails, bundle, rspec, and so on, you can use rdbg -c option.

Examples:

NOTE: -- is needed to separate the command line options for rdbg from the executable being invoked, and its options. For example, rdbg -c rake -T would be parsed as rdbg -c -T -- rake, which is incorrect. It should be rdbg -c -- rake -T.

NOTE: If you want to use Bundler (bundle executable), you need to add gem 'debug' to your Gemfile.

Like other languages, you can use this debugger on the VSCode.

  1. Install VSCode rdbg Ruby Debugger - Visual Studio Marketplace
  2. Open .rb file (e.g. target.rb)
  3. Register breakpoints with "Toggle breakpoint" in the 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 you want to run.
  6. Chosen command line is invoked with rdbg -c, and VSCode shows the details at breakpoints.

Please refer to Debugging in Visual Studio Code for operations on VSCode.

You can configure the extension in .vscode/launch.json. Please see the extension page for more details.

You can use this debugger as a remote debugger. For example, it will help in the following situations:

You can run your application as a remote debuggee, and the remote debugger console can attach to the debuggee anytime.

Invoke as a remote debuggee

There are multiple ways to run your program as a debuggee:

Stop at program start rdbg option require debugger API Yes rdbg --open require "debug/open" DEBUGGER__.open No rdbg --open --nonstop require "debug/open_nonstop" DEBUGGER__.open(nonstop: true) rdbg --open (or rdbg -O for short)

Launch a script with rdbg --open target.rb to run target.rb as a debuggee program. It also opens the network port and suspends at the beginning of target.rb.

$ 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...

By default, rdbg --open uses UNIX domain socket and generates the 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).

$ rdbg -A
[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

(rdbg:remote)

If there are no other files in the default directory, rdbg --attach will automatically connect to the UNIX domain socket listed. If there are multiple files, you need to specify which to use.

When rdbg --attach connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console. When a debuggee program exits, the remote console will also terminate.

NOTE: If you use the quit command, only the 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.

If you want to use TCP/IP for remote debugging, you need to specify the port and host with --port like rdbg --open --port 12345 and it binds to localhost:12345. You can add an optional --port_range to try multiple ports in a reliable way. For example, rdbg --open --port 12345 --port_range 10 will try to bind to 12345, 12346, 12347,… until it finds an available port.

To connect to the debuggee, you need to specify the port.

If you want to choose the host to bind, you can use --host option. Messages communicated between the debugger and the debuggee are NOT encrypted so please use remote debugging carefully.

require 'debug/open' in a program

If you can modify the program, you can open the debugging port by adding require 'debug/open' in the program.

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 dangerous because it can become another vulnerability. Please use it carefully.

By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the RUBY_DEBUG_PORT environment variable.

$ RUBY_DEBUG_PORT=12345 ruby target.rb
Integration with external debugger frontend

You can attach with external debugger frontend with VSCode and Chrome.

$ rdbg --open=[frontend] target.rb

This will open a debug port and the [frontend] can attach to the port.

(vscode-rdbg v0.0.9 or later is required)

If you don't run a debuggee Ruby process on VSCode, you can attach it to VSCode later with the following steps.

rdbg --open=vscode opens the debug port and tries to invoke the VSCode (code executable).

$ rdbg --open=vscode target.rb
DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-27706)
DEBUGGER: wait for debugger connection...
Launching: code /tmp/ruby-debug-vscode-20211014-27706-gd7e85/ /tmp/ruby-debug-vscode-20211014-27706-gd7e85/README.rb
DEBUGGER: Connected.

It tries to invoke the new VSCode window and VSCode will attach to the debuggee Ruby program automatically.

You can also use open vscode in a REPL.

$ rdbg target.rb
[1, 8] in target.rb
     1|
=>   2| p a = 1
     3| p b = 2
     4| p c = 3
     5| p d = 4
     6| p e = 5
     7|
     8| __END__
=>#0    <main> at target.rb:2
(rdbg) open vscode    # command
DEBUGGER: wait for debugger connection...
DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-28337)
Launching: code /tmp/ruby-debug-vscode-20211014-28337-kg9dm/ /tmp/ruby-debug-vscode-20211014-28337-kg9dm/README.rb
DEBUGGER: Connected.

If the machine which runs the Ruby process doesn't have a code executable on $PATH, the following message will be shown:

(rdbg) open vscode
DEBUGGER: wait for debugger connection...
DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-455)
Launching: code /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb
DEBUGGER: Can not invoke the command.
Use the command-line on your terminal (with modification if you need).

  code /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb

If your application is running on a SSH remote host, please try:

  code --remote ssh-remote+[SSH hostname] /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb

Note that you can attach with rdbg --attach and continue REPL debugging.

Chrome DevTool integration

Using rdbg --open=chrome will show the following message:

$ rdbg target.rb --open=chrome
DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633)
DEBUGGER: With Chrome browser, type the following URL in the address-bar:

   devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef

DEBUGGER: wait for debugger connection...

Type the following in the address bar on Chrome browser, and you can continue the debugging with chrome browser:

devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef`

Similar to VSCode, you can use open chrome to open the debugger in Chrome.

For more information about how to use Chrome debugging, see the devtools docs.

You can configure the debugger's behavior with debug commands and environment variables. When the debug session is started, some initialization scripts (e.g., ~/.rdbgrc) are loaded, allowing you to configure the debugger's behavior to your needs and preferences.

You can configure the debugger's behavior with environment variables and config command. Each configuration has an environment variable and a name which can be specified by config command.

# configuration example
config set log_level INFO
config set no_color true

There are other environment variables:

If there is a ~/.rdbgrc file it is loaded as an initialization script (which contains debug commands) when the debug session is started.

Initial scripts are useful to write your favorite configurations. For example, you can set breakpoints with break file:123 in ~/.rdbgrc.

If there is a ~/.rdbgrc.rb file it is also loaded as a Ruby script when the debug session is started.

Debug command on the debug console

On the debug console, you can use the following debug commands.

There are additional features:

You can use the following debug commands. Each command should be written in 1 line. The […] notation means this part can be eliminated. For example, s[tep] means s or step is a valid command. ste is not valid. The <…> notation means the argument.

Using IRB as the Debug Console

Starting from version v1.9, you can now use IRB as the debug console. This integration brings additional features such as:

To switch to the IRB console, simply use the irb command in the debug console.

Once activated, you'll notice the prompt changes to:

If you want to make IRB the default console for all sessions, configure the irb_console setting by either:

To disable the IRB console in the current session, execute config set irb_console 0 in the console.

Start by requiring a library

You can start debugging without rdbg command by requiring the following libraries:

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.

NOTE: Until Ruby 3.0, there is old lib/debug.rb in the standard library. 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.

So, if this gem is not installed, or if the Gemfile doesn't include this gem and bundle exec is used, you will see the following output:

$ 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.

.../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)

After loading debug/session, you can start a debug session with the following methods. They are convenient if you want to specify debug configurations in your program.

For example:

require 'debug/session'
DEBUGGER__.start(no_color: true,    # disable colorize
                 log_level: 'INFO') # Change log_level to INFO

... # your application code

binding.break (or binding.b) sets a breakpoint at that line. It also has several keywords.

If do: 'command' is specified, the debugger suspends the program, runs the command as a debug command, and continues the program. It is useful if you only want to call a debug command and don't want to stop there. For example:

def initialize
  @a = 1
  binding.b do: 'info \n watch @a'
end

In this case, execute the info command, then register a watch breakpoint for @a and continue to run. You can also use ;; instead of \n to separate your commands.

If pre: 'command' is specified, the debugger suspends the program and runs the command as a debug command, and keeps suspended. It is useful if you have operations before suspend. For example:

def foo
  binding.b pre: 'p bar()'
  ...
end

In this case, you can see the result of bar() every time you stop there.

exe/rdbg [options] -- [debuggee options]

Debug console mode:
    -n, --nonstop                    Do not stop at the beginning of the script.
    -e DEBUG_COMMAND                 Execute debug command at the beginning of the script.
    -x, --init-script=FILE           Execute debug command in the FILE.
        --no-rc                      Ignore ~/.rdbgrc
        --no-color                   Disable colorize
        --no-sigint-hook             Disable to trap SIGINT
    -c, --command                    Enable command mode.
                                     The first argument should be a command name in $PATH.
                                     Example: 'rdbg -c bundle exec rake test'

    -O, --open=[FRONTEND]            Start remote debugging with opening the network port.
                                     If TCP/IP options are not given, a UNIX domain socket will be used.
                                     If FRONTEND is given, prepare for the FRONTEND.
                                     Now rdbg, vscode and chrome is supported.
        --sock-path=SOCK_PATH        UNIX Domain socket path
        --port=PORT                  Listening TCP/IP port
        --port-range=PORT_RANGE      Number of ports to try to connect to
        --host=HOST                  Listening TCP/IP host
        --cookie=COOKIE              Set a cookie for connection
        --session-name=NAME          Session name

  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 -c rake test'                     starts like 'rake test'.
  'rdbg -c -- rake test -t'               starts like 'rake test -t'.
  'rdbg -c bundle exec rake test'         starts like 'bundle exec rake test'.
  '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.
  'rdbg target.rb -O chrome --port 1234'  starts and accepts connecting from Chrome Devtools with 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:
    -v                               Show version number
        --version                    Show version number and exit
    -h, --help                       Print help
        --util=NAME                  Utility mode (used by tools)
        --stop-at-load               Stop immediately when the debugging feature is loaded.

NOTE
  All messages communicated between a debugger and a debuggee are *NOT* encrypted.
  Please use the remote debugging feature carefully.

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.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4