To develop the Pintos projects, you’ll need two essential sets of tools:
To get started, you need to clone the Pintos source code distribution we provided:
$ git clone https://github.com/jhu-cs318/pintos.git
The CS department’s lab machines
already have these tools available under /usr/local/data/cs318/x86_64. You just
need to modify your PATH setting to include it. For Bash, that is to put the following
at the end of your ~/.bash_profile:
$ export PATH=/usr/local/data/cs318/x86_64/bin:$PATH
For tcsh (the default login shell in ugrad lab machines in the CS department),
the syntax is different: add set path = (/usr/local/data/cs318/x86_64/bin $path)
to the end of your ~/.tcshrc. Log out and re-login to let it take effect.
Besides the lab machines, you may want to work on the projects on your own machines to be more productive. This page contains instructions to help you with the setup of the core development environment needed for Pintos on your own machines. They are intended for Unix and Mac OS machines. If you are running Windows, we recommend you to run a virtual machine with Linux or you will have to setup Cygwin first. This guide, and the course in general, assumes you are familiar with Unix commands.
The best Pintos development environment is your laptop/desktop. For Linux distributions, Ubuntu 18.04 is what we use. But it is ok to use others like Ubuntu 20.04 or Fedora. Mac computers work, too. If you are using a Windows machine, however, we recommend you to install a virtual machine.
69c89938d4b768bdcca4362fd39f06e4. The initial login password is
jhucs318.
The compiler toolchain is a collection of tools that turns source code into binary
executables for a target architecture. Pintos is written in C and
x86 assembly, and runs on 32-bit x86 machines. So we will need the appropriate
C compiler (gcc), assembler (as), linker (ld) and debugger (gdb).
If you are using a Linux machine, it is likely equipped with the compiler toolchain already.
But it should support 32-bit x86 architecture. A quick test of the support is to run
objdump -i | grep elf32-i386 in the terminal. If it returns matching lines, your
system’s default tool chain supports the target, then you can skip Section 2.2.
Otherwise, you will need to build the toolchain from source.
objdump -i test won't work.
objdump -i test.
However, you will likely encounter an issue later presumably due to a gcc 7 toolchain
bug (see discussion). It is
recommended that you build the toolchain from source according to Section 2.2.
sudo apt-get install build-essential gdb gcc-multilib.
The objdump -i test should pass.
When you are building the toolchain from source, to distinguish the new toolchain
from your system’s default one, you should add a i386-elf- prefix to the build
target, e.g., i386-elf-gcc, i386-elf-as.
make, gcc, etc. To build GDB, you will need the ncurses and textinfo libraries.$ sudo apt-get install build-essential automake git libncurses5-dev texinfo
pintos/src/misc/toolchain-build.sh)
that automates the building instructions. So you can just run the script and
modify your PATH setting after the build finishes. The script has been tested on
recent version of Ubuntu, Mac OS and Fedora.
Replace /path/to/setup below with a real path to store
the toolchain source and build, e.g., /home/ryan/318/toolchain; and replace
/path/to/pintos with the real path where you cloned the pintos repo, e.g.,
~/318/pintos.
$ SWD=/path/to/setup
$ mkdir -p $SWD
$ cd /path/to/pintos
$ src/misc/toolchain-build.sh $SWD
If the above commands succeeded, add the toolchain path to your PATH environment variable settings in the .bashrc
(or .zshrc if you are using zsh) file in your home directory.
$ export PATH=$SWD/x86_64/bin:$PATH
Don’t forget to replace the $SWD above with the real path, e.g.,
export PATH=/home/ryan/318/toolchain/x86_64/bin:$PATH.
If you are curious to build the toolchain manually, below are the detailed instructions.
~/318/toolchain) and subdirectories that look like this:
/path/to/setup
├── build
├── x86_64
└── src
/path/to/setup with the
full path to the actual setup directory you’ve created, e.g., SWD=/home/ryan/318/toolchain).
$ SWD=/path/to/setup
$ PREFIX=$SWD/x86_64
$ export PATH=$PREFIX/bin:$PATH
$ export LD_LIBRARY_PATH=$PREFIX/lib:$LD_LIBRARY_PATH
For Mac users, the last command is export DYLD_LIBRARY_PATH=$PREFIX/lib:$DYLD_LIBRARY_PATH instead.
$ cd $SWD/src
$ wget https://ftp.gnu.org/gnu/binutils/binutils-2.27.tar.gz && tar xzf binutils-2.27.tar.gz
$ mkdir -p $SWD/build/binutils && cd $SWD/build/binutils
$ ../../src/binutils-2.27/configure --prefix=$PREFIX --target=i386-elf \
--disable-multilib --disable-nls --disable-werror
$ make -j8
$ make install
$ cd $SWD/src
$ wget https://ftp.gnu.org/gnu/gcc/gcc-6.2.0/gcc-6.2.0.tar.bz2 && tar xjf gcc-6.2.0.tar.bz2
$ cd $SWD/src/gcc-6.2.0 && contrib/download_prerequisites
$ mkdir -p $SWD/build/gcc && cd $SWD/build/gcc
$ ../../src/gcc-6.2.0/configure --prefix=$PREFIX --target=i386-elf \
--disable-multilib --disable-nls --disable-werror --disable-libssp \
--disable-libmudflap --with-newlib --without-headers --enable-languages=c,c++
$ make -j8 all-gcc
$ make install-gcc
$ make all-target-libgcc
$ make install-target-libgcc
$ cd $SWD/src
$ wget https://ftp.gnu.org/gnu/gdb/gdb-7.9.1.tar.xz && tar xJf gdb-7.9.1.tar.xz
$ mkdir -p $SWD/build/gdb && cd $SWD/build/gdb
$ ../../src/gdb-7.9.1/configure --prefix=$PREFIX --target=i386-elf --disable-werror
$ make -j8
$ make install
Now check if the toolchain has been installed to the proper place and the version is 6.2.0:
$ which i386-elf-gcc
$ i386-elf-gcc --version
If you see the command not found error message, check if you have added export PATH=$SWD/x86_64/bin:$PATH
to your .bashrc or .zshrc (depending on your shell echo $SHELL).
If so, you may need to restart your terminal for the new PATH to take effect.
You may also want to delete the source and build directories in $SWD/{src,build}
to save space.
Besides the cross-compiler toolchain, we also need an x86 emulator to run Pintos OS. We will use two popular emulators QEMU and Bochs.
sudo apt-get install qemubrew install qemupintos/src/misc/bochs*.patch. We will build two versions of
Bochs: one, simply named bochs, with the GDB stub enabled, and the other,
named bochs-dbg, with the built-in debugger enabled.pintos/src/misc/bochs-2.6.2-build.sh that
will download, patch and build two versions of the Bochs for you.
But you need to make sure X11 and its library is installed.
sudo apt-get install libx11-dev libxrandr-dev($SWD should be set previously, e.g., /home/ryan/318/toolchain)
$ src/misc/bochs-2.6.2-build.sh $SWD/x86_64
bochs or bochs-db are in PATH. You
can verify the install with bochs -h. The output should contain 2.6.2.The Pintos source distribution comes with a few handy scripts that you will be
using frequently. They are located within src/utils/. The most important one is
the pintos Perl script, which you will be using to start and run tests
in pintos. You need to make sure it can be found in your PATH environment
variable. In addition, the src/misc/gdb-macros is provided with a number of
GDB macros that you will find useful when you are debugging Pintos. The pintos-gdb
is a wrapper around the i386-elf-gdb that reads this macro file at start.
It assumes the macro file resides in ../misc.
The commands to do the above setup for the Pintos utilities are:
(make sure SWD is set previously to the correct directory path)
$ dest=$SWD/x86_64
$ cd pintos/src/utils && make
$ cp backtrace pintos Pintos.pm pintos-gdb pintos-set-cmdline pintos-mkdisk setitimer-helper squish-pty squish-unix $dest/bin
$ mkdir $dest/misc
$ cp ../misc/gdb-macros $dest/misc