--- /dev/null
+@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 GSX Server}. 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},
+@command{pintos}, @command{pintos-gdb}, @command{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 @command{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}.
+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.
+@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-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-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}.
projects / pintos-anon / blobdiff