- CSCI 350 Operating Systems Image
This repo contains a simple dev environment to do operating system development
(at least for xv6). After pulling the Docker image from Docker Hub, you
should be able to use the run.sh
or run.ps1
script to start, stop, and work in a
virtualized environment all from your command line.
The interface is based off of Noah Kim's and my cs104/docker.
For more information, please see the wiki. For any bugs or problems, please create an issue or dm me on Discord.
This Docker image has been tested and verified to be functioning correctly on the following platforms:
- Catalina, Big Sur (Intel)
- Big Sur (Apple Silicon)
- Windows 10 (Docker with WSL2 backend)
- Debian Sid, Arch Linux
- Visual Studio Code with the Remote Containers extension
- JetBrains CLion with the Makefile extension or CMake integration
- NeoVim with coc.nvim and extra patience
You can download the CLI utility to run this and other docker environments. Shameless plug, I wrote that CLI too. Benefits of installing this way is that you don't have to be in a specific directory to start the csci350 environment. Also, you won't have to clone this repo to get started.
See instructions here on the commands to run to install the CLI.
Once you have ch
installed, run the command to create the csci350 environment.
This will download the Docker image that will work for xv6 and set the required environment to run qemu, gdb,
and even do remote debugging. Before you run the command, make sure you've provided the correct path with the
--volume
flag (see instructions in the README for details).
The instructions below will walk you through running the setup script and the run script you'll use to access the csci350 environment.
-
Install Docker desktop from the website
- Windows Users Only: Docker provides better performance using WSL 2 than legacy Hyper-V. Set up WSL 2 using Microsoft's guide here. After you have WSL 2 running, refer to the screenshots at the end of this readme for settings you have to enable in Docker Desktop app.
- Linux Users Only: Install Docker engine from here,
-
Clone this repository.
-
Specify your desired mount location (i.e. your
xv6
project folder)
Windows users only
Make sure you run this in an Admin PowerShell to let you run scripts:
# must execute this in admin powershell and select [A] to run scripts
Set-ExecutionPolicy RemoteSigned
-
Modify the
work
variable at the top of the run script in the project folder. For example:macOS/Linux:
# in run.sh work=~/projects/cs350/xv6-public-master/
Windows Powershell:
# in run.ps1 $work="C:\Users\Username\cs350\xv6-public-master"
Windows Terminal using WSL2:
work=/mnt/c/Users/Username/cs350/xv6-public-master
-
Run the
run.sh
/run.ps1
script. If this is your first time starting, this will pull the Docker image. This image will be cached until there's a new image available or you manually remove it.macOS/Linux/Windows Terminal (WSL2):
./run.sh start
Windows Powershell:
.\run.ps1 start
This script is only a wrapper for some simple Docker commands.
To start up a Linux shell inside the Docker image, you'll want to start a terminal session inside the Docker image:
macOS/Linux/Windows Terminal (WSL2):
./run.sh shell
Windows Powershell:
.\run.ps1 shell
If you're only using this as a build toolchain, you can run the following command to create xv6.img
and fs.img
for use in QEMU later. This assumes that the Makefile exists in the project directory.
macOS/Linux/Windows Terminal (WSL2):
./run.sh build
Windows Powershell:
.\run.ps1 build
To quit qemu and return to Linux shell:
ctrl + a
x
Don't hit all three keys at the same time. Do ctrl + a
then x
You may get better performance by only using the build toolchain in the container, and running QEMU natively after installing it through Homebrew or your package manager of choice. This is because newer versions of GCC no longer compile the bootloader correctly. You can also get QEMU to run graphically this way!
After you're done working in the environment, you might want to stop the container. Don't worry if you forget to do this, since Docker Desktop will automatically and safely stop running containers when you shutdown your computer.
macOS/Linux/Windows Terminal (WSL2):
./run.sh stop
Windows Powershell:
.\run.ps1 stop
Here's what it looks like to interact with a setup environment:
If you don't want to navigate to your docker directory every time, you can check out Container Helper for a simple command-line interface. The README includes a one-liner to create the same cs350 environment included in the repository here.
Below are the system requirements for Docker Desktop:
- Windows 10 64-bit: (Build 15063 or later)
- Pro, Enterprise, or Education: using Hyper-V and Containers Windows features
- Any Windows 10 version: using WSL2 container backend (recommended)
If you are using Windows 10 Home, you can obtain a "free" license for Windows 10 Education here.
- Mac hardware must be a 2010 or newer model
- macOS must be version 10.13 or newer
- 4 GB RAM minimum
- Use the Docker-provided install instructions if it exists for your distro, otherwise
If you're having issues starting xv6
, such as the system is hanging at qemu
commands, try the following
- Outside the Docker shell, pull updated repo directory from xv6-public:
git clone git@github.com:mit-pdos/xv6-public.git
- Ensure all
.pl
files are executable and re-build:
# run these commands in the docker shell
chmod +x *.pl
make clean
make qemu-nox
Since this Docker image does not run a virtual display or window server, you cannot run make qemu
. Instead, use
make qemu-nox
. Adding an X server would have minimal benefit, since you can simply use your current terminal
window to debug your xv6 programs.
Run these commands
make clean
chmod 755 *.pl cuth dot-bochsrc printpcs runoff runoff1 show1 spinp
make qemu-nox
If your shell is stuck at qemu-system-i386 -nographic -drive file=fs.img,index=1,media=disk,format=raw -drive file=xv6.img,index=0,media=disk,format=raw -smp 2 -m 512
after running make qemu-nox
, it probably means you don't have WSL/WSL2 enabled properly.
You can check if you have WSL by checking here.
If you don't have WSL, you can follow the steps here.
Now that you have WSL and a linux distro installed, you can check if you have WSL2 enabled by runnning PowerShell in administration and run this command
wsl --list --verbose
You'll then see the name of your WSL, State, and Version (what you see may vary based on the distro you installed, this write up is using Ubuntu)
PS C:\WINDOWS\system32> wsl --list --verbose
NAME STATE VERSION
* Ubuntu Running 2
docker-desktop Running 2
docker-desktop-data Running 2
Here, you see a list of WSL running processes along with its state and WSL version.
If it shows 1
under version for any of the names, you can change it to 2
by entering this command in PowerShell in administration
wsl --set-version <process name> 2
You can change the default distro by running
wsl --setdefault <process name>
After it finishes changing, open your Docker Desktop and enable Use the WSL 2 based engine
. Then navigate to Settings > Resources > WSL Integration
, make sure you check Enable integration with my default WSL distro
, and enable integrations with any of the additional distros you have. You'll have to restart your docker by doing this operation.