In this class, we will learn about computer systems in part by using the C programming language and exploring its relationship to the Intel x86-64 machine language and assembly language. To ensure that we all have a consistent computing environment, you should plan to do your work on the CS department’s Linux server mantis.mathcs.carleton.edu. This short lab will help you get started working on mantis by connecting from another computer. (Note: For some assignments, you’ll be able to use your own laptop without the extra step of connecting to mantis, but the only supported computing environment for actually running your code in this course will be mantis.)

Step 1: Install Visual Studio Code

If you’re working in Olin 310, you do not need to do this step, because VS Code and the Remote-SSH extension should already be installed.

• Get VS Code: Download and install Visual Studio Code on your working computer.

• Launch VS Code: Open up the VS Code program on your computer.

• Install the Remote - SSH extension: In VS Code, on the left edge of the window, click the Extensions icon. (Alternatively, select the View->Extensions menu item.)

In the extensions browser, search for SSH. The top result will probably be Remote - SSH by Microsoft. Install it.

Step 2: Connect to mantis

From within VS Code:

• Hover your mouse over the little green/blue icon in the very bottom-left corner of the VS Code window. You should see hover-text that says Open a Remote Window. Click on the icon.

• At the top of the VS Code window, you’ll now see a drop-down menu starting with Connect to Host.... Click on Connect to Host....

• Now, you’ll see a new menu item that says + Add New SSH Host. Click on it, and fill the resulting text box with:

  YOUR_CARLETON_USER_NAME@mantis.mathcs.carleton.edu
  

Hit enter. Assuming this goes fine, you won’t have to add a new SSH host again. Instead, mantis will appear as a choice in the Connect to Host menu in the future.

• At this point, what VS Code asks you will depend on context. You may be asked for a password or you may be asked for an SSH config file (or something similar). If asked for a config file, you can choose the option that looks similar to /Users/YOUR_LOCAL_USER_NAME/.ssh/config. You may need to retry Connect to Host->mantis.mathcs.carleton.edu again to get to where you can enter your Carleton password.

• Once you have connected successfully to mantis, a new VS Code window will open. That bottom-left icon will now say SSH:mantis.mathcs.carleton.edu, which means you’re ready to go!

Step 3: Set up your working space on mantis

• Open VS Code’s file explorer: In the upper-left corner, click on the two-pieces-of-paper icon that opens VS Code’s file explorer (or select View->Explorer from the menu). Next, click on the Open Folder button that appears in the explorer. This will give you many choices, but you should go ahead and click OK for the default option, which should be /Accounts/YOUR_CARLETON_USER_NAME.

Note: If this step seems to be taking a long time, glance at the top of the screen and see if it’s expecting you to enter your password (possibly again).

• Trust the code authors: You may see a message asking if you trust the authors of the code you’re viewing. Say yes, as you don’t have any code yet, and the author will be you anyway.

• Ignore “large workspace” warning: You may see a warning that says Unable to watch for file changes in this large worksapce.... Don’t worry about it.

• Set up a long-term working directory named cs208: The file explorer on the left side of the VS Code window should now show you the top level of files in your CS/mantis account. Next, you should create a folder to organize your files for this course.

  • In the menu at the top of the VS Code window, select Terminal->New Terminal. A panel with a Unix prompt should appear in the bottom right of your VS Code window. This is a regular Unix shell on mantis, so you can run any Unix commands you want there.

  • In that terminal, create a folder named cs208, where you will do your work for the term:

    mkdir cs208
    

  If you type the command ls in the terminal after that (and then hit enter/return), you’ll see the new folder listed. You can also look at the VS Code file explorer, and the folder should show up there, too.

Step 4: Log out of mantis

To end your session, click the bottom-left icon (SSH: mantis.mathcs.carleton.edu), then scroll to the bottom of the resulting drop-down menu and select Close Remote Connection.

A typical work session

You’re all set up now, and you won’t need to repeat most of the previous steps anymore. This section describes a typical session with VS Code and mantis.

1. Restart, but with the cs208 working directory: Log in to mantis again, but this time when you click on Open Folder in the VS Code Explorer, select your cs208 folder instead of your top-level directory. Then, just open a terminal in VS Code.

Alternatively, after you’ve opened it once, you can use the File->Open Recent menu option. It should show ~/cs208 [SSH:mantis.mathcs.carleton.edu], which would be really handy when working from your own computer.

2. Start a new program: Go to File->New File. Type a hello-world program (e.g., hello.py with a single print statement). Save the file.

NOTE: You should get into the habit of saving frequently in VS Code, as it may not autosave for you.

3. Test your program: In the VS Code terminal, type a suitable command (e.g., python3 hello.py) to run your program.

4. Pause to reflect: Ponder the following questions:

   • Where is your hello.py file stored? (Answer: On the computer named mantis.mathcs.carleton.edu.)

   • Will your file still be on mantis after you log out? (Answer: Yes.)

   • Is there a copy still on your computer after you log out? (Answer: Maybe in a cache somewhere, temporarily, but you shouldn’t count on it.)

5. Download a file from mantis: Copy a file from mantis to your local computer (e.g., so you can submit homework via Moodle in your web browser). To do so, in the VS Code file explorer, right-click on the file you want to download and select Download from the right-click menu. There doesn’t seem to be a drag-and-drop option for this.

6. Upload a file to mantis: Open the folder containing your file (e.g., new_hello.c) on your local machine. This will be a Windows Explorer, macOS Finder, or Linux folder display. Drag the icon of your file into the VS Code Explorer panel while you’re logged in to mantis.

7. Always log out when you’re done: Don’t just close the VS Code window. Logging out helps mantis clean up after your connection, which helps keep mantis usable for you and your classmates.

One caveat about working on the lab computers

When you log out of the computers on the 3rd floor of Olin, your changes on that computer are discarded. So, for example, if you did Add New SSH Host on an Olin 310 computer, the resulting menu option would not be there anymore when you returned to that computer later. This can be frustrating, and is one of many reasons we encourage you to do most of your work by SSHing from your own computer.

Next steps

Now that you’re able to connect to mantis, you’re almost ready to work on the first assignment! Take a look at Assignment 1 - Starting C to get an idea of what you need to do, and then upload a few samples, compile, and run them on mantis.