This page will walk you through setting up VSCode so you can run it on your local computer, but edit, compile, and execute code on MathLAN. You’ll need to be careful not to lock yourself out of your account, but this setup can be more convenient than using a remote session through FastX. Please be careful when you work your way through the instructions, and be extra cautious about closing sessions when you finish. It’s easy to lock yourself out of your Grinnell account; if that happens you will need to contact ITS or go to https://passwordreset.grinnell.edu. Be prepared for a lot of Duo pushes, but once you’ve logged in you may find this configuration is easier to use than the default FastX options.
Before setting up the development environment we will use for this class, you’ll need to configure your machine to allow SSH access to MathLAN. Follow the instructions for your computer’s operating system below:
If your computer has a different operating system, stop and ask for help. It’s probably possible to set up for the course, but I don’t have prepared instructions for all possible operating systems.
Once you have SSH connections working, you will need to set up Visual Studio Code. Go to https://code.visualstudio.com and download the latest version for your machine. Run the installer on your computer, and continue with the steps below once you have VSCode on your computer.
Launch Visual Studio Code, and then open the Command Palette. You can find the command palette under the View menu, or just type ctrl+shift+p on Linux and Windows, or command+shift+p on macOS. You’ll use the command palette frequently, so it’s worth learning the hotkeys for this.
Type in “Extensions: Install Extensions” (you can type just part of this line and select it from the pop-up). Type enter when you have it selected. You should see a search field at the top of the left-side panel that just opened. This allows you to search for extensions. You’ll need to find and install each of the following extensions, all developed by Microsoft:
Make sure you choose the extensions that match these names exactly, and that they are versions released by Microsoft and not some other developer. After you install the extensions you will need to relaunch VSCode.
Once you’ve installed the extensions, open the Command Palette and type in Preferences: Open User Settings. Using the search bar above, find the setting under the Remote-SSH extension for Max Reconnection Attempts. Set this to zero or one; a larger number could lock you out of your MathLAN account if you accidentally leave VSCode running while you are away from your computer.
Now we’re going to use the Remote-SSH extension to connect to a MathLAN machine from Visual Studio Code. This is the normal model you’ll use for development in this class; your editor will run locally, but all the code you write will run on MathLAN.
Open the Command Palette (ctrl/command+shift+p). Type in “Remote-SSH: Connect to Host” and type enter.
The prompt now wants you to choose a computer to connect to.
You should see a list of machines that matches the ones you added to your SSH configuration file.
You can choose any machine except for mathlan-gateway;
the gateway is not configured the same way as the machines we’ll use for this course, and will not work for many labs and assignments.
Once you’ve selected a host to connect to, type enter.
You may be prompted to allow network connections from VSCode. You should allow this. If this happens, your connection will probably time out and you’ll need to click the “Retry” button.
Wait for a Duo push and approve the login attempt. At some point you may be asked what kind of machine you’re connecting to. Choose “Linux” if you are asked.
After some intiial setup, you should now be running a remote session on MathLAN. You should see some activity in an Output window as the remote connection is set up. Once the activity stops, you can close the window.
Now we’ll open a project on MathLAN through VSCode.
Open a terminal by typing ctrl+` (or command+` on macOS). This terminal is running on the MathLAN machine.
You can use this terminal to run any commands required to obtain a copy of the starter code for a lab or assignment, e.g. git clone ....
Once you’ve done that, you’ll need to open the directory in VSCode.
You should have a file browser pane on the left side of the window with an Open Folder.
Click this button, and then browse to the starter code for your lab or assignment.
You may be asked to install recommended extensions for your project. You’ve already installed these extensions on your machine, but VSCode is asking to install them on MathLAN as well. Accept the suggestion. You may have to click “Install on remote” buttons below each extension below each extension you have installed locally.
If you are prompted to install an “insiders edition” of any plugins, I recommend you choose “No”. These versions may have some new features, but they’re likely to have bugs as well.
At this point, you should be able to open, edit, and save files on the remote machine.
You can build the project by running make in a terminal.
Anything else you do in the terminal, including running the programs you compile, will run on the MathLAN machine you are connected to.
If you run the make zip command to create an archive of your work, you should see the .zip file appear in the file browser.
You can right-click this file and download it to your computer, and then you can upload the zip file to Gradescope to submit your work.
You can share your VSCode session with members of your lab group using the Live Share plugin. Open the Command Palette and type in “Live Share: Start Collaboration Session”. This will probably prompt you to log in; log in with a Microsoft account, using your Grinnell credentials. Make sure you include the “@grinnell.edu” part after your username when logging in on Microsoft’s page.
At that point, you should have a link you can share with group members so they can join. They may be able to join through a browser, but it’s likely easiest if everyone in the group installs VSCode and the Live Share extension so everyone can run locally. Only the host of the live share session has to be connected to MathLAN, so other group members can skip the SSH setup if they’d prefer not to try it.