Skip to content

Setup

Jump to bottom
Devon Friend edited this page Jul 23, 2024 · 9 revisions

Prerequisites

  1. In my experience, at least 16GB of RAM is required to run the devcontainer without any issues on Windows and Mac. You might get away with using less if you are running on native Linux since it seems to manage memory better when using Docker 🤷
  1. Docker must be installed. The installation process looks different depending on the operating system:
  1. VS Code must be installed. Once VS Code is installed, install the Remote Development Extension Pack.

Screenshot 2024-05-03 010632

Devcontainer Setup Steps

  1. Ensure that the docker daemon is running. You can check that docker --version returns an error-free output in the CLI. If you installed Docker Desktop for Windows or MacOS, starting it will start the docker daemon.
  1. Clone this repository:
cd ${HOME} && git clone https://github.com/DFriend01/os161_devcontainer.git

Important

If you are in Windows WSL, the devcontainer must be cloned within the WSL network.

It is recommended that you install Windows Terminal and use the Ubuntu profile when working in WSL. Ensure the starting directory is your home directory ~ or /home/<USERNAME>. If not, you will need to change the starting directory field for the Ubuntu profile to //wsl.localhost/<DISTRO NAME>/home/<USERNAME>. See the windows terminal documentation.

  1. Clone your OS161 source code into the devcontainer:

Important

Your os161 code must be contained inside os161_devcontainer/os161/src

If you already have a repository for os161

cd os161_devcontainer/os161 && git clone <REPO URL> src

If you do not have a repository for os161

The instructions are adapted from here.

First, create an empty repository on GitHub (probably a private repo if this is for a course). Then, set up the repository locally:

# Create the source directory for development
mkdir os161_devcontainer/os161/src
cd os161_devcontainer/os161/src

# Set up the git repository
echo "# os161" >> README.md
git init
git add README.md
git commit -m "Initial commit"
git branch -M main
git remote add origin <REPO URL>
git push -u origin main

Get a copy of the source code and push to main:

# Ensure that you are inside the src directory
# If wget fails with error 404, also try getting the source from
# http://www.os161.org/download
wget http://people.ece.ubc.ca/os161/download/os161-CPEN331-base-2016.tar.gz \
&& tar -xvzf os161-CPEN331-base-2016.tar.gz \
&& rm os161-CPEN331-base-2016.tar.gz

git commit -am "Initial commit of os161"
git push origin main
  1. Start VS Code with the os161_devcontainer as the project directory:
# Check that the path ends in 'os161_devcontainer'
cd ../.. && pwd
code .
  1. VS Code should prompt you to reopen in the devcontainer. Accept the prompt.

Screenshot 2024-05-03 012924

If VS Code does not prompt anything, then open the VS Code command palette with ctrl + shift + p (you should see the > character) then search for Dev Containers: Rebuild and Reopen in Container and select that option. When the build starts, VS Code gives you the option to view the logs during the build process (click on Starting Dev Container (show log) on the bottom-right).

Screenshot 2024-05-03 013433

Wait for the devcontainer to finish building. Subsequent builds should be quicker.

Note

If you experience the error "Missing GCLIB >= 2.28" (or something similar) when building the devcontainer, this is a result of a breaking change that was made in recent updates to VS Code. There was a GitHub issue related to this problem here. However, the easiest workaround is to downgrade to VS Code 1.85 and disable auto updates.

  1. Open the os161.code-workspace file and click the "Open Workspace" button. You should see a purple border on your VS Code window.

Screenshot 2024-05-03 015724

Screenshot 2024-05-03 020037

This will provide access to VS Code settings and configurations specific to the devcontainer using a VS Code Workspace.

  1. Build your kernel with ctrl + shift + b and selecting a kernel to configure (i.e. DUMBVM). You can also do it yourself by following the instructions here.
  1. Open a new terminal Terminal > New Terminal and then run your kernel Run > Start Debugging. Alternatively, the kernel can also be started in the command line:
cd $WORKSPACE_DIR/os161/root && sys161 kernel
  1. ctrl + shift + p and Tasks: Run Task gives a list of a few common tasks that have been automated (running the kernel, building, and cleaning).

Clone this wiki locally