Byebug Documentation

Instead of starting the entire process with the byebug CLI, you can insert a breakpoint directly into your Ruby code or unit tests by calling the byebug method. This is useful for debugging specific parts of a larger application or within a test suite (like minitest).

To use this, ensure the byebug library is required (e.g., via ruby -rbyebug <file> or require 'byebug').

# Inside a method or test
def test_basic
  byebug
  solutions = []
  # ...
end

The edit command opens your preferred text editor at the current line of execution.

To configure which editor Byebug uses, set the EDITOR environment variable. The editor must support the +nnn file syntax to allow opening at a specific line.

Example (Bash):

export EDITOR=/usr/bin/vi
byebug ...

To verify the threading support implementation, you can run the specific thread command tests after installing dependencies and compiling the C-extension.

bundle install # Install dependencies
rake compile # Compile the C-extension
ruby -w -Ilib test/test_helper.rb test/commands/thread_test.rb

You can install Byebug as a standalone gem or add it to your project using Bundler.

Requirements:

• MRI 3.3.0 or higher.

Using gem:

gem install byebug

Using Bundler:

bundle add byebug --group "development, test"

Control program execution using breakpoints and inspect the execution context with the call stack:

• break <line_number>: Creates a breakpoint at the specified line. The program will stop just before this line is executed.
• continue or c: Resumes program execution until the next breakpoint is hit.
• where or bt: Shows the current call stack (backtrace), displaying the frame number, method name, parameters (with types), and file/line position.
• frame <number>: Moves the debugger context to a specific frame in the call stack.
• up / down: Moves through the call stack frames (implied by the frame and down examples).
• restart <args>: Restarts the program with the specified arguments.
• undisplay: Clears all display expressions.

(byebug) break 5
(byebug) continue
(byebug) where
(byebug) frame 2
(byebug) restart 3

Byebug allows you to customize how code and file paths are displayed during execution:

• set linetrace: Enables or disables line tracing (shows which lines are being executed).
• set basename: Enables or disables showing only the basename of files instead of full paths during tracing.
• set nofullpath: Toggles whether the debugger displays the full file path in the output.

(byebug) set linetrace
(byebug) set basename
(byebug) set nofullpath

You can debug a Ruby process from a different machine or a different terminal by setting up a remote server.

Step 1: Setup the server in your Ruby code Insert the following before the point you wish to debug:

require "byebug/core"
Byebug.wait_connection = true
Byebug.start_server("localhost", <port>)

Step 2: Connect from the client Run the following command from your local machine:

$ byebug -R localhost:<port>

Step 3: Trigger the breakpoint Add a standard byebug call in your code where you want the remote session to intercept execution.

If you want to debug a Ruby script without modifying the source code, you can invoke the byebug command followed by the script name.

byebug myscript.rb

When using Byebug's REPL, evaluating Ruby code that manipulates threads (like creating or switching threads) can cause deadlocks because Byebug holds a global lock.

To prevent this, Byebug uses an internal pattern to temporarily release the lock before evaluating user input. If you are extending Byebug or working with its internals, you can use the allowing_other_threads pattern to ensure the global lock is released during execution and re-acquired afterward.

def allowing_other_threads
  Byebug.unlock
  res = yield
  Byebug.lock
  res
end

Byebug supports debugging multi-threaded Ruby applications. You can inspect, switch, and control individual threads:

• thread list or th l: Lists all active threads, showing their ID, status (e.g., run or sleep), and current location.
• thread switch <id>: Switches the debugger context to the specified thread ID.
• thread stop <id>: Stops the execution of a specific thread. Stopped threads are marked with a $ symbol.
• thread resume <id>: Resumes the execution of a specific thread. Note: You must resume a sleeping thread before switching to it to avoid hanging the debugger.

Stopped threads are indicated by $ and the current active thread is indicated by + in the thread list output.

(byebug) th l
(byebug) th switch 3
(byebug) th stop 1
(byebug) th resume 2

To pause execution at a specific point in your Ruby code, simply insert the byebug command where you want the debugger to start. Once the execution reaches that line, you will receive a debugging prompt.

Example in a Rails controller:

def index
  byebug
  @articles = Article.find_recent
end

After adding the command, start your application (e.g., bin/rails s) to trigger the debugger.