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.

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

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")

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.

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 \(\hat{\beta} = (X^t X)^{-1}(X^t Y)\):

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.

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).

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.

Final remarks

Now you 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 the 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.