Wikipedia donations style note: Because of delays with my scholarship payment, if this post is useful to you I kindly ask a minimal donation on Buy Me a Coffee. It shall be used to continue my Open Source efforts. The full explanation is here: A Personal Message from an Open Source Contributor.

Adapted from Debugging Rcpp with VSCode. Thanks a lot to Mr. Jinyang Liu for the original post!

For reference, I am using a Thinkpad X1 with the following R version:

> sessionInfo()
R version 4.5.1 (2025-06-13)
Platform: x86_64-pc-linux-gnu
Running under: Manjaro Linux

Matrix products: default
BLAS/LAPACK: /usr/lib/libopenblas.so.0.3;  LAPACK version 3.12.0

< section id="configure-vscode-for-c" class="level1">

Configure VSCode for C++

Install VSCode if you haven’t already. Add the following extensions:

• C/C++ Extension Pack
• R
• CodeLLB

CodeLLB is the debugger you shall use to debug C++ code.

< section id="create-an-r-package" class="level1">

Create an R package

To debug C++ code with cpp11armadillo, you shall need to wrap your code in an R package.

Create an R package in a directory of your choice with:

cd ~/Downloads && R
cpp11armadillo::pkg_template("blogpost")

The package structure corresponds to:

.
├── cleanup
├── configure
├── DESCRIPTION
├── dev
│   ├── 01_load_or_install.R
│   ├── 02_test.R
│   ├── 03_readme_and_license.R
│   └── data.r
├── NAMESPACE
├── R
│   └── blogpost-package.R
├── README.md
└── src
    ├── 00_main.h
    ├── 01_ols.cpp
    ├── 02_your_functions.cpp
    ├── Makevars.in
    └── Makevars.win

< section id="install-the-required-r-packages" class="level1">

Install the required R packages

We shall need the following packages to debug C++ code:

• devtools : For building R packages
• usethis : Helps set up package skeletons
• testthat : For unit testing
• vscDebugger : Connects R code to the VSCode debugger
• cpp11armadillo: To show a linear algebra example in this blog post

if (!require(devtools)) install.packages("devtools")
if (!require(usethis)) install.packages("usethis")
if (!require(testthat)) install.packages("testthat")
if (!require(vscDebugger)) install.packages("vscDebugger", repos = "https://manuelhentschel.r-universe.dev")

< section id="configure-c-in-vscode" class="level1">

Configure C++ in VSCode

Connect the VSCode debugger so that you can debug the cpp11 code. Depending on your operating system and R installation this step will not be exactly the same, so please adapt the paths and settings as needed.

Run the following R commands:

R.home("include")
.libPaths()

Open the command palette (ctrl + shift + p), type “edit configurations,” and select “C/C++: Edit configurations (JSON).” In my case that opens c_cpp_properties.json containing:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "~/R/x86_64-pc-linux-gnu-library/4.5/cpp11/include/*", 
                "/usr/include/R/*"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/clang",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-clang-x64"
        }
    ],
    "version": 4
}

Modify these lines from the previous JSON code according to the previous two R commands:

"~/R/x86_64-pc-linux-gnu-library/4.5/cpp11/include/*", 
"/usr/include/R/*"

If you run into compilation issues, create a Makevars file in src/ with:

PKG_CPPFLAGS = -I/opt/homebrew/lib/R/4.3/site-library/Rcpp/include

Adjust the path as needed for your setup.

< section id="test-the-package-example-functions" class="level1">

Test the package example functions

Open the package folder from File -> Open folder in VSCode and after opening an R terminal type this:

usethis::use_test("ols")

For this test I check if the ols_mat(y,x) function in src/01_ols.cpp gives the same result as the OLS estimator :

test_that("simple OLS test", {
 y <- as.matrix(mtcars$mpg)
 x <- cbind(1, as.matrix(mtcars$wt))
 expect_equal(solve(t(x) %*% x) %*% (t(x) %*% y), ols_mat(y, x))
})

You can run the following commands to register the functions and check the equivalency:

devtools::document()
devtools::test()

The test should pass.

< section id="edit-the-launch-configuration-in-vscode" class="level1">

Edit the launch configuration in VSCode

If there is no .vscode directory in your package root, create it from the left menu in VSCode and create a launch.json file inside it.

// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(lldb) Launch",
            "type": "lldb",
            "request": "launch",
            "program": "/usr/bin/R",
            "args": [
              "--vanilla",
              "-e",
              "devtools::test()"
            ],
            "env": {
              "R_HOME" : "/usr/lib64/R"
            },
            "terminal": "console",
            "stopOnEntry": false
        }
    ]
}

Verify that “program” and “R_HOME” match your R setup (check R.home() from R).

< section id="debug-your-c-code" class="level1">

Debug Your C++ Code

Open src/01_ols.cpp and set a breakpoint by clicking to the left of the line number. I added a breakpoint in line sixteen.

Go to the debugger tab in VSCode and click the play button next to your launch configuration. This will start the debugging session.

When your C++ function is called, the debugger will pause at your breakpoint, letting you inspect variables and step through the code.

You can also use the debug console to send commands directly to LLDB.

< section id="final-remarks" class="level1">

Final remarks

Now have a working setup for debugging cpp11 (and cpp11armadillo) code in VSCode. If you want to avoid setting up c_cpp_properties.json for every project, you can add the include paths globally:

Open user settings as JSON (ctrl + shift + p) and add:

"C_Cpp.default.includePath": [
    "~/R/x86_64-pc-linux-gnu-library/4.5/cpp11/include/*", 
    "/usr/include/R/*"
]

This change allows VSCode to find the R and cpp11 headers for any project.