JRuby debugging support or documentation

[noahkawasakigoogle]

Filing an issue track and discuss JRuby debugging either interactively with a gem like pry or with a remote client as suggested in known issues.

bazel version: bazel 7.1.0- (@non-git)
Jruby version: jruby 9.4.13.0 (3.1.4) 2025-06-10 9938a3461f OpenJDK 64-Bit Server VM 11.0.23+0-adhoc..source on 11.0.23+0-adhoc..source +jit [x86_64-linux]

My attempts to get interactive JRuby debugging with bazel so far have not worked and I am wondering if anyone else has had any success. Either a simple pry session or a remote client would be great, so far I have not found any solution.

Attempts:

1. Use --run_under with extra jruby args --debug -S rdebug as recommended on JRuby docs.

# .bazelrc
test:rdebug --run_under="@ruby//:ruby --debug -S rdebug"
run:rdebug --run_under="@ruby//:ruby --debug -S rdebug"

> bazel run --config rdebug //...

SyntaxError in ...XXX_rb.sh:5: syntax error, unexpected local variable or method
set -uo pipefail; f=bazel_tools/tools/bash/run...
        ^~~~~~~~

I believe this fails because rb_binary and rb_test produce a shell script as the executable, and jruby --debug -S rdebug obviously cannot execute a shell script.

2. Directly use pry or pry-remote in source file and use bazel run instead of bazel test, which supposedly allows STDIN access as a workaround.

In ruby file:

require 'pry'
require 'pry-remote'

# anywhere in test file
binding.pry
binding.remote_pry

> bazel run //...

exec ${PAGER:-/usr/bin/less} "$0" || exit 1
Executing tests from //XXX
-----------------------------------------------------------------------------
Started with run options --seed 51274

SomeTest

  test_xxx                                     SKIP (2.14s)

 # hangs here and nothing else happens

In this case, it appears the binding.pry is successfully halting the program, however there is no ability to interact with pry session.

[noahkawasakigoogle]

Here is a workaround that works for me. We can build the test target as a binary and then directly execute it using bazel query to get all the needed data/args etc to create the correct command.

#! /usr/bin/env bash

# Usage: bazel-rdebug //target_name
#
# Put "binding.pry" or "debugger" in a .rb file in your target to open up a pry/debugger session
# interactively.
#
# Given any //ruby-gems target, we can use bazel query to get all needed info to re-create the
# bazel test execution and add in additional logic to enable a REPL debugger in a jruby bazel target.

set -eo pipefail

target=$1

# Get full label name in case someone uses a relative label from within a directory
target="$(bazel query "${target}" --output label)"

# Because we directly execute the executable, we must build every time to
# ensure hermeticity and that the executable is up to date.
bazel build "${target}"

# Require debugger gems at startup, this removes the need to add 'require gem_name' in a file
target_args+=(
  "${@:2}" # Pass through any other args given to JRuby
  "-rpry"
  "-rruby-debug"
  "--debug"
)

# Convert target name into its binary executable.
# The outputted executable file name is determined by language rules implementation.
target_binary="${target#\/\/}" # Strip //
target_binary="${target_binary//://}" # Replace : with / 
target_binary="${target_binary}.sh" # Add .sh 
target_runfiles_dir="${target_binary}.runfiles/WORKSPACE_NAME" < update this

# Parse args attr from target, we need to pass these into the binary
args_string=$(bazel query --output=build "${target}" | sed -n 's/.*args = \[\(.*\)\],/\1/p')
# Remove quotes and commas, then split into an array
IFS=', ' read -r -a _target_args <<< "${args_string//\"/}"

# Append target args to the end, the test_file needs to be last
target_args+=("${_target_args[@]}")

# Bazel test sets variables at execution time: https://bazel.build/reference/test-encyclopedia
# These are the only ones that matter for us to re-create test runtime (currently)
# The only variables that matter are the ones you reference in ruby source code.
bazel_bin="$(bazel info bazel-bin)"
export BAZEL_TEST="true"
export TEST_UNDECLARED_OUTPUTS_DIR="/tmp/bazel-out/test_undeclared_outputs_dir"
export TEST_TMPDIR="/tmp/bazel-out/tmpdir"
export TEST_TARGET="${target}"

# Go into runfiles dir
cd "${bazel_bin}/${target_runfiles_dir}" || exit 1

echo
echo "Running:"
echo "${bazel_bin}/${target_binary}" "${target_args[@]}"
echo

"${bazel_bin}/${target_binary}" "${target_args[@]}"