Tools Used in CS 134

You'll use two sets of tools in this class: an x86 emulator, QEMU, for running your kernel; and a compiler toolchain, including assembler, linker, C compiler, and debugger, for compiling and testing your kernel. This page has the information you'll need to download and install your own copies. This class assumes familiarity with Unix commands throughout.

We highly recommend using knuth to work on the labs. If you use knuth, then all the software tools you will need for this course are already installed. Just type 'source /cs/cs134/bin/setup.bash' to get access to them.

If you really want to, you can build and install the tools on your own machine. We have instructions below for Linux and MacOS computers.

It should be possible (although untested at this point!) to get this development environment running under windows with the help of Windows Subsystem for Linux. Install that, and then follow the Linux instructions.

For an overview of useful commands in the tools used in CS 134, see the lab tools guide.

Compiler Toolchain

A "compiler toolchain" is the set of programs, including a C compiler, assemblers, and linkers, that turn code into executable binaries. You'll need a compiler toolchain that generates code for 32-bit Intel architectures ("x86" architectures) in the ELF binary format.

Test Your Compiler Toolchain

Modern Linux and BSD UNIX distributions may already provide a toolchain suitable for CS 134. To test your distribution, try the following commands:

% objdump -i

The second line should say elf32-i386.

% gcc -m32 -print-libgcc-file-name

The command should print something like /usr/lib/gcc/i486-linux-gnu/version/libgcc.a or /usr/lib/gcc/x86_64-linux-gnu/version/32/libgcc.a

If both these commands succeed, you're all set, and you probably don't need to compile your own toolchain.

If the gcc command fails, you may need to install a development environment. On Ubuntu Linux, try this:

% sudo apt-get install -y build-essential gdb

On 64-bit machines, you may need to install a 32-bit support library. The symptom is that linking fails with error messages like "__udivdi3 not found" and "__muldi3 not found". On Ubuntu Linux, try this to fix the problem:

% sudo apt-get install gcc-multilib

Building Your Own Compiler Toolchain

Mac OS

First, install brew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then, install the toolchains:
brew install i386-elf-gcc i386-elf-gdb

Other systems

We assume that you are installing the toolchain into /usr/local. You will need a fair amount of disk space to compile the tools (around 1GiB). If you don't have that much space, delete each directory after its make install step.

Download the following packages:

(You may also use newer versions of these packages.) Unpack and build the packages. The green bold text shows you how to install into /usr/local, which is what we recommend. To install into a different directory, $PFX, click herenote the differences in lighter type (hide). If you have problems, see below.

export PATH=$PFX/bin:$PATH
export LD_LIBRARY_PATH=$PFX/lib:$LD_LIBRARY_PATH


tar xjf gmp-5.0.2.tar.bz2
cd gmp-5.0.2
./configure --prefix=/usr/local--prefix=$PFX
make
make install             # This step may require privilege (sudo make install)
cd ..

tar xjf mpfr-3.1.2.tar.bz2
cd mpfr-3.1.2
./configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX
make
make install             # This step may require privilege (sudo make install)
cd ..

tar xzf mpc-0.9.tar.gz
cd mpc-0.9
./configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX --with-mpfr=$PFX
make
make install             # This step may require privilege (sudo make install)
cd ..


tar xjf binutils-2.21.1.tar.bz2
cd binutils-2.21.1
./configure --prefix=/usr/local--prefix=$PFX --target=i386-jos-elf --disable-werror
make
make install             # This step may require privilege (sudo make install)
cd ..

i386-jos-elf-objdump -i
# Should produce output like:
# BFD header file version (GNU Binutils) 2.21.1
# elf32-i386
#  (header little endian, data little endian)
#   i386...


tar xjf gcc-core-4.6.4.tar.bz2
cd gcc-4.6.4
mkdir build              # GCC will not compile correctly unless you build in a separate directory
cd build
../configure --prefix=/usr/local--prefix=$PFX --with-gmp=$PFX --with-mpfr=$PFX --with-mpc=$PFX \
    --target=i386-jos-elf --disable-werror \
    --disable-libssp --disable-libmudflap --with-newlib \
    --without-headers --enable-languages=c MAKEINFO=missing
make all-gcc
make install-gcc         # This step may require privilege (sudo make install-gcc)
make all-target-libgcc
make install-target-libgcc     # This step may require privilege (sudo make install-target-libgcc)
cd ../..

i386-jos-elf-gcc -v
# Should produce output like:
# Using built-in specs.
# COLLECT_GCC=i386-jos-elf-gcc
# COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/i386-jos-elf/4.6.4/lto-wrapper
# Target: i386-jos-elf


tar xjf gdb-9.2.tar.xz
cd gdb-9.2
mkdir build              # GDB will not compile correctly unless you build in a separate directorycd gdb-9.2
cd build
../configure --prefix=/usr/local--prefix=$PFX --target=i386-jos-elf --program-prefix=i386-jos-elf- \
    --disable-werror
make all
make install             # This step may require privilege (sudo make install)
cd ../..

Linux troubleshooting

Q. I can't run make install because I don't have root permission on this machine.
A. Our instructions assume you are installing into the /usr/local directory. However, this may not be allowed in your environment. If you can only install code into your home directory, that's OK. In the instructions above, replace --prefix=/usr/local with --prefix=$HOME (and click here to update the instructions further). You will also need to change your PATH and LD_LIBRARY_PATH environment variables (or, possibly LDPATH, depending on your system), to inform your shell where to find the tools. For example: 
export PATH=$HOME/bin:$PATH
export LD_LIBRARY_PATH=$HOME/lib:$LD_LIBRARY_PATH
Enter these lines in your ~/.bashrc file so you don't need to type them every time you log in.
Q. My build fails with an inscrutable message about "library not found".
A. You need to set your LD_LIBRARY_PATH (or, possibly LDPATH--needed on gentoo, for example). The environment variable must include the PREFIX/lib directory (for instance, /usr/local/lib).

QEMU Emulator

QEMU is a modern and fast PC emulator. QEMU version 2.3.0 is set up on Knuth for x86 machines in the CS 134 directory (source /cs/cs134/bin/setup.bash)

Unfortunately, QEMU's debugging facilities, while powerful, are somewhat immature, so we highly recommend you use our patched version of QEMU instead of the stock version that may come with your distribution. The version installed on Knuth is already patched. To build your own patched version of QEMU:

Install using brew on Mac OS

First, install brew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then, specify that you want to use my tap:
brew tap nrhodes/homebrew-os134sp19

Finally, install qemu with:
brew install nrhodes/homebrew-os134sp19/qemu

Or, Install by hand

  1. Clone the IAP 6828 QEMU git repository git clone https://github.com/mit-pdos/CS 134-qemu.git qemu
  2. On Linux, you may need to install several libraries. We have successfully built CS 134 QEMU on Debian/Ubuntu 16.04 after installing the following packages: libsdl1.2-dev, libtool-bin, libglib2.0-dev, libz-dev, and libpixman-1-dev.
  3. Configure the source code (optional arguments are shown in square brackets; replace PFX with a path of your choice)
    1. Linux: ./configure --disable-kvm --disable-werror [--prefix=PFX] [--target-list="i386-softmmu x86_64-softmmu"]
    2. OS X: ./configure --disable-kvm --disable-werror --disable-sdl [--prefix=PFX] [--target-list="i386-softmmu x86_64-softmmu"] The prefix argument specifies where to install QEMU; without it QEMU will install to /usr/local by default. The target-list argument simply slims down the architectures QEMU will build support for.
  4. Run make && make install
This is derivative work based on MIT 6.828 used under Creative Commons License.

Creative Commons License Top // CS 134 home // Last updated Wed Aug 26 09:15:06 AM PDT 2020