Remote SSH

The Remote-SSH extension lets us use a remote machine as our development environment while running VS Code locally. The source code is located on the remote machine.

Preliminary setup

We are assuming the following tasks have been done beforehand:

• The remote host that we want to connect to is defined in the local SSH configuration file ~/.ssh/config.
• The toy repository has been cloned and set up on the remote machine as described in Overview of the toy repository.

Install the extension

To install/enable the extension, follow the same steps as in the previous sections.

Get started

Connect to Host

To establish a connection to the remote machine,

• Run >Remote-SSH: Connect to Host...
• Select your host from the pop up window (workstation in our case)

This opens a new VS Code window that is connected to the remote host (see bottom left corner):

Install extensions on the remote machine

Just like we did in the previous sections, we can install extensions on the remote machine.

• Go to Extensions in the activity bar

VS Code shows you all the extensions which are installed on the local and on the remote machine. It will also disable certain local extensions if they cannot be used on the remote machine.

To install an extension remotely, simply select a greyed out local extension and click Install in SSH: workstation:

For this tutorial, we are going to install the following extensions on the remote machine:

Settings on the remote machine

To modify VS Code user settings on the remote machine,

• Run >Preferences: Open Remote Settings (JSON) (SSH: workstation)

You can simply copy the contents of your local user settings to the remote file.

Note: Be careful to adjust all paths in case they don't make sense for the remote machine. Settings for extensions which are not installed remotely will simply be greyed out and ignored.

In our case, we simply

• copied the local settings,
• simplified cmake.buildDirectory and cmake.installPrefix (VS Code doesn't recognize ${buildKitVendor} and ${buildKitVersion} on our remote machine),
• added a cmake.cmakePath setting and
• changed the path of the clangd executable:

Open the workspace on the remote machine

To open a folder on the remote machine,

• Run >File: Open Folder...
• Select the remote workspace folder moderncpp_vscode

Configure CMake

First, follow the same steps as in Setting the source directory and in Scan and edit kits.

Setting up the CMake kits can be a little bit more complicated.

Often we want to connect to an HPC cluster which uses Environment modules. In this case, we don't want CMake Tools to find the kits for us. Instead, we will add them manually by running >CMake: Edit User-Local CMake Kits:

We will use and focus on the following kit:

{
  "name": "Clang-19.1.7",
  "compilers": {
    "C": "clang",
    "CXX": "clang++",
    "Fortran": "gfortran"
  },
  "isTrusted": true,
  "environmentSetupScript": "/mnt/home/thahn/scripts/mymodules2.4/clang-py3-mkl.sh",
  "description": "Development environment using llvm19 and intel-mkl",
  "keep": true,
  "cmakeSettings": {
    "CMAKE_CXX_FLAGS": "${env:CXXFLAGS} -I/mnt/sw/nix/store/hfz0assy0i6nxj3l7f3vfl6md1794lfs-cuda-12.5.1/include -I/mnt/sw/nix/store/xr2bwj18vpfgljj56vrbskavicnd8ixv-llvm-19.1.7/include -I/mnt/sw/nix/store/bxyc4126c41qsmgznz224p1krgvxzcj6-hwloc-2.11.1/include -I/mnt/sw/nix/store/5k6q3mp0zy5jypinnhla9h364ifmfrhw-boost-1.87.0/include -I/mnt/sw/nix/store/fx4s301kfywhjkdqaldc721gdabrlwkz-hdf5-1.12.3/include -I/mnt/sw/nix/store/l3vka19z7hajn2qxhsd6ja0k07vcg99z-nfft-3.5.3/include -I/mnt/sw/nix/store/zlzq2k4r6gvpfrlzhaif4pfp63fsar8s-fftw-3.3.10/include -I/mnt/sw/nix/store/zdyfpzfxp0r5k16s10xb66l7qih5ldan-gmp-6.3.0/include -I/mnt/sw/nix/store/b11qsc8pddw779l2cqsvvpjf9rkgcrrv-python-3.12.9-view/include -I/mnt/sw/nix/store/pa59vldasm7gxpr7dkijhk09q5qq63q1-openmpi-4.1.8/include -I/mnt/sw/nix/store/5cfsn3h63k3mp3sjqars1hzdpa0bb6k6-magma-2.9.0/include -I/mnt/sw/nix/store/mmj2ni52w5xf531q81msvz2n3qk2sva1-flexiblas-3.4.2/include -I/mnt/sw/nix/store/mjpb8cncb34xrb245zl0bzzrnd54z3i9-gdb-15.2/include -I/mnt/sw/nix/store/xpar4v99p64z5f5s6gjbbvsvg0lfbgi4-gcc-14.2.0/include"
  }
}

As you can see, we did not specify any absolute paths for the compilers. Instead, we will bring them into the PATH by loading the right modules with the setup script /mnt/home/thahn/scripts/mymodules2.4/clang-py3-mkl.sh. The script is located on the remote machine and contains:

$ cat scripts/mymodules2.4/clang-py3-mkl.sh
module load mymodules2.4/clang-py3-mkl

Here, we simply load the module the sets up the environment on our remote machine, i.e. loads other modules and sets environment variables. What exactly needs to be done in the environment setup script depends a lot on your remote machine and the requirements of your project.

Note: We are also including directories of various loaded libraries with the CMAKE_CXX_FLAGS CMake variable. This is needed in our case for a better coding experience, otherwise VS Code cannot find the necessary header files.

Build and Run

Once we have all our kits defined, we can Select a kit + variant and configure the project and Build the project.

To Run tests and examples from the terminal, we might have to load the corresponding modules first.

Otherwise, you can simply run them directly in VS Code with >CMake: Run Tests.

clangd

We can also check that the language server works as expected by opening the ./src/linalg.cpp file and hovering over nda::matrix:

Debugging

Debugging on a remote machine via VS Code does not work out of the box in our case.

You can try the approaches described in the Debugging section.

If they don't work, we recommend to debug via the command line or to use Dev Containers as explained in the next section.