IDEs & Remote Development
Steven Zeil
In remote development, the compiler and debugger are run on the remote machine and do not need to be on your own PC. The IDE, however, is installed and run on your own PC. It communicates with the remote machine via a combination of SSH and SFTP to show you your files from the remote machine, to let you edit them, and to issue commands to the compiler and debugger on the remote machine.
1 VSCode
The IDE that we will use for remote development is VSCode, short for “Visual Studio Code”. This IDE is a free program with an open-source base, though the version we will be downloading includes some proprietary code. Despite its name, it is not the same as Microsoft’s “Visual Studio” suite, though its interface clearly draws inspiration from that proprietary Microsoft product.
Like many modern IDEs, you install VSCode as a basic framework with a limited set of built-in capabilities, and then customize it for your choice of programming languages and your development style by installing extensions. There is a very active community of people writing extensions for VSCode, so much so that it can be hard to keep up with all of the possibilities.
1.1 System Requirements
VSCode should work for remote development on PCs with the following operating systems:
- Windows 11
- Windows 10, builds from Fall 2018 or later, with OpenSSH
- Older Windows 10 versions, with CygWin SSH
- MacOS
- Linux
1.2 Trying It Out
Example 1: Try This: VSCode Remote Development
If your PC runsWindows 11 or Windows 10 (Fall 2018 or later), activate OpenSSH if you have not already done so.
- Open
Settings
.- Go to
Apps
, thenApps and Feature
, thenOptional Features
.- Find the entry for
OpenSSH Client
(Client
, notServer
!), click on it, and then clickInstall
.Follow the on-screen instructions to complete the installation.
If you have a Windows PC running an older version of Windows, you will not be able to use VSCode unless you first install CygWin.
Install VSCode on your PC, following the linked instructions below. Then return to this Try This.
If you are running CygWin SSH, you need to let VSCode know where it is. The way to do this is to
- Open the VSCode Settings (the gear icon in the lower left).
- Select “Settings”.
- In the Search bar, look for: remote.SSH.path
- Enter
C:\cygwin64\bin\ssh.exe
(assuming that you accepted the default location when installing CygWin, otherwise adjust the path accordingly).- Close the Settings pane.
Run VSCode and connect to
linux.cs.odu.edu
.From the
Terminal
menu, selectNew Terminal
(if you have not already done so).You should now have a shell session at the bottom of the main column. This is an ssh connection to one of our Linux servers. Select the
Terminal
tab, if necessary.Type a few shell commands (e.g.,
pwd
,ls
) to make sure everything is working.Let’s get a fresh copy of our program. Give the following commands in that shell session.
mkdir ~/playing/vscode mkdir ~/playing/vscode/primes cd ~/playing/vscode/primes cp -r ~cs252/Assignments/primes/* . ls -R
From the
File
menu, selectOpen Folder...
. Navigate to your~/playing/vscode/primes/
folder and open it.(You may be prompted for your password again when you do this.)
In the left column, you should see a listing of all of your files for this project. If not, try selecting the “Explorer” icon in the left toolbar.
Try clicking on a few of these files to load them into the editor.
When you first open a Java file in the editor, VSCode immediately looks at your folder as the root directory of a Java project. It should correctly deduce your source directory (e.g.,
src/
) and compile the Java code accordingly.
Unlike Eclipse, VSCode does not have separate commands to create or open projects that use Maven or Gradle build managers. If it sees a
pom.xml
file, it will treat this as a maven project. If it sees abuild.gradle
file, it will treat this as a Gradle project.All in all, there’s a whole lot less fuss involved with opening a Java project in VSCode.
You should see a short list of compilation errors in the “Problems” pane. Click on the first error message.
This should bring you near to to a line to a function named “find”.
Hover your mouse pointer over the phrase underlined in red, and the text of the error message will pop up.
- Position your cursor just after the “d” in “find”. Now pretend that you had just been typing “find”, then realized that you weren’t sure what the actual name of the function was that you wanted. Type Ctrl-space and a suggestion box will pop up. It should suggest the functions
findNthPrime
andfindSomething
, both of which are functions in this program. Double-click onfindNthPrime
to select it. Eclipse inserts the rest of the function name.Now move down to the next line and delete the semicolon. Notice that an error marker pops up almost immediately on the left. VSCode will actually find many Java mistakes as you type them, before you actually run the compiler. Restore the semicolon.
Use the Problem listing to locate the remaining syntax error, the use of “False” instead of “false”. Correct this and save your changes.
Run the program. Right-click on Primes.java in the “package Explorer” column and select “
Run Java
”.In the Console area, you will see a message “You must supply…”.
Now look at the code in the function
main
. You can see that this message gets printed when the arrayargs
has length 0. That array contains the command line parameters supplied to the program. In this step, we did not supply any, so the program informs us that we need to supply an integer.Open
Primes.java
in the editor.
From the
Run
menu, selectAdd Configuration...
A file
.vscode/launch.json
will be created and opened in your editor. You should see something that looks like this:{ // 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": [ { "type": "java", "name": "Current File", "request": "launch", "mainClass": "${file}" }, { "type": "java", "name": "Primes", "request": "launch", "mainClass": "cs252.Primes", "projectName": "prime_528ad334" } ] }
This creates two or more run configurations, the first one (highlighted above) to run whatever Java file you have open and the rest to run Java files that have a
main
function.Delete the highlighted option. It creates more confusion (IMO) than it’s worth.
Go to the “Primes” configuration.
Add a line as shown…
⋮ "configurations": [ { "type": "java", "name": "Primes", "request": "launch", "mainClass": "cs252.Primes", "args": ["3"], "projectName": "prime_528ad334" } ] ⋮
Save your changes to
.vscode/launch.json
Right-click on
Primes.java
in the Explorer column and select “Run Java
”.You should see, in the Terminal area, that the program correctly reports that the third prime number is $5$.
Edit the configuration in
launch.json
to change the “3” to a “5”.Right-click on
Primes.java
in the Explorer column and select “Run Java
”.This time the program incorrectly claims that $9$ is the $5^\mbox{th}$ prime number.
Clearly there is a logic bug somewhere in this code. We’ll track that down in the later lesson on Debugging.
You can now exit from Eclipse.
1.3 Cutting Down on Password Prompts
If you find yourself annoyed at being prompted for your password so many times, you can avoid this by creating an SSH key pair and registering it with an agent, then select the VSCode connection icon, select SSH: Open Configuration File...
, find your saved configuration info, and add an IdentityFile line with a path to your private key, e.g.,
Host linux.cs.odu.edu
HostName linux.cs.odu.edu
User myCSLoginName
IdentityFile c:\Users\myPCLoginName\.ssh\myKeyName
Modify the path in the final line as necessary to point to the actual location of your private key.
2 Details
2.1 Installing VSCode
-
Get VSCode here and install it on your PC.
-
Run VSCode. In a freshly installed state, it does not know how to work with C++ or Java, and it does not know how to do remote development. We’ll fix these limitations by immediately installing some extensions.
Click on the button to enter the list of extensions.
-
Use the text box at the top of the left column to search for the “Remote - SSH” extension. Click the small blue “Install” button in the left column to install it.
-
Use the text box at the top of the left column to search for “C++”. Locate and install the following extensions:
- C/C++
- Better C/C++ Syntax
2.2 Working with VSCode.
2.2.1 Connect to the remote server
-
Click on the small connect icon in the lower-left corner.
From the list of options, select
Remote SSH: Connect Current Window to Host...
. -
If this is not your first time using VSCode for a remote connection, you should see a list of the machines you have previously connected to. Select one and proceed.
If this is your first time, or if you want to connect to a different machine, click “+ Add New SSH Host…”.
-
Enter the ssh command:
ssh yourCSLoginName@linux.cs.odu.edu
and hit Enter. -
You will be asked where on your local PC to store the configuration info. The first suggestion, to put it in
.ssh/config
within your local home directory (C:\Users\
… for Windows users) is probably the best. -
A notice will pop up in the lower-right corner. Click the
Connect
button to proceed.
-
-
Watch for a password prompt to occur in the top center. Enter your password.
You may get prompted for this more than once before you are done.
The connection area in the lower left should eventually change to show the name of the remote machine that you are connected to.
-
From the
Terminal
menu, selectNew Terminal
.This will open up an shell session on the remote machine in which you can issue commands.
2.3 Configure VSCode to Run Your Program
If your program requires command-line arguments, you will need to set up a “run configuration” to supply them.
-
Open a Java file in the editor, preferably the one that contains the
main
function for the program that you want to run. -
From the
Run
menu, selectAdd Configuration...
A file
.vscode/launch.json
will be created and opened in your editor. You should see something that looks like this:{ // 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": [ { "type": "java", "name": "Current File", "request": "launch", "mainClass": "${file}" }, { "type": "java", "name": "MainProgram", "request": "launch", "mainClass": "cs252.MainProgram", "projectName": "mainprogram_528ad334" } ] }
This creates two or more run configurations, the first one (highlighted above) to run whatever Java file you have open and the rest to run Java files that have a
main
function. -
Delete the highlighted option. It creates more confusion (IMO) than it’s worth.
- Go to the configuration that names the class with the
main
function that you want to run. Add a line of the form"args": [
list_of_command_line_parameters],
with each parameter in the list inside quote
" "
and separated from one another by commas.For example, if you want to run the equivalent of
java cs252.MainProgram abc 123
you should edit
launch.json
like this:{ // 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": [ { "type": "java", "name": "MainProgram", "request": "launch", "mainClass": "cs252.MainProgram", "args": ["abc", "123"], "projectName": "mainprogram_528ad334" } ] }
Save your changes to
.vscode/launch.json
. -
Now you should be able to run the program, with those parameters, either from the VSCode debugger or by right-clicking on the Java file and selecting
Run Java
.
2.4 VSCode and git
If you open a project/folder in VSCode that is part of a local git repository, VSCode will take note and will start watching your changes.
-
Clicking the icon on the left will open a display in hte left column that will list:
- What files have been changed.
- What files have been staged for a later commit.
-
If you move your mouse over one of the changed files, you will see a “+” button to the right. Clicking this will move it to the stage.
-
Clicking on the file name of a changed or staged file will bring up a “difference” view showing what lines have been changed since your last commit.
-
You can commit your staged changes by typing your commit description into the “Message” box and terminating with Ctrl-Enter.
-
Near the bottom of the column you may see something that looks like this: .
- The number after the up-arrow indicates how many commits you have in your local repository that have not been pushed to the origin.
- The number after the down-arrow indicates how many commits fetched from the origin have not been merged into your working directory. Until you start working with git branches, this should be zero.
-
You can push and pull from the origin repository using the
...
menu at the top of the column — once we make sure that you can use your GitHub SSH key.
2.4.1 Authenticating with SSH Keys
When you clone, push, or pull from GitHub, you need to supply your SSH key. In your earlier work with git, you used the -A
option of an ssh
command to direct any attempts to authenticate your SSH keys back from the remote Linux server to your SSH agent running on your own PC.
Now we need to tell VSCode to do the same thing.
- Run VSCode.
- If you are already connected to linux.cs.odu.edu, click the
><
button and select “Disconnect…”. - Click the
><
button and select “Open SSH Configuration File…” Select the file that you used when you set up the connection info (probablyC:\Users\
…) . - You should see your info about connecting to linux.cs.odu.edu. It probably looks something like this:
Host your-name-for-this-connection HostName linux.cs.odu.edu User yourLoginName
Add a line to the end of the list of options:
Host your-name-for-this-connection HostName linux.cs.odu.edu User yourLoginName ForwardAgent yes
-
Save that configuration file.
2.4.2 Try It Out
Example 2: Try This: git and VSCode
Again, make sure that you have registered an SSH key with GitHub and have added that key to an SSH key agent.
Run VSCode and connect to
linux.cs.odu.edu
.From the
File
menu, Open the directory~/playing/CS252-project1
.Within a few seconds, you should see your VSCode project in the left column.
Open the
Pie.java
file and add a Java comment. Save your changes.
- Look at the icon on the left. a small number should have appeared, indicating the count of the number of files changed since the last commit.
- Click on that icon to enter the git view.
You should see
Pie.java
listed as changed but not staged.Click on it to open a comparison view, showing what changes were made.
Hover your mouse over the
Pie.java
in the Source Control column, and you should see a “+” button appear.Click that “+” to move the file to the stage.
(You could also open a terminal in VSCode and type
git add src/cs252/Pie.java
. All of the git commands are still available to you in the terminal.)Type a descriptive message in the Message box, terminating with Ctrl-Enter.
Pie.java
will disappear from both the stage nd the changed files list, because it has not been committed and is up-to-date.At the bottom of the left column, you should see a one by an ip-arrow, indicating that you have one commit that remains to be pushed to the origin.
Type
git push
into the terminal, or selectPull,Push -> Push
from the...
menu at the top of the left column, or use the “Sync Changes” button in that column.
- If you are using CygWin SSH, issue this command in a separate CygWin terminal as described above.
- I find that the “Sync Changes” button and the “Push,Pull” menu items are unreliable when doing remote connections. Typing the command into the terminal, however, seems to work reliably.
- If even that fails, refer to the FAQ for troubleshooting suggestions.
Visit your project on GitHub and verify that the changes have been sent up to the origin repository.
2.4.3 Viewing and Manipulating your History
If you right-click on any file in your listing, one of the options available is File History -> Open File History
.
This opens up a small window in the left column showing the recent commits in which you made changes to that file.
- Hover your mouse over one of those commits. A set of buttons will appear. These allow you to
- view that old version of the file, or
- see a comparison of that version of the file to your current version.
Between those, you can selectively undo all or some of the changes you have made by copying and pasting from the old version of the file into the current one. (You can also use the command line git checkout
command to replace the current version of the file by an old one, if you so desire.)