1 @node Installing Pintos
2 @appendix Installing Pintos
4 This chapter explains how to install a Pintos development environment on
5 your own machine. If you are using a Pintos development environment
6 that has been set up by someone else, you do not need to read this
7 chapter or follow these instructions.
9 The Pintos development environment is targeted at Unix-like systems. It
10 has been most extensively tested on GNU/Linux, in particular the Debian
11 and Ubuntu distributions, and Solaris. It is not designed to install
12 under any form of Windows.
14 Prerequisites for installing a Pintos development environment include
15 the following, on top of standard Unix utilities:
19 Required: @uref{http://gcc.gnu.org/, GCC}. Version 4.0 or later is
20 preferred. Version 3.3 or later should work. If the host machine has
21 an 80@var{x}86 processor, then GCC should be available as @command{gcc};
22 otherwise, an 80@var{x}86 cross-compiler should be available as
23 @command{i386-elf-gcc}. A sample set of commands for installing GCC
24 3.3.6 as a cross-compiler are included in
25 @file{src/@/misc/@/gcc-3.3.6-cross-howto}.
28 Required: @uref{http://www.gnu.org/software/binutils/, GNU binutils}.
29 Pintos uses @command{addr2line}, @command{ar}, @command{ld},
30 @command{objcopy}, and @command{ranlib}. If the host machine is not an
31 80@var{x}86, versions targeting 80@var{x}86 should be available with an
32 @samp{i386-elf-} prefix.
35 Required: @uref{http://www.perl.org, Perl}. Version 5.8.0 or later is
36 preferred. Version 5.6.1 or later should work.
39 Required: @uref{http://www.gnu.org/software/make/, GNU make}, version
43 Recommended: @uref{http://fabrice.bellard.free.fr/qemu/, QEMU}, version
44 0.8.0 or later. If QEMU is not available, Bochs can be used, but its
45 slowness is frustrating.
48 Recommended: @uref{http://www.gnu.org/software/gdb/, GDB}. GDB is
49 helpful in debugging (@pxref{GDB}). If the host machine is not an
50 80@var{x}86, a version of GDB targeting 80@var{x}86 should be available
51 as @samp{i386-elf-gdb}.
54 Recommended: @uref{http://www.x.org/, X}. Being able to use an X server
55 makes the virtual machine feel more like a physical machine, but it is
56 not strictly necessary.
59 Optional: @uref{http://www.gnu.org/software/texinfo/, Texinfo}, version
60 4.5 or later. Texinfo is required to build the PDF version of the
64 Optional: @uref{http://www.tug.org/, @TeX{}}. Also required to build
65 the PDF version of the documentation.
68 Optional: @uref{http://www.vmware.com/, VMware Player}. This is a
69 third platform that can also be used to test Pintos.
72 Once these prerequisites are available, follow these instructions to
77 Install @uref{http://bochs.sourceforge.net/, Bochs}, version 2.2.6, as
78 described below (@pxref{Building Bochs for Pintos}).
81 Install scripts from @file{src/utils}. Copy @file{backtrace},
82 @file{pintos}, @file{pintos-gdb}, @file{pintos-mkdisk},
83 @file{pintos-set-cmdline}, and @file{Pintos.pm} into the default
87 Install @file{src/misc/gdb-macros} in a public location. Then use a
88 text editor to edit the installed copy of @file{pintos-gdb}, changing
89 the definition of @env{GDBMACROS} to point to where you installed
90 @file{gdb-macros}. Test the installation by running
91 @command{pintos-gdb} without any arguments. If it does not complain
92 about missing @file{gdb-macros}, it is installed correctly.
95 Compile the remaining Pintos utilities by typing @command{make} in
96 @file{src/utils}. Install @file{squish-pty} somewhere in @env{PATH}.
97 To support VMware Player, install @file{squish-unix}.
98 If your Perl is older than version 5.8.0, also install
99 @file{setitimer-helper}; otherwise, it is unneeded.
102 Pintos should now be ready for use. If you have the Pintos reference
103 solutions, which are provided only to faculty and their teaching
104 assistants, then you may test your installation by running @command{make
105 check} in the top-level @file{tests} directory. The tests take between
106 20 minutes and 1 hour to run, depending on the speed of your hardware.
109 Optional: Build the documentation, by running @command{make dist} in the
110 top-level @file{doc} directory. This creates a @file{WWW} subdirectory
111 within @file{doc} that contains HTML and PDF versions of the
112 documentation, plus the design document templates and various hardware
113 specifications referenced by the documentation. Building the PDF
114 version of the manual requires Texinfo and @TeX{} (see above). You may
115 install @file{WWW} wherever you find most useful.
117 The @file{doc} directory is not included in the @file{.tar.gz}
118 distributed for Pintos. It is in the Pintos CVS tree available via
119 @code{:pserver:anonymous@@footstool.stanford.edu:/var/lib/cvs}, in the
120 @code{pintos} module. The CVS tree is @emph{not} the authoritative
121 source for Stanford course materials, which should be obtained from the
126 * Building Bochs for Pintos::
129 @node Building Bochs for Pintos
130 @section Building Bochs for Pintos
132 Upstream Bochs has bugs and warts that should be fixed when used with
133 Pintos. Thus, Bochs should be installed manually for use with Pintos,
134 instead of using the packaged version of Bochs included with an
135 operating system distribution.
137 Two different Bochs binaries should be installed. One, named simply
138 @command{bochs}, should have the GDB stub enabled, by passing
139 @option{--enable-gdb-stub} to the Bochs @command{configure} script. The
140 other, named @command{bochs-dbg}, should have the internal debugger
141 enabled, by passing @option{--enable-debugger} to @command{configure}.
142 (The @command{pintos} script selects a binary based on the options
143 passed to it.) In each case, the X, terminal, and ``no GUI'' interfaces
144 should be configured, by passing @option{--with-x --with-x11 --with-term
145 --with-nogui} to @command{configure}.
147 This version of Pintos is designed for use with Bochs 2.2.6. A number
148 of patches for this version of Bochs are included in @file{src/misc}:
151 @item bochs-2.2.6-big-endian.patch
153 Makes the GDB stubs work on big-endian systems such as Solaris/Sparc, by
154 doing proper byteswapping. It should be harmless elsewhere.
156 @item bochs-2.2.6-jitter.patch
158 Adds the ``jitter'' feature, in which timer interrupts are delivered at
159 random intervals (@pxref{Debugging versus Testing}).
161 @item bochs-2.2.6-triple-fault.patch
163 Causes Bochs to break to GDB when a triple fault occurs and
164 the GDB stub is active (@pxref{Triple Faults}).
166 @item bochs-2.2.6-ms-extensions.patch
168 Needed for Bochs to compile with GCC on some hosts. Probably
171 @item bochs-2.2.6-solaris-tty.patch
173 Needed for Bochs to compile in terminal support on Solaris
174 hosts. Probably harmless elsewhere.
176 @item bochs-2.2.6-page-fault-segv.patch
178 Makes the GDB stub report a SIGSEGV to the debugger when a page-fault
179 exception occurs, instead of ``signal 0.'' The former can be ignored
180 with @code{handle SIGSEGV nostop} but the latter cannot.
182 @item bochs-2.2.6-paranoia.patch
184 Fixes compile error with modern versions of GCC.
186 @item bochs-2.2.6-solaris-link.patch
188 Needed on Solaris hosts. Do not apply it elsewhere.
191 To apply all the patches, @command{cd} into the Bochs directory, then
194 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch
195 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch
196 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch
197 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch
198 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch
199 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-page-fault-segv.patch
200 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-paranoia.patch
201 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch
204 You will have to supply the proper @env{$PINTOSDIR}, of course. You can
205 use @command{patch}'s @option{--dry-run} option if you want to test
206 whether the patches would apply cleanly before trying to apply them.
208 Sample commands to build and install Bochs for Pintos are supplied in
209 @file{src/misc/bochs-2.2.6-build.sh}.