To gain experience setting up a Pintos development environment on Windows Subsystem for Linux (WSL), I followed the instructions at Pintos Projects: Installing Pintos🔗 to get Pintos to run on my machine. Here is a recap of the process with additional steps I had to take.

These instructions assume use of Ubuntu on WSL with the APT package manager. This is the experience reflected in this article. For other distros it is mainly a matter of where to get the various packages.

Step 1: Get Pintos directly

For the most current Pintos for this tutorial, I cloned it directly from the source. This was found at Pintos Projects: Introduction🔗.

git clone http://cs212.scs.stanford.edu/pintos.git

Step 2: Pre-requisites

Get the required utilities:

  • gcc - The GNU C Compiler.
  • binutils - Additional utilities.
  • perl - For additional scripts.
  • make - Common build tool for C/C++ projects.

Now. There are some additional steps.

Added pre-requisite 1: Windows paths in WSL

By default, your Windows PATH variable entries are also on your WSL PATH. This messes with the build script for Bochs, so I had to adjust my WSL configuration.

Get hold of the configuration for the WSL. On Ubuntu as follows:

sudo nano /etc/wsl.conf

Add this:

[interop]
enabled = true
appendWindowsPath = false

Then restart the WSL:

wsl --shutdown

Finally, reopen your WSL terminal and check:

echo $PATH

Added pre-requisite 2: VS Code with WSL

Without the paths from Windows, I cannot run VS Code from our WSL shell. To get VS Code to work again, add the path to its WSL launcher to ~/.bashrc like so:

export PATH="$PATH:/mnt/c/Program Files/Microsoft VS Code/bin"

Then reload the shell:

source ~/.bashrc

Added pre-requisite 3: X11 libraries

The build script for Bochs will want the X11 libraries for the Windows GUI when on WSL. (This is uniquely a problem for WSL users.)

Here is the script to install those:

sudo apt update
sudo apt install libx11-dev libxext-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev

Added pre-requisite 4: g++ compiler

This is not mentioned in the instructions, but came up when running the Bochs build script. Get hold of the g++ compiler for C++:

sudo apt install g++

Added pre-requisite 5: Curses library

This was another hick-up. The build script requires some version of the Curses library:

sudo apt install libncurses-dev

Added pre-requisite 6: .bashrc entries

I added these paths to my .bashrc, following the Pintos installation instructions:

# Pintos project
export GDBMACROS="/home/rono/repos/pintos/src/misc/gdb-macros"
export PATH="$PATH:/home/rono/repos/pintos/src/utils"

Step 2: Building Bochs

With the pre-requisites fulfilled, I can now run the build script from the Pintos repository in ./src/misc and install Bochs:

sudo sh bochs-2.6.11-build.sh /usr

Here, /usr is where Bochs will be placed. I chose another target initially to test the builder, and I suggest you do the same.

This will run a lengthy build script. When done, I should have access to bochs in the shell. If not, I will check the script printouts for errors to resolve.

Excerpt from shell terminal running bochs:

========================================================================
                       Bochs x86 Emulator 2.6.11
              Built from SVN snapshot on January 5, 2020
                Timestamp: Sun Jan  5 08:36:00 CET 2020
========================================================================
00000000000i[      ] BXSHARE not set. using compile time default '/usr/share/bochs'
------------------------------
Bochs Configuration: Main Menu
------------------------------

This is the Bochs Configuration Interface, where you can describe the
machine that you want to simulate.  Bochs has already searched for a
configuration file (typically called bochsrc.txt) and loaded it if it
could be found.  When you are satisfied with the configuration, go
ahead and start the simulation.

You can also start bochs with the -q option to skip these menus.

1. Restore factory default configuration
2. Read options from...
3. Edit options
4. Save options to...
5. Restore the Bochs state from...
6. Begin simulation
7. Quit now

Please choose one: [2]

Step 3: Testing Pintos

With all the pre-requisites in place, it should be possible to test Pintos. To build and test it:

  1. Navigate to ./src/threads and run the Make file. (make).
  2. Navigate to the ./build just created. Run make check to run the tests.

Some of the tests should pass. Here is an excerpt from terminal of how the tests behave for me on the initial project:

pass tests/threads/alarm-single
pass tests/threads/alarm-multiple
pass tests/threads/alarm-simultaneous
FAIL tests/threads/alarm-priority
pass tests/threads/alarm-zero
pass tests/threads/alarm-negative
FAIL tests/threads/priority-change
FAIL tests/threads/priority-donate-one
FAIL tests/threads/priority-donate-multiple
FAIL tests/threads/priority-donate-multiple2
FAIL tests/threads/priority-donate-nest
FAIL tests/threads/priority-donate-sema
FAIL tests/threads/priority-donate-lower
FAIL tests/threads/priority-fifo
FAIL tests/threads/priority-preempt
FAIL tests/threads/priority-sema
FAIL tests/threads/priority-condvar
FAIL tests/threads/priority-donate-chain
FAIL tests/threads/mlfqs-load-1
FAIL tests/threads/mlfqs-load-60
FAIL tests/threads/mlfqs-load-avg
FAIL tests/threads/mlfqs-recent-1
pass tests/threads/mlfqs-fair-2
pass tests/threads/mlfqs-fair-20
FAIL tests/threads/mlfqs-nice-2
FAIL tests/threads/mlfqs-nice-10
FAIL tests/threads/mlfqs-block
20 of 27 tests failed.

If bochs is unavailable, none of the tests will be able to run at all.

Upon close inspection, the build directory has a subdirectory ./tests/threads. This contains for each test test-name:

  1. test-name.errors with diagnostics output from the Bochs emulator.
  2. test-name.output with the raw output from the test that ran.
  3. test-name.result which either contains the word PASS, or the word FAIL followed by a detailed explanation as expected with Test Driven Development.