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.

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:

• System Requirements and Setup
• Configure Visual Studio Code (VSC) and Remote development
• Troubleshooting

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 22. 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, to compile/run your program open an SSH Client like PuTTY/MobaXterm or terminal on Mac. – VSCode Best Practices

Explore/Edit files on Linux Machines via VSC

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

• Start VSC on your local machine,
• Set up SSH Target
• Connect to the SSH Target
• You can now Explore your Linux folder (and edit files)
• You can select any of your C++ source code file by clicking on the file to open it in the VSC code editor.

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

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.

Troubleshooting VSCode:

Troubleshooting VSCode: How to use VSCode on the remote csslab and avoid high-load/infinite loops and disconnect:

When running your program on the remote csslab using VSCode, there might be some bugs on your script that can create infinite loops. These bugs can lead to a high-load on the remote machine, which will result in you being disconnected from the lab. In order to avoid this, please follow the instructions below:

While connecting to the remote Linux lab from your VSCode, you can parallelly establish a new connection to the same Linux machine using the Terminal (if you are using Linux/Mac) or PuTTY (if you are using Windows). Make sure that your personal machine is connected to the “Husky OnNet VPN” when you are off Campus.

To avoid creating a high load on the remote machine. Write your code in the VSCode editor and then compile/run it using your terminal/PuTTY. – VSCode Best Practices

Pro Tip: You can terminate your runaway job by pressing “Ctrl + Z” on your terminal.

Check the below Images for visual reference:

Mac terminal connection to the same Linux machine:

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

• 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.}

WARNING on Executable File Names

You can do a file listing in your currently working folder, 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.

Run your C++ program from terminal

You can also compile and run your programs from the Terminal in VSC

1. Choose New Terminal from VSC menu
2. Compile: g++ -g -std=c++11 -Wall -Wextra -Wno-sign-compare *.cpp
3. Execute: ./a.out

If you are going through the edit-compile-run many times, the following script can be helpful.

#!/bin/bash
 
# runit.sh compile and run the program
 
rm -f a.out
g++ -g -std=c++11 -Wall -Wextra -Wno-sign-compare *.cpp
./a.out

Troubleshooting

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 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, 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.Now, on your own machine, quit VSC and start again. It should work now.

• 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, issue these commands

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.

If you are still having problems with your disk quota, you can also remove all the VSC files, but you will have to re-install at least some of them later.

rm -rf ~/.vscode-server

If you are not sure what directories are using your disk quota, you can use

cd; ls -a | du | sort -n

or alternatively

find ~ -maxdepth 1 -execdir du -s {} \; | sort -n