Docs : documentation for LLDB debugging #268

avinab-neogy · 2025-08-11T11:11:58Z

Closes #196

hturner · 2025-08-11T14:50:02Z

docs/tutorials/debugging_with_lldb.md

+Rebuild R with debugging symbols so LLDB can access C source lines and
+variables. Make sure your build uses the `-g` flag. Open a bash terminal


They may have already built R with the correct CFLAGS. So here we can say something like:

Suggested change

Rebuild R with debugging symbols so LLDB can access C source lines and

variables. Make sure your build uses the `-g` flag. Open a bash terminal

If you have not yet built a version of R-devel, follow the [Building R](<link>) instructions, including the optional step to set `CFLAGS="-g -O0"`.

Otherwise, change to the build directory and check the `CFLAGS` configuration:

```bash

cd $BUILDDIR

R CMD config CFLAGS

```

If the output begins `-g 02`, you should reconfigure and rebuild R. Start from [Step 5](<link needed>) in the Building R tutorial.

Once you have a version of R-devel configured with `CFLAGS="-g -O0"`, use `which_r` to switch to this version.

You need to add the relevant links: "Step 5" should link to "5) Set CFLAGS (Optional—For Debugging C Code)" - you will need to add an anchor somehow, it may be easier to convert the item headers to proper HTML headings of the appropriate level.

Since we will update the docs to always use CFLAGS="-g -O0", we can delete this part. It is probably best to start with a step like:

#### 1. Switch to a built version of R Use `which_r` to switch to a version of R you have built in the devcontainer, e.g. `r-devel`.

and then go on to launch an R terminal, etc.

hturner · 2025-08-11T14:56:49Z

docs/tutorials/debugging_with_lldb.md

+and navigate to the root of your project’s source directory.
+
+```bash
+cd $TOP_SRCDIR
+```
+
+#### 2. Run R Using the Debug Wrapper Script
+
+Run R through the wrapper script (`launch_r.sh`) that
+sets up `LD_PRELOAD` and debugging environment:
+
+```bash
+./scripts/launch_r.sh
+```
+
+This ensures the ptrace helper library is loaded
+for debugging support.


The user does not have to do this, the way which_r updates the VS Code settings means that the launch_r script is run when they start an R terminal.

hturner · 2025-08-11T14:59:24Z

docs/tutorials/debugging_with_lldb.md

+Find the process ID (PID) of your R session. You
+can do this within R, Start an R terminal by using
+the command R in the terminal,then:


People should not run R in the bash terminal, they should start an R terminal, e.g. by clicking on R (not attached) or by using the Command Palette. We don't need to document how to start an R terminal as that is covered in an earlier tutorial.

Suggested change

Find the process ID (PID) of your R session. You

can do this within R, Start an R terminal by using

the command R in the terminal,then:

Start an R terminal and find the process ID (PID) of the R session using

hturner · 2025-08-11T15:12:58Z

docs/tutorials/debugging_with_lldb.md

+Attach LLDB to this PID, using the command palette type
+`LLDB: Attach to Process` then select the PID you just
+got or you can do this via the terminal:
+
+```bash
+lldb -p <PID>
+```


The aim is not to use lldb from the command line, but to use the LLDB extension as I demoed in our meeting the other week. So once you have the pid from R, go to the Run and Debug panel and click the green arrow (Start Debugging to launch the debugger (as defined in the launch.json file). This opens a dialog where you type in the pid to select the R process to attach to.

hturner · 2025-08-11T15:14:11Z

docs/tutorials/debugging_with_lldb.md

+You can do this by clicking the r
+ed dot on the left side
+of a line in a program as shown i
+n the screenshot below:


These lines should not be so narrow! it should be okay to have lines that are 80 characters width.

hturner · 2025-08-11T15:15:47Z

docs/tutorials/debugging_with_lldb.md

+of a line in a program as shown i
+n the screenshot below:
+
+![alt text](../assets/rdev26.png)


Screenshots should not use dark mode - ideally they would be take from GitHub Codespaces as that is the default interface, but of course that requires #267 to be merged in first, so using light mode locally should be okay.

hturner · 2025-08-11T15:17:27Z

docs/tutorials/debugging_with_lldb.md

+Use this command directly in the LLDB debug
+console to call the C function and see its
+result:
+
+```lldb
+expr (double)rlogis(1.0, 1.0)
+```


The idea is that we trigger the breakpoint from R. So within the R terminal, we type the R command

rlogis(1)

This R wrapper will call the C function and stop at the breakpoint in the C code.

hturner · 2025-08-11T15:24:10Z

docs/tutorials/debugging_with_lldb.md

+at the specified line for inspection as shown
+below.
+
+![alt text](../assets/rdev27.png)


When it is working correctly it should look like this:

hturner · 2025-08-11T18:49:37Z

docs/tutorials/debugging_with_lldb.md

+- **Stop Execution:** Pause the running process
+(interrupt command, icon may not always be shown).
+- **Additional Controls:**
+ack (↶ in blue) for reverse debugging
+    if available.
+t (⟲ in green) to restart the session.
+nect (🔗 in orange) to detach the debugger
+    while leaving the process running.


I would only document the buttons that are visible in the screenshot (so not Stop Execution or Back for reverse debugging).

As we are attaching to a running process, restart and disconnect have the same behaviour: they stop the debugger and return to R.

(Note you have some letters missing here).

It would be nice to use actual pictures of the buttons here. According to ChatGPT you could do this in markdown

Click the ![Menu Button](images/menu-button.png){: .icon } to open the menu.

Then in docs/css/custom.css (which should be included via extra_css in mkdocs.yml):

.icon { height: 20px; vertical-align: middle; }

hturner · 2025-08-11T21:33:08Z

docs/tutorials/debugging_with_lldb.md

+LLDB allows watching variables and
+evaluating expressions. For example,
+in the context of debugging `rlogis`,
+you can inspect the variable `u` or
+watch the result of an expression:
+
+```lldb
+expr u
+expr log(u / 1.0 - u)
+```
+
+The side panel or variable/watch
+window updates as you step through
+the code. Finally, when you exit
+the debugger using the disconnect
+button or te exit command, the
+screen shown below is displayed:


The idea here was to document the Watch panel in the Run and Debug panel on VS Code:

As you can see, you can watch simple expressions like u and u / (1.0 - u), but log(u/(1.0 - u) doesn't work in the watch panel as it can't find the log function. I was trying to find a way round this, but it's not that simple. So for now just document simple expressions.

When you exit the debugger (e.g. via disconnect) it should just finish running the command and return to the R terminal:

Added a page for lldb documentation

9461b8a

avinab-neogy requested a review from hturner August 11, 2025 11:12

hturner reviewed Aug 11, 2025

View reviewed changes

avinab-neogy self-assigned this Aug 28, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Docs : documentation for LLDB debugging #268

Docs : documentation for LLDB debugging #268

Uh oh!

avinab-neogy commented Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 12, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

hturner Aug 11, 2025

Uh oh!

Uh oh!

		Rebuild R with debugging symbols so LLDB can access C source lines and
		variables. Make sure your build uses the `-g` flag. Open a bash terminal

-Rebuild R with debugging symbols so LLDB can access C source lines and
-variables. Make sure your build uses the `-g` flag. Open a bash terminal
+If you have not yet built a version of R-devel, follow the [Building R](<link>) instructions, including the optional step to set `CFLAGS="-g -O0"`.
+Otherwise, change to the build directory and check the `CFLAGS` configuration:
+```bash
+cd $BUILDDIR
+R CMD config CFLAGS
+```
+If the output begins `-g 02`, you should reconfigure and rebuild R. Start from [Step 5](<link needed>) in the Building R tutorial.
+Once you have a version of R-devel configured with `CFLAGS="-g -O0"`, use `which_r` to switch to this version.

Docs : documentation for LLDB debugging #268

Are you sure you want to change the base?

Docs : documentation for LLDB debugging #268

Uh oh!

Conversation

avinab-neogy commented Aug 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!