CS 233 Development Environment Guide

This page attempts to provide an overview of various ways you can set up a development environment for this course and answers some common questions about setup.

Table of contents

On getting started - where do I write code for this class?

You have multiple options available to you for completing lab assignments in this course, which will require working in C, Verilog, and MIPS Assembly. Generally, you’re going to need somewhere to write code: some options include your own machine, EWS, virtual machines, and more.

On your own machine

If you would like to try setting up for this course locally, follow software set-up information at the On your own machine page on this website. If you are on Windows, you likely want to try setting up Windows Subsystem for Linux (WSL), which will give you a lightweight Linux terminal you can use for development. While WSL is likely better performance-wise, another alternative is setting up a virtual machine, if your computer has sufficient hardware to do so.

Virtual machine suggestions

Virtual machines emulate a computer, so setting up a Linux virtual machine for this class means your computer will emulate a Linux machine locally which you can then use for development. You might be interested in setting up a virtual machine if you want a local Linux environment but are having trouble setting up X-forwarding with WSL (if WSL works for you, WSL will likely give you better performance, though) or installing the necessary software directly on your machine.

(Note that a virtual machine doesn’t HAVE to have a desktop GUI, in which case X-forwarding would still be needed in the end to see GTKWave output, but we are assuming that you want a local desktop GUI to avoid dealing with that setup.)

There are many different ways to set up a virtual machine, but one way which might be easiest is using the VMWare free download available through the UIUC store. More specifically, here’s how that may work:

  1. Download VMWare Workstation Pro

You should be able to download VMWare Workstation Pro here for free.

  1. Download desired Ubuntu ISO

Once you have VMWare set up, the only other thing you need to set up a virtual machine is an ISO that will enable you to set up a specific operating system you want. We recommend using Ubuntu 20.04 LTS, as we’ve found it seems to work best with the software needed for this class. Of course, if you discover something that says otherwise, please tell us your recommendation so we can make set-up as painless as possible in the future.

Link to find recent Ubuntu downloads here

  1. Open VMWare Workstation Pro

Open VMWare Workstation, and click File > New Virtual Machine to get started with your new machine. Follow the instructions on the set-up wizard, selecting your Ubuntu download ISO where prompted for one. You may be asked what specs you want on your virtual machine with options such as memory and number of processors. I suggest starting small, then if your virtual machine later keeps running out of memory or is very laggy, tweaking its parameters a bit (or making a new, more powerful machine if the old one completely failed and refuses to turn back on). Once your machine is set up, it may take a bit of time to boot for the first time, after which you’ll have a Linux desktop accessible locally! No X-forwarding is required here.

Connecting to EWS

If you would like to develop remotely on EWS, then you will need to either use SSH and X-forwarding or FastX. FastX is easy at times to use, though we do recommend having other alternatives such as a local development environment or SSH with X-forwarding set up as well for the events where FastX may go down (this might not seem like a big deal for labs, but you might end up taking a timed quiz requiring you to compile code and will not be provided accommodation if FastX fails you in your time of need).

To connect to EWS, we suggest first downloading the UIUC VPN. For SSH, this isn’t always needed, but for FastX, it is. Follow the guide here for setting up the VPN, and have the VPN running before trying to use FastX or SSH.

X-forwarding for SSH to EWS

Generally, to SSH into EWS, you only need to type the following in your terminal of choice (replacing netID with your actual netID):

ssh netID@linux.ews.illinois.edu

However, a bit more work might be needed to also set up X-forwarding, which will be described below. Regardless of which platform you’re trying to X-forward on, try typing “xclock” on the terminal where you believe X-forwarding is working, and if it does work, you should see a clock appear (some platforms may first require installing xclock, after which it should work).

For Mac OS, download XQuartz. You may then need to restart your computer. Have XQuartz running before you SSH. To SSH, open your Terminal, and log in with the following:

ssh -X netID@linux.ews.illinois.edu

(Note: if -X doesn’t work, try using the -Y flag instead.)

For Windows, download VcXsrv. Once downloaded, a program called XLaunch will become available. Open XLaunch, and choose the following options:

Note: the below instructions are intended for SSHing to EWS with X-forwarding. For X-forwarding to work with WSL, see our WSL guide.

First page: select Start a program

Screenshot of first XLaunch Client Startup page with option Start a program selected

Second page: fill in Connect to computer with “linux.ews.illinois.edu” and Login as user with your netID (replacing netID in the below screenshot with your actual netID).

Screenshot of second XLaunch Client Startup page where Connect to computer text field is filled with linux.ews.illinois.edu and User text field is filled by netID as a placeholder netID

Third page: check the Disable access control box.

Screenshot of third XLaunch Client Startup page where all default boxes are checked in addition to the Disable access control box

Then, click Finish, enter your UIUC password when prompted for a password, and keep clicking through the windows that show up until you can see xterm (it looks like a terminal window with a white background) spawn up successfully. X-forwarding to EWS should be working.

FastX

To use FastX, you simply need to connect to the UIUC VPN and then navigate to fastx.ews.illinois.edu in your browser. You should be able to login using your Illinois credentials, after which you can open up your terminal from the desktop GUI and get started.

Development Environment FAQs

Where do I use X-forwarding?

Specifically, you should either X-forward between your machine and EWS, or your machine and WSL if you choose to use WSL. You do not need to set up WSL if your end goal is simply to connect to EWS. WSL is, however, useful for local development if you don’t trust your Internet connection.

Also, if you are using Visual Studio Code for editing files, no matter how hard you try, unfortunately X-forwarding will not happen within the VS Code terminal. If you are using VS Code, you should also have a separate terminal open if you are planning on loading GTKWave for debugging purposes.

Why do I need to set up X-forwarding?

X-forwarding serves the purpose that using FastX could also solve: enabling you to test code with GUI outputs on EWS (or WSL). If you have no issues using FastX, you CAN use FastX, though note that this is strongly not recommended for timed quizzes, can sometimes randomly go down, and is generally laggy as soon as you open anything other than a terminal.

I want to develop locally. Should I use my local machine or a virtual machine or WSL?

WSL is only available on Windows, so if you’re using a Mac, WSL isn’t an option at all. The question comes down to whether you find it easier to download software on your Mac or set up a VM, if you’re a Mac user.

If you are on Windows, then WSL may be worth trying first. But, if X-forwarding from WSL to your local machine becomes a massive pain and CS233 office hours fail to fix your problems, then give VMs a try. Either will very likely be needed to do lab assignments in this course; installing locally is highly likely to not work.

What application should I write code in?

The short answer is that it’s up to you, but we have some suggestions. If you want the easiest development experience, Visual Studio Code (NOT Visual Studio) might be nice, while other popular GUI editors in the past have also been Sublime and Atom. However, if you’re using a resource-restrained virtual machine or developing over FastX, it might be too laggy to boot it up on either method. Your options would then be to either install VS Code on your local machine and develop on EWS using the remote SSH extension or use an editor on the command-line which will probably not choke your machine as terribly. Vim or emacs will be what you need. Look up either, and you should be able to quickly find guides for how to edit files on either since both are wildly popular.

What extensions should I download in Visual Studio Code?

If you want to use VS Code on your local machine to edit files on EWS, then the Remote SSH extension is necessary. Other extensions that are optional but might make life easier are:

How can I access my Windows files from my WSL terminal?

See the WSL Guide for more details on this.

How can I edit files on EWS/WSL from Visual Studio Code?

As noted in other comments about FastX, opening VS Code or other applications from FastX might lead to FastX freezing. So, you might be wondering - how can I edit code from a GUI application? There are some options which might work better.

If you’re using SSH to connect to EWS on the terminal: the VS Code Remote SSH extension might be your friend here. Once you have the Remote SSH extension installed, click the green bottom-left corner of VS Code:

Screenshot of VS Code Remote SSH button in bottom-left corner of VS Code window

This should open up multiple Remote-SSH menu options at the top of the screen. Click the “Connect to Host” option, and then “Add new host.” You will be prompted for an SSH command, which should be (replace netID below with your own netID!):

ssh netID@linux.ews.illinois.edu

Save this in your config file of choice as prompted. Then, click the green button again, click “Connect to Host” again, and this newly added host should be an option. If prompted for the host type, click Linux. Type your UIUC password when prompted for a password, and you should now be successfully connected to your EWS machine through your local VS Code! Note that, while you can certainly compile code on the built-in VS Code terminal, X-forwarding is currently not supported from that terminal, so you would still need to run a separate terminal such as the xterm which comes with XLaunch to see the output of GUI applications such as GTKWave.

If you’re using WSL: you should be able to open applications such as VS Code and edit files on WSL locally if you would like. For example, when on your WSL terminal, type:

code .

If you have VS Code installed, this will launch VS Code in your current WSL directory, allowing you to edit files with ease while avoiding command-line text editing. If you have another preferred code editor, you can try launching it from the terminal as well.