Software🔗

This course will make use of the following software:

• Operating system: an x86-64 ABI conforming OS such as many variants of Linux and macOS running on an x86-64 CPU. It is also possible to use macOS on an Apple Silicon CPU with some extra steps. For Using Windows, see notes below.

  All students have access to the campus GRACE cluster, which use Red Hat Linux on an x86-64 CPU, an appropriate OS for this class. See the Using GRACE notes below.

• Racket: the implementation language and source language of our compilers.

• Racket langs package: a package containing utilities for this course.

• NASM: the Netwide Assembler, which we will use to assemble x86 programs.

• GCC: the GNU compiler collection or a GCC-compatible system such as clang.

Instruction for using each system are below:

• Using Linux

• Using macOS

• Using Windows

• Using GRACE

1 Using Linux🔗

If you have an ARM-based machine, you will need to use GRACE or potentially setup an x86 VM.

For x86-based Linux machines, you will need to install Racket and the langs package. Finally, install nasm. You can use your favorite package manager; they should all have nasm.

2 Using macOS🔗

If you are using a macOS computer, the setup will be different depending on whether you have an Intel-based CPU or an Apple Silicon CPU. If you’re unsure which you have, click the Apple icon in the top-left and select "About This Mac". Under CPU, you will see a chip name containing either Intel or Apple.

2.1 Using macOS on Intel🔗

Intel-based Macs are fairly straightforward to set up. You will need to install Racket and the langs package. You will also need to install nasm. It’s probably easiest to use a package manager such as Homebrew to install with brew install nasm.

You will also want to make sure your Racket installation is visible from your PATH environment variable. Assuming Racket was installed in the usual location, you can run:

NOTE: You’ll need to know what version of Racket you installed and use that version’s name in the above command. For example, if you install Racket 8.6, you should be using the path "/Applications/Racket 8.6/bin" instead.

You can add this line to the .zshrc file in your home directory so that it is available every time you start the Terminal. Note that once you make this change to the .zshrc, you’ll either need to restart your terminal application or run source ~/.zshrc to update your current PATH settings.

2.2 Using macOS on Apple Silicon🔗

It’s also possible to run everything we need on an Apple Silicon Mac even though it doesn’t use an x86 CPU and instead uses an ARM processor. That’s because Apple provides a compability layer called Rosetta that will allow you run x86 programs on your ARM CPU.

The set up is basically the same as when Using macOS on Intel, except that when you install Racket you need to select the installer for Mac OS (Intel 64-bit) when downloading Racket. Do not use Apple Silicon 64-bit installer. This will work thanks to Rosetta.

Otherwise, follow the steps given above.

3 Using Windows🔗

For Windows users, using WSL for testing is highly recommended. Beyond the first few assignments, the projects will require generating and executing assembly code using the nasm package. Students in the past have had trouble trying to configure this in the Windows environment, so an easier workaround is simply to enable WSL and run your tests through some Linux Distribution. Here is a breakdown of the steps:

1. Following the instructions at this link, install a Linux Distro of your choice (e.g., Ubuntu). The instructions include a suggestion to upgrade to WSL2; this is not necessary but will improve efficiency in general.

2. Open your installed Linux distribution of choice and make any initial configurations necessary (user, pass, etc.). Run sudo apt update and follow with sudo apt upgrade. These two may take some time.

3. Run sudo apt install racket and sudo apt install nasm. These two should cover the necessary installations for this course.

4. Here is where to determine which IDE you would like to use.

   • Using vim (or Emacs as mentioned in the previous section) is simple. Copy assignment files into WSL. Modify files.

   • Previous students preferred installing VSCode (outside of WSL) from this link. For each assignment, copy assignment files somewhere on your Linux distro. If you would like to open some-file.rkt, you can open it from the command line by calling code some-file.rkt and, after some automatic set up, VSCode should load up the file. You can install Racket extensions from the VSCode Marketplace (a suggestion will also pop up once you open a .rkt file) to have colorized syntax, bracket matching, autocomplete/IntelliSense, etc.

   • If you are intent on using DrRacket, you will want to set up an X Window System to run GUI programs from within WSL. A popular option is MobaXterm. Once that is installed, you can launch DrRacket from within your WSL terminal by running the command drracket.

     You could also install DrRacket outside WSL and copy your files back and forth or use a symbolic link to connect the two. However, DrRacket will not be able to see the langs package you will install later by default, so you would either need to install it again within DrRacket or else find a way to connect your Windows-based DrRacket to your WSL-based Racket package configuration. This seems unnecessarily complicated, though, so we don’t recommend this option.

Regardless of the IDE used, you can now run your tests from your Linux subsystem by entering the project directory and using the raco command.

4 Using GRACE🔗

GRACE is unfortunately not well maintained by the university and is recommended only as a last resort. Please contact course staff if you plan to use GRACE for this class so we can help make sure everything is set-up properly.

The GRACE system gives students access to an x86-64 Linux system that meets all of the system requirements for the software in this course. If you have an incompatible system, or if you’d rather avoid installing and setting up the software for this course, you can use GRACE.

Before using GRACE, you should locally install an implementation of the X.Org X Window System which will enable you to run GUI programs from GRACE on your computer (or any other computer that uses X11). On Linux, this is likely set up by default. On Mac, you will need to install XQuartz. On Windows, you can use MobaXterm.

To use GRACE, open a terminal on your computer and type:

You will prompted for your UMD Directory ID password. After entering your password, you will be at the GRACE command line prompt.

The -Y command line option sets up X11 forwarding, which lets you run GUI applications from GRACE. If you leave this off, programs like DrRacket will fail to launch when started.

Racket and nasm are already installed, but you will need to modify your PATH environment variable so that you can execute them from the command-line. You can do this with the following commands:

If you add these lines to the .path file in your home directory, then you won’t have to run this command manually every time you login; it will happen automatically.

Once set, you should be able to run commands such as racket, raco, and nasm. Other tools such as gcc are already available.

Finally, you will need to install The langs package.

5 Installing Racket🔗

Racket is available for all major operating systems from:

https://racket-lang.org/

We will be using Racket 8.13, but any version from the past several years should work fine.

It’s best to install Racket using the Racket installer rather than any package management system (e.g. Homebrew) as these bundles are often out-of-date, missing features, or will select the wrong platform (remember: you need to be running the Intel 64-bit version, even if you’re on Apple Silicon).

There are two essential references:

• The Racket Guide - intended for those new to Racket, i.e. you!

• The Racket Reference - the definitive, comprehensive manual for Racket

Racket is a large, full-featured, batteries-included language platform. However, we will be using only a small subset of Racket. This subset should be easy to pick up for anyone familiar with functional programming. If you’re comfortable with basic OCaml, Haskell, or even JavaScript, you shouldn’t have much trouble learning the Racket bits we will be using.

6 The langs package🔗

After installing Racket, install the langs package which includes course utilities such as the a86: a Little Assembly Language library.

To install, run the following command:

To test the package works as expected, run:

All of the tests should pass; if they don’t, consult course staff.

The package source is hosted on Github. To check for and install updates, run:

7 IDE🔗

Racket comes with its own IDE: DrRacket, which is the recommended way to edit Racket files. We will also be running Racket and its associated tools from the command line.

If you’d like to use Emacs, there’s a good Racket mode, but we recommend using DrRacket for a while before switching to Emacs. Using any other editor is fine, too.