IDEs & Remote Development

Steven Zeil

Last modified: Dec 20, 2023
Contents:

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:

1.2 Trying It Out

Example 1: Try This: VSCode Remote Development
  1. If your PC runsWindows 11 or Windows 10 (Fall 2018 or later), activate OpenSSH if you have not already done so.

    1. Open Settings.
    2. Go to Apps, then Apps and Feature, then Optional Features.
    3. Find the entry for OpenSSH Client (Client, not Server!), click on it, and then click Install.

      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.

  2. Install VSCode on your PC, following the linked instructions below. Then return to this Try This.

  3. If you are running CygWin SSH, you need to let VSCode know where it is. The way to do this is to

    1. Open the VSCode Settings (the gear icon in the lower left).
    2. Select “Settings”.
    3. In the Search bar, look for: remote.SSH.path
    4. Enter C:\cygwin64\bin\ssh.exe (assuming that you accepted the default location when installing CygWin, otherwise adjust the path accordingly).
    5. Close the Settings pane.
  4. Run VSCode and connect to linux.cs.odu.edu.

  5. From the Terminal menu, select New 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.

  6. 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
    
  7. From the File menu, select Open 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.

  8. 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 a build.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.

  9. 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 and findSomething, both of which are functions in this program. Double-click on findNthPrime to select it. Eclipse inserts the rest of the function name.
  10. 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.

  11. Use the Problem listing to locate the remaining syntax error, the use of “False” instead of “false”. Correct this and save your changes.

  12. 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 array args 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.

  13. Open Primes.java in the editor.

    • From the Run menu, select Add 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

  14. 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$.

  15. Edit the configuration in launch.json to change the “3” to a “5”.

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

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

  1. Get VSCode here and install it on your PC.

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

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

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

  1. Click on the small connect icon in the lower-left corner.

    From the list of options, select Remote SSH: Connect Current Window to Host....

  2. 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…”.

    1. Enter the ssh command: ssh yourCSLoginName@linux.cs.odu.edu and hit Enter.

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

    3. A notice will pop up in the lower-right corner. Click the Connect button to proceed.

     

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

  4. From the Terminal menu, select New 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.

  1. Open a Java file in the editor, preferably the one that contains the main function for the program that you want to run.

  2. From the Run menu, select Add 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.

  3. Delete the highlighted option. It creates more confusion (IMO) than it’s worth.

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

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

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.

  1. Run VSCode.
  2. If you are already connected to linux.cs.odu.edu, click the >< button and select “Disconnect…”.
  3. Click the >< button and select “Open SSH Configuration File…” Select the file that you used when you set up the connection info (probably C:\Users\…) .
  4. 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
    
  5. Save that configuration file.

2.4.2 Try It Out

Example 2: Try This: git and VSCode
  1. Again, make sure that you have registered an SSH key with GitHub and have added that key to an SSH key agent.

  2. Run VSCode and connect to linux.cs.odu.edu.

  3. From the File menu, Open the directory ~/playing/CS252-project1.

    Within a few seconds, you should see your VSCode project in the left column.

  4. 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.
  5. You should see Pie.java listed as changed but not staged.

    Click on it to open a comparison view, showing what changes were made.

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

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

  8. Type git push into the terminal, or select Pull,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.
  9. 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.

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