[pintos-anon] / doc / installation.texi

@node Installing Pintos
@appendix Installing Pintos

This chapter explains how to install a Pintos development environment on
your own machine.  If you are using a Pintos development environment
that has been set up by someone else, you do not need to read this
chapter or follow these instructions.

The Pintos development environment is targeted at Unix-like systems.  It
has been most extensively tested on GNU/Linux, in particular the Debian
and Ubuntu distributions, and Solaris.  It is not designed to install
under any form of Windows.

Prerequisites for installing a Pintos development environment include
the following, on top of standard Unix utilities:

@itemize @bullet
@item
Required: @uref{http://gcc.gnu.org/, GCC}.  Version 4.0 or later is
preferred.  Version 3.3 or later should work.  If the host machine has
an 80@var{x}86 processor, then GCC should be available as @command{gcc};
otherwise, an 80@var{x}86 cross-compiler should be available as
@command{i386-elf-gcc}.  A sample set of commands for installing GCC
3.3.6 as a cross-compiler are included in
@file{src/@/misc/@/gcc-3.3.6-cross-howto}.

@item
Required: @uref{http://www.gnu.org/software/binutils/, GNU binutils}.
Pintos uses @command{addr2line}, @command{ar}, @command{ld},
@command{objcopy}, and @command{ranlib}.  If the host machine is not an
80@var{x}86, versions targeting 80@var{x}86 should be available with an
@samp{i386-elf-} prefix.

@item
Required: @uref{http://www.perl.org, Perl}.  Version 5.8.0 or later is
preferred.  Version 5.6.1 or later should work.

@item
Required: @uref{http://www.gnu.org/software/make/, GNU make}, version
3.80 or later.

@item
Recommended: @uref{http://fabrice.bellard.free.fr/qemu/, QEMU}, version
0.8.0 or later.  If QEMU is not available, Bochs can be used, but its
slowness is frustrating.

@item
Recommended: @uref{http://www.gnu.org/software/gdb/, GDB}.  GDB is
helpful in debugging (@pxref{GDB}).  If the host machine is not an
80@var{x}86, a version of GDB targeting 80@var{x}86 should be available
as @samp{i386-elf-gdb}.

@item
Recommended: @uref{http://www.x.org/, X}.  Being able to use an X server
makes the virtual machine feel more like a physical machine, but it is
not strictly necessary.

@item
Optional: @uref{http://www.gnu.org/software/texinfo/, Texinfo}, version
4.5 or later.  Texinfo is required to build the PDF version of the
documentation.

@item
Optional: @uref{http://www.tug.org/, @TeX{}}.  Also required to build
the PDF version of the documentation.

@item
Optional: @uref{http://www.vmware.com/, VMware Player}.  This is a
third platform that can also be used to test Pintos.
@end itemize

Once these prerequisites are available, follow these instructions to
install Pintos:

@enumerate 1
@item
Install @uref{http://bochs.sourceforge.net/, Bochs}, version 2.2.6, as
described below (@pxref{Building Bochs for Pintos}).

@item
Install scripts from @file{src/utils}.  Copy @file{backtrace},
@file{pintos}, @file{pintos-gdb}, @file{pintos-mkdisk} into the
default @env{PATH}.

@item 
Install @file{src/misc/gdb-macros} in a public location.  Then use a
text editor to edit the installed copy of @file{pintos-gdb}, changing
the definition of @env{GDBMACROS} to point to where you installed
@file{gdb-macros}.  Test the installation by running
@command{pintos-gdb} without any arguments.  If it does not complain
about missing @file{gdb-macros}, it is installed correctly.

@item
Compile the remaining Pintos utilities by typing @command{make} in
@file{src/utils}.  Install @file{squish-pty} somewhere in @env{PATH}.
To support VMware Player, install @file{squish-unix}.
If your Perl is older than version 5.8.0, also install
@file{setitimer-helper}; otherwise, it is unneeded.

@item
Pintos should now be ready for use.  If you have the Pintos reference
solutions, which are provided only to faculty and their teaching
assistants, then you may test your installation by running @command{make
check} in the top-level @file{tests} directory.  The tests take between
20 minutes and 1 hour to run, depending on the speed of your hardware.

@item
Optional: Build the documentation, by running @command{make dist} in the
top-level @file{doc} directory.  This creates a @file{WWW} subdirectory
within @file{doc} that contains HTML and PDF versions of the
documentation, plus the design document templates and various hardware
specifications referenced by the documentation.  Building the PDF
version of the manual requires Texinfo and @TeX{} (see above).  You may
install @file{WWW} wherever you find most useful.

The @file{doc} directory is not included in the @file{.tar.gz}
distributed for Pintos.  It is in the Pintos CVS tree available via
@code{:pserver:anonymous@@footstool.stanford.edu:/var/lib/cvs}, in the
@code{pintos} module.  The CVS tree is @emph{not} the authoritative
source for Stanford course materials, which should be obtained from the
course website.
@end enumerate

@menu
* Building Bochs for Pintos::   
@end menu

@node Building Bochs for Pintos
@section Building Bochs for Pintos

Upstream Bochs has bugs and warts that should be fixed when used with
Pintos.  Thus, Bochs should be installed manually for use with Pintos,
instead of using the packaged version of Bochs included with an
operating system distribution.

Two different Bochs binaries should be installed.  One, named simply
@command{bochs}, should have the GDB stub enabled, by passing
@option{--enable-gdb-stub} to the Bochs @command{configure} script.  The
other, named @command{bochs-dbg}, should have the internal debugger
enabled, by passing @option{--enable-debugger} to @command{configure}.
(The @command{pintos} script selects a binary based on the options
passed to it.)  In each case, the X, terminal, and ``no GUI'' interfaces
should be configured, by passing @option{--with-x --with-x11 --with-term
--with-nogui} to @command{configure}.

This version of Pintos is designed for use with Bochs 2.2.6.  A number
of patches for this version of Bochs are included in @file{src/misc}:

@table @file
@item bochs-2.2.6-big-endian.patch

Makes the GDB stubs work on big-endian systems such as Solaris/Sparc, by
doing proper byteswapping.  It should be harmless elsewhere.

@item bochs-2.2.6-jitter.patch

Adds the ``jitter'' feature, in which timer interrupts are delivered at
random intervals (@pxref{Debugging versus Testing}).

@item bochs-2.2.6-triple-fault.patch

Causes Bochs to break to GDB when a triple fault occurs and
the GDB stub is active (@pxref{Triple Faults}).

@item bochs-2.2.6-ms-extensions.patch

Needed for Bochs to compile with GCC on some hosts.  Probably
harmless elsewhere.

@item bochs-2.2.6-solaris-tty.patch

Needed for Bochs to compile in terminal support on Solaris
hosts.  Probably harmless elsewhere.

@item bochs-2.2.6-page-fault-segv.patch

Makes the GDB stub report a SIGSEGV to the debugger when a page-fault
exception occurs, instead of ``signal 0.''  The former can be ignored
with @code{handle SIGSEGV nostop} but the latter cannot.

@item bochs-2.2.6-paranoia.patch

Fixes compile error with modern versions of GCC.

@item bochs-2.2.6-solaris-link.patch

Needed on Solaris hosts.  Do not apply it elsewhere.
@end table

To apply all the patches, @command{cd} into the Bochs directory, then
type:
@example
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-page-fault-segv.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-paranoia.patch
patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch
@end example
@noindent
You will have to supply the proper @env{$PINTOSDIR}, of course.  You can
use @command{patch}'s @option{--dry-run} option if you want to test
whether the patches would apply cleanly before trying to apply them.

Sample commands to build and install Bochs for Pintos are supplied in
@file{src/misc/bochs-2.2.6-build.sh}.