Project 0: Setting up your development tools

This project will demonstrate how to set up the tools and development environment we will use for the remaining projects in this course. We will use a similar environment to grade your work.

If you have taken other systems courses at Brown, you have likely set up a Docker container on your system with the tools you need for the course. In this course, we will set up an environment with similar tools, but, depending on your system, you might not need a Docker container: because we will be developing code exclusively for a virtual machine (QEMU) or on separate hardware (a physical Raspberry Pi), you may actually need fewer tools installed on your computer than your other classes, so your environment can be simpler.

These instructions will describe how to set up your environment, and how to set up a docker container if needed (or if you prefer to develop this way).

Clone your environment

In this step, we’ll download the course’s setup code and determine how to configure your system.

xcode-select --install

Start your setup by cloning our development environment repo and checking your system. To do this:

1. Open a terminal in a directory on your computer where you want to do your coursework:

   • ⚠️ Windows users: open a WSL terminal (e.g. terminal type “Ubuntu”) and change to your WSL home directory (type cd ~)

   • ⚠️ Mac users: We strongly recommend you use a folder that does not sync with iCloud or any other cloud storage, which can cause random issues throughout the semester. To do this, we recommend starting from your main user folder (i.e., the folder that holds your Documents/Downloads/Desktop folders). For example:

     # Example:  go to your home directory before starting
     you@your-mac:~$ cd ~
     

     Optionally, you can setup your environment in any other folder you like, so long as it doesn’t sync with iCloud.

2. Then, enter the following command to download our development environment to the new subdirectory, YOUR_DIRECTORY. Choose your own name (e.g., cs1670) instead of our placeholder YOUR_DIRECTORY. To do so, replace YOUR_DIRECTORY in the git command below with whatever you choose:

   git clone https://github.com/csci1670/cs1670-f26-devenv.git YOUR_DIRECTORY
   

3. Use cd to enter the directory you have just created (e.g., cd cs1670 if you called your directory cs1670).

4. Run the script check-host-system, which will check your host’s OS version and see what tools you already have installed:

   ./check-host-system

   The script should print some information about your system, and some recommendations, like this:

   Host OS:         macOS v15.7.4 Sequoia
   Architecture:    ARM64
   Shell:           /bin/bash
   Homebrew:        Yes (/opt/homebrew/bin/brew)
   Docker:          Yes (v29.4.1)
   
   ===================================================================
   
   Your system looks OK to install the native macOS (homebrew) version

Take a look at the output from the script: if you see any warnings in red, the script identified a problem with your setup that needs to be fixed before continuing. To fix them, follow the instructions in the script; you can find more details about the issues in the Troubleshooting section.

Otherwise, if there are no warnings, you’re all set to install your tools!

Installing your tools

We offer two ways you can install our development tools – the check-host-system script (from the previous section) will recommend which version you should use. Before continuing with this guide, follow the instructions to set up your preferred version:

• Native macOS version (aka the “homebrew version”, for macOS Sonoma and later): installs our development tools natively on your host system using the homebrew package manager. This is a lot simpler than the container version, but only works on the most recent macOS versions.
• Container version (Windows systems, macOS Ventura and earlier, most Linux systems): this version sets up a Docker container on your system, similar to the environment you may have used in your other systems courses.

Testing your setup: building a kernel!

Now that your environment is set up, it’s time to build your first operating system!

To test your setup, we’ve provided a pre-compiled “demo” operating system image (i.e., a machine code file containing a kernel and userspace programs) that demonstrates many of the features you’ll be implementing throughout the course.

By the end of this project, you’ll add a small file that modifies the operating system, and run it in QEMU to see the changes. This will make sure that both your compiler and QEMU are working.

Running the demo OS (console mode)

Running with graphics

Our demo OS doesn’t just print to the console, however – it also has fancy graphics that are displayed on QEMU’s video display, which emulates a monitor that you might connect to a computer via an HDMI port.

We won’t start using the graphical display until Project 3, but QEMU’s graphics support can be a bit tricky to use on systems, we’ll test it now to make sure it’s working.

Since running QEMU in graphics mode can sometimes be buggy, we support two ways to run it: a window method and a browser method–you should choose which method based on the environment you set up:

• If you are using the container environment (e.g., if you use Windows, older macOS), you should use the browser method. This method creates a web page that shows the display, which you can open in your browser.
• If you are using macOS and used the native install (i.e., homebrew) environment, you should try the window method. This shows the display in a normal desktop window on your mac.

Browser method

The browser method shows the QEMU display (i.e., what would be on a screen if we were to connect one) on a web page that you can view in your browser. This method should work in any development environment (container, or native macOS).

Window method (native macOS only)

The window method shows QEMU’s graphical display (i.e., what would appear on a screen if we were to connect one) in a regular window on your Mac. This is usually more convenient than the browser version, but it doesn’t work in the container environment, and may have some bugs. If you use this method, and run into issues, you can always fall back to the browser method.

Expand for instructions

To run QEMU in windowed mode, run the following command from your repo:

make qemu-fb

Aside: what does "fb" mean?

The fb stands for framebuffer, which is how the operating system interacts with the display hardware. We’ll learn what this means later in the course!

This should open a small window that shows “Welcome to CS1670!”

Warning: If your window is really small, you may need to resize it so that it shows the whole display:

To do this, click and drag the bottom-right corner–the window should also-resize to the correct size as soon as you start dragging.

Once you’ve resized your display, you should see a window that shows “Welcome to CS1670!” and a box bouncing around the screen, like this:

Some important things to note as you use the QEMU display:

• When you click into the display, QEMU will take control of your mouse. To get it back, press Ctrl+Option+G (as shown in the titlebar)
• You can quit QEMU by closing the display window, or by pressing Ctrl+a x in the terminal (like we did for the previous demo)

Exercise

At this point, your tools are mostly set up! Let’s do a quick practice to make sure you can compile code for your operating system. While you don’t have the code for our ready-made demo OS, we’ve set things up so that you can modify it: as practice, we’ll change the background color of the display. The results of this part are what you’ll hand in at the end.

0x00BBGGRR
    BB     - blue channel  (1 byte)
      GG   - green channel (1 byte)
        RR - red channel   (1 byte)

So how do we use this to set the background color? We’ve set up this project’s stencil to read the background color from a certain address in memory (0x0e0000). the rest of the code sets all the background pixels to this value. For our demo, we’ll set a color value at this address.

// Tell the linker to store my_var in the ".bgcolor" section of memory
// NOTE:  Your variable will NOT be type char--what should it be??!
char __attribute__((section(".bgcolor"))) my_var = 0x00;

Once you have your display showing your color of choice, read the next section to submit your work!

Submitting your work

Submitting on the grading server

Head over to the grading server. If you were registered for the course on the first day of classes, you should have received credentials by email. If you don’t see an email, please check your spam folder.

1. Log into the grading server with the password you received. Once you’re logged in, enter your GitHub username (at the top).

2. Add the repository URL under “Project 0” category. Click “Project 0” to initiate a fetch of your repository from GitHub:

   

   • Note: If your GitHub account is not linked to your Brown email address, the grading server will give you a command to run to verify your repository.

3. You should see your commit listed on the Labs page, as shown above. You’ll also see a button labeled “Checkoff”. Click this button to have your submission checked off.

   After your work passes the test, you should see a screen similar to this one (you might need to refresh the page to see it):

   

Setup feedback form

In addition to the checkoff, please also fill out our background and setup form to help us tune the assignment for future offerings of the course.

You will not receive credit unless you complete the form (regardless of the grade shown on the grading server).

Congratulations, you’ve completed Project 0 and are set up for the course! 🎉

Resources and troubleshooting

We’ve compiled a list of FAQs and common issues for both development environments:

• Container environment FAQs
• Native macOS environment FAQs

FAQs and common issues will be collected here!