pintos-os.org Git - pintos-anon/blob - doc/installation.texi

   1 @node Installing Pintos
   2 @appendix Installing Pintos
   3
   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.
   8
   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.
  13
  14 Prerequisites for installing a Pintos development environment include
  15 the following, on top of standard Unix utilities:
  16
  17 @itemize @bullet
  18 @item
  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}.
  26
  27 @item
  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.
  33
  34 @item
  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.
  37
  38 @item
  39 Required: @uref{http://www.gnu.org/software/make/, GNU make}, version
  40 3.80 or later.
  41
  42 @item
  43 Recommended: @uref{http://fabrice.bellard.free.fr/qemu/, QEMU}, version
  44 0.11.0 or later.  If QEMU is not available, Bochs can be used, but its
  45 slowness is frustrating.
  46
  47 @item
  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}.
  52
  53 @item
  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.
  57
  58 @item
  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
  61 documentation.
  62
  63 @item
  64 Optional: @uref{http://www.tug.org/, @TeX{}}.  Also required to build
  65 the PDF version of the documentation.
  66
  67 @item
  68 Optional: @uref{http://www.vmware.com/, VMware Player}.  This is a
  69 third platform that can also be used to test Pintos.
  70 @end itemize
  71
  72 Once these prerequisites are available, follow these instructions to
  73 install Pintos:
  74
  75 @enumerate 1
  76 @item
  77 Install @uref{http://bochs.sourceforge.net/, Bochs}, version 2.2.6, as
  78 described below (@pxref{Building Bochs for Pintos}).
  79
  80 @item
  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
  84 @env{PATH}.
  85
  86 @item
  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.
  93
  94 @item
  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.
 100
 101 @item
 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.
 107
 108 @item
 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.
 116
 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
 122 course website.
 123 @end enumerate
 124
 125 @menu
 126 * Building Bochs for Pintos::
 127 @end menu
 128
 129 @node Building Bochs for Pintos
 130 @section Building Bochs for Pintos
 131
 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.
 136
 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}.
 146
 147 This version of Pintos is designed for use with Bochs 2.6.11.  A number
 148 of patches for this version of Bochs are included in @file{src/misc}:
 149
 150 @table @file
 151 @item bochs-2.6.11-banner-stderr.patch
 152
 153 Prints startup boilerplate information to stderr instead of stdout.
 154
 155 @item bochs-2.6.11-jitter-plus-segv.patch
 156
 157 Adds the ``jitter'' feature, in which timer interrupts are delivered at
 158 random intervals (@pxref{Debugging versus Testing}). Also makes the
 159 GDB stub report a SIGSEGV to the debugger when a page-fault
 160 exception occurs, instead of ``signal 0.''  The former can be ignored
 161 with @code{handle SIGSEGV nostop} but the latter cannot.
 162
 163 @item bochs-2.6.11-link-tinfo.patch
 164
 165
 166 Patches the build mechanism to include the -ltinfo library; doesn't
 167 change any functionality.
 168 @end table
 169
 170 The best way to build Bochs is by invoking
 171 @code{src/misc/bochs-2.6.11-build.sh}. This should be invoked in
 172 a directory containing the Bochs distribution file
 173 (@code{bochs-2.6.11-tar.gz}).
 174 The build script takes a single argument, which provides the destination
 175 for installation (the binaries will be placed in the @code{bin}
 176 subdirectory of that directory).
 177 The script will apply the patches and build both versions of Bochs.
 178
 179 The @code{src/misc} directory also contains patches and build scripts for
 180 older versions of Bochs, if desired. However, these may require
 181 changes elsewhere in Pintos. For example, @code{src/utils/pintos}
 182 had to be modified for Bochs 2.6.11; if you use an older version of
 183 Bochs you will need to back out those changes.