1- This tutorial introduces debugging C code with LLDB (the Low-Level Debugger)
2- via VS Code's Run and Debug functionality. It is also possible to use lldb
1+ This tutorial introduces debugging C code with LLDB (the Low-Level Debugger)
2+ via VS Code's Run and Debug functionality. It is also possible to use lldb
33to debug R via the command line using bash terminals in the R Dev Container.
44
55#### 1. Open an R Terminal Running R Built from Source
66
7- If necessary, run ` which_r ` to switch to a version of R you have built
7+ If necessary, run ` which_r ` to switch to a version of R you have built
88following the [ Building R] ( tutorials/building_r ) tutorial.
99
10- Then open an R terminal by clicking on ` R: (not attached) ` in the status bar,
10+ Then open an R terminal by clicking on ` R: (not attached) ` in the status bar,
1111or running ` R: Create R terminal ` from the VS Code command palette.
1212
1313<!-- markdownlint-disable MD046 -->
@@ -17,41 +17,41 @@ Debugging C code requires R to have been built with `CFLAGS="-g -O0"`.
1717
1818#### 2. Attach LLDB to the Running R Process
1919
20- Open the "Run and Debug" sidebar and click the green arrow next to the
21- drop-down box at the top. This will open a dialog for you to select the
20+ Open the "Run and Debug" sidebar and click the green arrow next to the
21+ drop-down box at the top. This will open a dialog for you to select the
2222process to attach the LLDB debugger to.
2323
2424[ screenshot here]
2525
26- Enter the process ID (PID) shown after the R version number in the status bar,
26+ Enter the process ID (PID) shown after the R version number in the status bar,
2727e.g. here the PID is [ TBA]
2828
2929[ screenshot here]
3030
3131<!-- markdownlint-disable MD046 -->
3232!!! Note
33- If you can't see the R version number in the status bar, you can get the PID
33+ If you can't see the R version number in the status bar, you can get the PID
3434 by calling ` Sys.getpid() ` in R before starting debugging.
3535<!-- markdownlint-enable MD046 -->
3636
3737#### 3. Set a Breakpoint in C Code
3838
39- For example, to debug the ` rlogis ` C function, open
40- ` $TOP_SRCDIR/src/nmath/rlogis.c ` and set a breakpoint by clicking to the left
41- of the line number corresponding to the first line in the body of the function:
39+ For example, to debug the ` rlogis ` C function, open
40+ ` $TOP_SRCDIR/src/nmath/rlogis.c ` and set a breakpoint by clicking to the left
41+ of the line number corresponding to the first line in the body of the function:
4242
4343![ alt text] ( ../assets/rdev26.png )
4444
4545#### 4. Trigger the Debugger
4646
47- In the R terminal, run the ` rlogis() ` command, which calls the ` rlogis ` C
47+ In the R terminal, run the ` rlogis() ` command, which calls the ` rlogis ` C
4848function:
4949
5050``` r
5151rlogis(1 )
5252```
5353
54- This will trigger the LLDB debugger and pause at the line where the
54+ This will trigger the LLDB debugger and pause at the line where the
5555breakpoint was added:
5656
5757[ new screenshot here]
@@ -61,28 +61,28 @@ breakpoint was added:
6161After pausing at a breakpoint, use the LLDB
6262toolbar buttons and commands to control execution:
6363
64- - ** Continue/Pause** (▷ in blue, or F5): Resume running until the next
65- breakpoint or the end of the call from R. This changes to a pause button
64+ - ** Continue/Pause** (▷ in blue, or F5): Resume running until the next
65+ breakpoint or the end of the call from R. This changes to a pause button
6666(⏸ in blue) when the code is running, allowing you to pause execution.
67- - ** Step Over** (↷ in blue, or F10): Run the current line of code and stop
67+ - ** Step Over** (↷ in blue, or F10): Run the current line of code and stop
6868at the next line.
69- - ** Step Into** (↓ in blue, or F11): Run the current line of code and step
69+ - ** Step Into** (↓ in blue, or F11): Run the current line of code and step
7070into the next function called to start debugging the code in that function.
71- - ** Step Out** (↑ in blue, or Shift+F11): Run the remainder of the current
72- function and stop at the point where the function was called. This will step
73- out through several internal C functions in the call stack - use
71+ - ** Step Out** (↑ in blue, or Shift+F11): Run the remainder of the current
72+ function and stop at the point where the function was called. This will step
73+ out through several internal C functions in the call stack - use
7474** Continue** instead to finish and return to R.
75- - ** Restart** (⟲ in green, or Cmd/Ctrl+Shift+F5): Start again from the
75+ - ** Restart** (⟲ in green, or Cmd/Ctrl+Shift+F5): Start again from the
7676beginning.
77- - ** Disconnect** (🔌 in red, or Shift+F5): Detach the debugger but keep R
77+ - ** Disconnect** (🔌 in red, or Shift+F5): Detach the debugger but keep R
7878running.
79- - ** Stop** (access from more controls): Teminate the debugging session and
79+ - ** Stop** (access from more controls): Teminate the debugging session and
8080the R process (closes the R terminal).
8181
8282#### 6. Inspect Variables and Expressions
8383
84- The Variables sub-panel of the Run and Debug side panel shows the current value
85- of variables in the current environment. This is particularly helpful for
84+ The Variables sub-panel of the Run and Debug side panel shows the current value
85+ of variables in the current environment. This is particularly helpful for
8686local variables defined in the function, e.g. before ` u ` is defined:
8787
8888[ screenshot]
@@ -91,14 +91,13 @@ and after
9191
9292[ screenshot]
9393
94- In the Watch sub-panel we can define expressions to watch as we step through
94+ In the Watch sub-panel we can define expressions to watch as we step through
9595the code. For example, we might watch ` u / (1 - u) ` and ` scale == 0 ` :
9696
9797[ screenshot]
9898
99- Note these expressions can only use simple operations, for example, we can't
100- watch ` log (u / (1 - u)) ` as this uses the ` log ` function.
99+ Note these expressions can only use simple operations, for example, we can't
100+ watch ` log (u / (1 - u)) ` as this uses the ` log ` function.
101101
102- The watch panel can also be used to dereference pointers (e.g. ` *ptr ` ) or
102+ The watch panel can also be used to dereference pointers (e.g. ` *ptr ` ) or
103103access elements of an array (e.g. ` array[5] ` ).
104-
0 commit comments