Visual Studio Code: Remote (C++) Development on Linux Lab Machines

The Goal: Run an Integrated Development Environment (IDE) on your PC/Mac, edit source code files that are located on our Linux Lab machines, and compile/run/debug the Linux machine executable from your PC/Mac.

The Solution: While there are potentially many solutions to accomplish the above goal, thanks to Professor Yusuf Pisan for figuring out the details, this document presents an excellent and elegant solution based on Visual Studio Code (VSC) and SSH.

Overview: This document has two major sections:

Video: Thanks to Professor Pisan, here is an excellent video that you can watch while following the following tutorial.

Here are the details of the two sections. You should consider look at this document for a much higher level general discussion on C++ toolchain and writing high quality c++ code.

System Requirements and Setup

There are three main systems you must download/setup:

  • Husky OnNet VPN: So that you can connect to the Linux Lab.
  • Visual Studio Code (VSC): This is the IDE, you will be working with.
  • SSH: This is to allow VSC to connect to the Linux Lab.

Husky OnNet VPN

In preparation to connect to Linux machine, please you need to set up Husky OnNet VPN, please follow this link to download, install, and don’t forget to start the VPN after you are done. Note: make sure you have this running, otherwise when you run ssh command you will encounter operation time out (on Mac) or Resource temporarily unavailable (on Windows) error messages.

Visual Studio Code (the IDE)

  • Download and install Visual Studio Code (VSC) from this link
  • Now, install remote development extension to VSC from this link

SSH (for remote connection)

To install: you need to have an OpenSSH compatible client (putty does not work):

  • For A Windows Machine, follow these instructions. Note: you do not need to uninstall ssh after the installation (the instruction is for reference), and, you do not need to start sshd service to connect to Linux machines.
  • For A Mac Machine, your machine should have ssh already installed. However, you would need to install the Xcode command line tools (which can take a while), please follow these instructions.

To test ssh:

  • Open a Terminal (cmd for Windows, bash shell for Mac), and issue the following command (replace <YourNetId> with your net id!), and you will be asked if you trust csslab<x> (answer yes) and you can remote log-on to the linux machine. Note, <x> is an integer between 1 to 12. So, the machine names are, csslab1.uwb.edu, or, csslab2.uwb.edu, or csslab3.uwb.edu, etc.

ssh <YourNetId>@csslab<x>.uwb.edu

  • On Windows machine: if you encounter this error message “ssh is not recognized as an internal or external command …”, then, you would need to modify your system default PATH to include the path to your ssh.exe command file. The PATH to my ssh command on my Windows-10 machine is: C:\Windows\System32\OpenSSH\ssh.exe, you can find yours by performing a system-wide file search for “ssh.exe”.
  • Note: If you encounter “operation time out” (on Mac) or “Resource temporarily unavailable” (on Windows) error messages, then, make sure you have Husky OnNet VPN running!.

Configure Visual Studio Code (VSC) and Remote C++ development

You will need to connect to the Linux machine, and then, you can edit your c++ source code file, and then compile/run your program.

Explore/Edit files on Linux Machines via VSC

Here are the steps you must follow to explore/edit files on our Linux machines:

Here are the details.

Set up SSH Target
  • Start VSC on your local machine and begin setting up a ssh connection.
  • First, Click on Remote Explorer

  • Second, Select SSH Targets

  • Third, Add a new SSH Target by clicking on the + button

  • Now, type this command:
     ssh <YourNetID>@csslab<x>.uwb.edu 
    Note: <YourNetID> is your net id, and <x> is an integer between 1 to 12
  • Save to your personal profile, probably located at something like: /Users/<User>/.ssh/config
Connect to the SSH Target

When connecting to the ssh target:

  • You will be asked what is the OS: answer Linux
  • You will be asked if you trust the system, answer yes by clicking on continue
  • You will be asked for your password: type in your NetID password
  • Verify connection by checking on the lower-left corner

Explore your Linux folder
  • After connected, click on the Explorer button or View→Explorer
  • Click on the Open Folder button

  • Click on the OK button to explore your Linux folder

Do not click on Show Local, that will lead you to explore your local machine's folders.

  • You will probably be asked to type in your password again. That's fine.
  • You can also click on the Terminal menu item to start a new bash shell to explore the Linux file system.

Run and debug your C++ program with VSC

In all cases, you must have your source code file opened in the editor to run/debug the corresponding program.

Single source code file C++ program: Run/Debug

You must have the source code file open in the editor, for example, you can create a new file (right mouse button click over the desired folder), name the file main.cpp and type in the following C++ code:

#include <iostream>
 
using namespace std;
 
int main() {
    cout << "Hello world" << endl;
    return 0;
 
}

Make sure you save your edit (ctrl-s), you can then, with the editor open to the above code,

  • Run → Run without Debugging: to simply execute the program created from your opened source code file. The first time only: The first time you try to run a C++ program, VSC will not know what to do and the following window will pop up:
  1. Click on the more option and look for and select the C/C++ extension to install. I installed the C/C++ extension from Microsoft.
  2. Your program should now run.
  • Run→ Start Debugging: To debug the program created from your opened source code file.
Multiple source code files C++ program Run/Debug

To debug a program with multiple source code files, you will have to create a Command Palette to tell VSC how to compile/link your program.

  • View → Command Palette
  1. Choose: Tasks: Configure Task
  2. Choose: C/C++ g++ build active file: VSC will create a .vscode/tasks.json file.
  • You need to tell the VSC task which files it needs to compile. An easy way would be to inform VSC to compile all files with .cpp extension, this can be accomplished by:
  1. replacing: ${file} in .vscode/tasks.json
  2. with: ${fileDirname}/*.cpp
  • WARNING: You can do a file listing in your currently working forder, the actual program name created will be the name of the currently opened source code file. E.g., if your program source code consists of two files: f1.cpp and f2.cpp, when you have f1.cpp opened in the editor and debug, a executable named f1 will be created, while if you switch to have f2.cpp opened, a new executable file, f2, will be created instead. Make sure you understand what is going on, otherwise, you will end up with multiple program files which may cause confusion.
  • Compile options: since you are working with .vscode/tasks.json, you might aslo add additional flags to g++ compilation, e.g.,
    -std=c++11 -Wall -Wextra -Wno-sign-compare
    Here is what my tasks.json file looks like:
    1.{
    2.    "version": "2.0.0",
    3.    "tasks": [
    4.        {
    5.            "type": "shell",
    6.            "label": "C/C++: g++ build active file",
    7.            "command": "/usr/local/bin/g++",
    8.            "args": [
    9.                "-std=c++11",
    10.                "-Wall",
    11.                "-Wextra",
    12.                "-Wno-sign-compare",
    13.                "-g",
    14.                "${fileDirname}/*.cpp",
    15.                "-o",
    16.                "${fileDirname}/${fileBasenameNoExtension}"
    17.            ],
    18.            "options": {
    19.                "cwd": "${workspaceFolder}"
    20.            },
    21.            "problemMatcher": [
    22.                "$gcc"
    23.            ],
    24.            "group": "build"
    25.        }
    26.    ]
    27.}

Trouble Shooting

Issue: VSC Server Error

Symptom: VSC was working but, this time, with Husky OnNet VPN running, I receive this error message when trying to connect cssllab<x>:

I kept on typing my password but kept on receiving this error message.

Cause: It is likely your previous session did not terminate properly, and files are now corrupted on the csslab<x> machine.

Solution: (1) Go to the csslab<x> machine (2) find and kill the hanging processes, (3) remove all corrupted server files, (4) re-connect.

  • Go the the csslab<x> machine (by running ssh): On PC, run the cmd program, on Mac start a Terminal. Now type in this command:
     ssh <YourNetId>@csslab<x>.uwb.edu 
    Go ahead and type in your password and login.
  • Once on the csslab<x> machine, you can find and kill all hanging processes. To find the hanging processes, issue the following command (on csslab<x>):
     ps -ef | grep <YourNetId> 
    Remember to replace <YourNetId> with your own net-id. The output may be messy, and you may observe something like:

Take note of the first number next to YourNetId, ksung in this case, and the first numbers besides ksung are: 21045 and 21062. You want to kill these processes.

  • Kill the hanging processes: still on csslab<x>, issue this command
    kill -9 21045 21062
    Again, remember to replace the numbers 21045 and 21062 (there can be more, or, there may not be any hung process). No worries if you do not see any hung processes. Continue to next step.
  • You can also use this complex one line command
    ps aux | grep $USER | grep vscode | awk '{print $2}' | xargs kill -9 
    to find and kill processes as well. (Not sure if this command works in all cases)
  • Remove all corrupted server files: still on csslab<x>, issue these commands
    cd; rm -rf .vscode-server
    Be patient, this may take a while. Your prompt will return after a while (like up to a few minutes).

Now, on your own machine, quit VSC and start again. It should work now.

Issue: Disk Quota Exceeded

Symptom: While working on VSC with remote development, suddenly you cannot save your changes or create a new file. Receiving error messages saying “Disk Quota Exceeded”.

Cause: It is likely the VSC run-time cache is eating up all your disk quota.

Solution: Simply remove the cache file. On the Linux machine do this (e.g., via the Terminal of Visual Studio Code), issue this command:

rm -rf ~/.cache
This can take a short while, but after this you should be able to write to your file again.

Navigation

The best way to find something here is to use the search box in the upper right or the site index link below.

Print/export
Mobile QR Link