- 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 csci104/docker.
For more information, please see the wiki. For any questions, bugs or problems with these instructions, please create an issue. To help me in maintaining this repo, issues help track problems people have so any knowledge is documented, shared, and easier to track. Thanks!
This Docker image has been tested and verified to be functioning correctly on the following platforms:
- Catalina, Big Sur (Intel)
- Big Sur, Monterey (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
Skip to the Getting Started (run scripts) section if you do not want to install ch.
If you have the container helper CLI (ch) installed already, this is the
fastest way to start. See detailed instructions here to install ch. (full disclosure, this is a shameless plug since I wrote the CLI but I do at least dogfood my own tools!).
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 since your main dependency is the Docker image with qemu and gdb installed.
Simplest solution to install ch (at least on macOS) is if you have homebrew. See the getting started notes to run the install script for Windows or Unix-based system.
brew tap camerondurham/tap
brew install camerondurham/tap/chFind the absolute path to your csci350 directory where you keep your homework.
See the Filepaths in terminal wiki from csci104/docker if you need some help with this.
On macOS/Linux:
Navigate to your directory in the terminal and run pwd, the output should be something like /Users/username/path/to/csci350
In Windows Powershell
Navigate to the directory in Powershell and run Get-Location, you will want the output like C:\Users\Username\path\to\csci350
Use ch create to create and save the environment settings, replacing PATH_TO_YOUR_WORKDIR with the path from step 1.
You can copy-paste this below in macOS/Linux:
ch create csci350 \
--image camerondurham/cs350-docker:v1 \
--volume PATH_TO_YOUR_WORKDIR:/xv6_docker \
--security-opt seccomp:unconfined \
--port 7776:22 \
--port 7777:7777 \
--port 25000:25000 \
--cap-add SYS_PTRACE \
--shell /bin/bash \
--privileged \
--platform linux/amd64Below is the single-line version for Windows. Please remember to replace PATH_TO_YOUR_WORKDIR wirh the path from part 1.
ch create csci350 --image camerondurham/cs350-docker:v1 --volume PATH_TO_YOUR_WORKDIR:/xv6_docker --security-opt seccomp:unconfined --port 7776:22 --port 7777:7777 --port 25000:25000 --cap-add SYS_PTRACE --shell /bin/bash --privileged --platform linux/amd64
NOTE: The command above requires
chversion at leastv0.3.7. Refer to install instructions if you see errors about non-existent--platformflag.
ch shell csci350 --force-startSee the ch README Command section or ch --help for other commands.
Skip this section if you followed Getting Started (ch) instructions since
ch will take care of starting/stopping/getting shells into your environment.
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
xv6project 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
workvariable 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.ps1script. 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 shellWindows Powershell:
.\run.ps1 shellIf 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 buildWindows Powershell:
.\run.ps1 buildTo quit qemu and return to Linux shell:
ctrl + a
xDon'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 stopWindows Powershell:
.\run.ps1 stopHere's what it looks like to interact with a setup environment:
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
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
.plfiles are executable and re-build:
# run these commands in the docker shell
chmod +x *.pl
make clean
make qemu-noxSince 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-noxIf your shell is stuck on qemu-system-i386 -nographic -drive ... after running make qemu-nox or returns an error rosetta error: Unimplemented syscall number 282, you may need to disable Rosetta emulation in Docker.
Uncheck the "Use Rosetta for x86/amd64 emulation on Apple Silicon" option in Docker Settings > General. (thank you to @WardahJabeen for this suggestion in #13!).
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 --verboseYou'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 2Here, 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> 2You 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.
