Merge pull request #769 from posit-dev/feature/c-debug

Expose helpers for C/C++/Rust debuggers

Author: lionel-

Cargo.lock

@@ -69,6 +69,7 @@ stdext = { path = "../stdext", features = ["testing"] }
 tempfile = "3.13.0"
 
 [build-dependencies]
+cc = "1.0"
 chrono = "0.4.23"
 embed-resource = "2.5.0"
 

crates/ark/Cargo.toml

@@ -59,4 +59,7 @@ fn main() {
         .join("manifest")
         .join("ark-manifest.rc");
     embed_resource::compile_for_everything(resource, embed_resource::NONE);
+
+    println!("cargo:rerun-if-changed=src/debug.c");
+    cc::Build::new().file("src/debug.c").compile("debug");
 }

crates/ark/build.rs

@@ -0,0 +1,28 @@
+// Define `SEXP` as opaque struct. This replaces a dependency on `Rinternals.h`.
+typedef struct SEXPREC *SEXP;
+
+// C entry points that are visible to debuggers like lldb.
+// To ensure these functions are linked in, these must be called from
+// `_placeholder()` in `utils.rs`. The actual implementations live in
+// `debug.rs`.
+
+const char* ark_print_rs(SEXP x);
+const char* ark_inspect_rs(SEXP x);
+const char* ark_trace_back_rs();
+const char* ark_display_value_rs(SEXP x);
+
+const char* ark_print(SEXP x) {
+    return ark_print_rs(x);
+}
+
+const char* ark_inspect(SEXP x) {
+    return ark_inspect_rs(x);
+}
+
+const char* ark_trace_back() {
+    return ark_trace_back_rs();
+}
+
+const char* ark_display_value(SEXP x) {
+    return ark_display_value_rs(x);
+}

crates/ark/src/debug.c

@@ -0,0 +1,202 @@
+use std::ffi;
+use std::sync::atomic::Ordering;
+
+use harp::exec::RFunction;
+use harp::exec::RFunctionExt;
+use harp::utils::r_str_to_owned_utf8_unchecked;
+use harp::utils::r_typeof;
+
+use crate::interface::RMain;
+use crate::interface::CAPTURE_CONSOLE_OUTPUT;
+
+// To ensure the compiler includes the C entry points in `debug.c` in the binary,
+// we store function pointers in global variables that are declared "used" (even
+// though we never actually use them). The compiler is able to follow the chain
+// of dependency from these variables to the C functions and ultimately their
+// Rust implementations defined below.
+extern "C" {
+    fn ark_print(x: libr::SEXP) -> *const ffi::c_char;
+    fn ark_inspect(x: libr::SEXP) -> *const ffi::c_char;
+    fn ark_trace_back() -> *const ffi::c_char;
+    fn ark_display_value(x: libr::SEXP) -> *const ffi::c_char;
+}
+
+#[used]
+static _ARK_PRINT: unsafe extern "C" fn(x: libr::SEXP) -> *const ffi::c_char = ark_print;
+#[used]
+static _ARK_INSPECT: unsafe extern "C" fn(x: libr::SEXP) -> *const ffi::c_char = ark_inspect;
+#[used]
+static _ARK_TRACE_BACK: unsafe extern "C" fn() -> *const ffi::c_char = ark_trace_back;
+#[used]
+static _ARK_DISPLAY_VALUE: unsafe extern "C" fn(x: libr::SEXP) -> *const ffi::c_char =
+    ark_display_value;
+
+// Implementations for entry points in `debug.c`.
+
+#[no_mangle]
+pub extern "C-unwind" fn ark_print_rs(x: libr::SEXP) -> *const ffi::c_char {
+    capture_console_output(|| {
+        unsafe { libr::Rf_PrintValue(x) };
+    })
+}
+
+/// Inspect structure of R object
+///
+/// Uses lobstr's `sxp()` function because libr can't find `R_inspect()`.
+/// It's an `attribute_hidden` function but since the symbol is visible
+/// on macOS (and you can call it in the debugger) I would have expected
+/// libr to be able to find it.
+///
+/// Requires lldb setting:
+///
+/// ```
+/// settings set escape-non-printables false
+/// ```
+#[no_mangle]
+pub extern "C-unwind" fn ark_inspect_rs(x: libr::SEXP) -> *const ffi::c_char {
+    capture_console_output(|| {
+        // TODO: Should use C callable when implemented as that would avoid
+        // messing with namedness and refcounts:
+        // https://github.com/r-lib/lobstr/issues/77
+        let out = RFunction::new("lobstr", "sxp").add(x).call().unwrap();
+        unsafe { libr::Rf_PrintValue(out.sexp) };
+    })
+}
+
+/// Print backtrace via rlang
+///
+/// Requires lldb setting:
+///
+/// ```
+/// settings set escape-non-printables false
+/// ```
+#[no_mangle]
+pub extern "C-unwind" fn ark_trace_back_rs() -> *const ffi::c_char {
+    capture_console_output(|| {
+        // https://github.com/r-lib/rlang/issues/1059
+        unsafe {
+            let fun =
+                get_c_callable_int(c"rlang".as_ptr(), c"rlang_print_backtrace".as_ptr()).unwrap();
+            fun(1);
+        };
+    })
+}
+
+#[no_mangle]
+pub extern "C-unwind" fn ark_display_value_rs(x: libr::SEXP) -> *const ffi::c_char {
+    let value = unsafe {
+        let kind = tidy_kind(r_typeof(x));
+        let tag = format!("<{kind}>");
+
+        match r_typeof(x) {
+            libr::SYMSXP => format!(
+                "{tag} ({name})",
+                name = r_str_to_owned_utf8_unchecked(libr::PRINTNAME(x))
+            ),
+            // TODO: Show some values (not with ALTREP objects as that could
+            // materialise or cause side effects)
+            libr::LGLSXP |
+            libr::INTSXP |
+            libr::REALSXP |
+            libr::CPLXSXP |
+            libr::RAWSXP |
+            libr::STRSXP |
+            libr::VECSXP |
+            libr::SPECIALSXP |
+            libr::BUILTINSXP |
+            libr::PROMSXP => {
+                format!("{tag} [{len}]", len = libr::Rf_xlength(x))
+            },
+
+            _ => tag,
+        }
+    };
+
+    ffi::CString::new(value).unwrap().into_raw()
+}
+
+pub fn tidy_kind(kind: libr::SEXPTYPE) -> &'static str {
+    match kind {
+        libr::NILSXP => "null",
+        libr::SYMSXP => "sym",
+        libr::LISTSXP => "list",
+        libr::CLOSXP => "fn",
+        libr::ENVSXP => "env",
+        libr::PROMSXP => "prom",
+        libr::LANGSXP => "call",
+        libr::SPECIALSXP => "special",
+        libr::BUILTINSXP => "builtin",
+        libr::CHARSXP => "char",
+        libr::LGLSXP => "lgl",
+        libr::INTSXP => "int",
+        libr::REALSXP => "dbl",
+        libr::CPLXSXP => "cpl",
+        libr::STRSXP => "chr",
+        libr::DOTSXP => "dots",
+        libr::ANYSXP => "any",
+        libr::VECSXP => "list",
+        libr::EXPRSXP => "expr",
+        libr::BCODESXP => "bcode",
+        libr::EXTPTRSXP => "extptr",
+        libr::WEAKREFSXP => "weakref",
+        libr::RAWSXP => "raw",
+        libr::S4SXP => "s4",
+        libr::NEWSXP => "new",
+        libr::FREESXP => "free",
+        libr::FUNSXP => "fun",
+        _ => "unknown",
+    }
+}
+
+/// Run closure and capture its console output.
+///
+/// Useful for debugging. For instance you can use this to call code from the C
+/// debugger's interpreter. Output from stdout and stderr is returned instead of
+/// being sent over IOPub.
+///
+/// The closure is run in a `harp::try_catch()` context to prevent R errors and
+/// other C longjumps from collapsing the debugging context. If a Rust panic
+/// occurs however, it is propagated as normal.
+///
+/// Note that the resulting string is stored on the Rust heap and never freed.
+/// This should only be used in a debugging context where leaking is not an
+/// issue.
+pub fn capture_console_output(cb: impl FnOnce()) -> *const ffi::c_char {
+    let old = CAPTURE_CONSOLE_OUTPUT.swap(true, Ordering::SeqCst);
+
+    // We protect from panics to correctly restore `CAPTURE_CONSOLE_OUTPUT`'s
+    // state. The panic is resumed right after.
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| harp::try_catch(cb)));
+
+    CAPTURE_CONSOLE_OUTPUT.store(old, Ordering::SeqCst);
+    let mut out = std::mem::take(&mut RMain::get_mut().captured_output);
+
+    // Unwrap catch-unwind's result and resume panic if needed
+    let result = match result {
+        Ok(res) => res,
+        Err(err) => {
+            std::panic::resume_unwind(err);
+        },
+    };
+
+    // Unwrap try-catch's result
+    if let Err(err) = result {
+        out = format!("{out}\nUnexpected longjump in `capture_console_output()`: {err:?}");
+    }
+
+    // Intentionally leaks, should only be used in the debugger
+    ffi::CString::new(out).unwrap().into_raw()
+}
+
+// Cast `DL_FUNC` to correct function type
+fn get_c_callable_int(
+    pkg: *const std::ffi::c_char,
+    fun: *const std::ffi::c_char,
+) -> Option<unsafe extern "C-unwind" fn(std::ffi::c_int) -> *mut std::ffi::c_void> {
+    unsafe {
+        std::mem::transmute::<
+            Option<unsafe extern "C-unwind" fn() -> *mut std::ffi::c_void>,
+            Option<unsafe extern "C-unwind" fn(std::ffi::c_int) -> *mut std::ffi::c_void>,
+        >(libr::R_GetCCallable(pkg, fun))
+    }
+}

crates/ark/src/debug.rs

@@ -16,6 +16,8 @@ use std::collections::HashMap;
 use std::ffi::*;
 use std::os::raw::c_uchar;
 use std::result::Result::Ok;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
 use std::sync::Arc;
 use std::sync::Mutex;
 use std::task::Poll;
@@ -125,6 +127,7 @@ use crate::sys::console::console_to_utf8;
 use crate::ui::UiCommMessage;
 use crate::ui::UiCommSender;
 
+pub static CAPTURE_CONSOLE_OUTPUT: AtomicBool = AtomicBool::new(false);
 static RE_DEBUG_PROMPT: Lazy<Regex> = Lazy::new(|| Regex::new(r"Browse\[\d+\]").unwrap());
 
 /// An enum representing the different modes in which the R session can run.
@@ -236,6 +239,10 @@ pub struct RMain {
     /// Raw error buffer provided to `Rf_error()` when throwing `r_read_console()` errors.
     /// Stored in `RMain` to avoid memory leakage when `Rf_error()` jumps.
     r_error_buffer: Option<CString>,
+
+    /// `WriteConsole` output diverted from IOPub is stored here. This is only used
+    /// to return R output to the debugger.
+    pub(crate) captured_output: String,
 }
 
 /// Represents the currently active execution request from the frontend. It
@@ -567,6 +574,7 @@ impl RMain {
             pending_lines: Vec::new(),
             banner: None,
             r_error_buffer: None,
+            captured_output: String::new(),
         }
     }
 
@@ -1668,6 +1676,13 @@ impl RMain {
 
     /// Invoked by R to write output to the console.
     fn write_console(buf: *const c_char, _buflen: i32, otype: i32) {
+        if CAPTURE_CONSOLE_OUTPUT.load(Ordering::SeqCst) {
+            RMain::get_mut()
+                .captured_output
+                .push_str(&console_to_utf8(buf).unwrap());
+            return;
+        }
+
         let content = match console_to_utf8(buf) {
             Ok(content) => content,
             Err(err) => panic!("Failed to read from R buffer: {err:?}"),

crates/ark/src/interface.rs

@@ -12,6 +12,7 @@ pub mod control;
 pub mod coordinates;
 pub mod dap;
 pub mod data_explorer;
+pub mod debug;
 pub mod errors;
 pub mod fixtures;
 pub mod help;

crates/ark/src/lib.rs

@@ -41,6 +41,9 @@ functions::generate! {
         externalRoutines: *const R_ExternalMethodDef
     ) -> std::ffi::c_int;
 
+    pub fn R_GetCCallable(pkg: *const std::ffi::c_char, fun: *const std::ffi::c_char) ->
+        DL_FUNC;
+
     pub fn vmaxget() -> *mut std::ffi::c_void;
 
     pub fn vmaxset(arg1: *const std::ffi::c_void);