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.8.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 GSX Server}.  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 @command{pintos}, @command{pintos-gdb}, @command{pintos-mkdisk} into the
  83 default @env{PATH}.
  84
  85 @item
  86 Install @file{src/misc/gdb-macros} in a public location.  Then use a
  87 text editor to edit the installed copy of @command{pintos-gdb}, changing
  88 the definition of @env{GDBMACROS} to point to where you installed
  89 @file{gdb-macros}.  Test the installation by running
  90 @command{pintos-gdb} without any arguments.  If it does not complain
  91 about missing @file{gdb-macros}, it is installed correctly.
  92
  93 @item
  94 Compile the remaining Pintos utilities by typing @command{make} in
  95 @file{src/utils}.  Install @file{squish-pty} somewhere in @env{PATH}.
  96 If your Perl is older than version 5.8.0, also install
  97 @file{setitimer-helper}; otherwise, it is unneeded.
  98
  99 @item
 100 Pintos should now be ready for use.  If you have the Pintos reference
 101 solutions, which are provided only to faculty and their teaching
 102 assistants, then you may test your installation by running @command{make
 103 check} in the top-level @file{tests} directory.  The tests take between
 104 20 minutes and 1 hour to run, depending on the speed of your hardware.
 105
 106 @item
 107 Optional: Build the documentation, by running @command{make dist} in the
 108 top-level @file{doc} directory.  This creates a @file{WWW} subdirectory
 109 within @file{doc} that contains HTML and PDF versions of the
 110 documentation, plus the design document templates and various hardware
 111 specifications referenced by the documentation.  Building the PDF
 112 version of the manual requires Texinfo and @TeX{} (see above).  You may
 113 install @file{WWW} wherever you find most useful.
 114 @end enumerate
 115
 116 @menu
 117 * Building Bochs for Pintos::
 118 @end menu
 119
 120 @node Building Bochs for Pintos
 121 @section Building Bochs for Pintos
 122
 123 Upstream Bochs has bugs and warts that should be fixed when used with
 124 Pintos.  Thus, Bochs should be installed manually for use with Pintos,
 125 instead of using the packaged version of Bochs included with an
 126 operating system distribution.
 127
 128 Two different Bochs binaries should be installed.  One, named simply
 129 @command{bochs}, should have the GDB stub enabled, by passing
 130 @option{--enable-gdb-stub} to the Bochs @command{configure} script.  The
 131 other, named @command{bochs-dbg}, should have the internal debugger
 132 enabled, by passing @option{--enable-debugger} to @command{configure}.
 133 (The @command{pintos} script selects a binary based on the options
 134 passed to it.)  In each case, the X, terminal, and ``no GUI'' interfaces
 135 should be configured, by passing @option{--with-x --with-x11 --with-term
 136 --with-nogui} to @command{configure}.
 137
 138 This version of Pintos is designed for use with Bochs 2.2.6.  A number
 139 of patches for this version of Bochs are included in @file{src/misc}:
 140
 141 @table @file
 142 @item bochs-2.2.6-big-endian.patch
 143
 144 Makes the GDB stubs work on big-endian systems such as Solaris/Sparc, by
 145 doing proper byteswapping.  It should be harmless elsewhere.
 146
 147 @item bochs-2.2.6-jitter.patch
 148
 149 Adds the ``jitter'' feature, in which timer interrupts are delivered at
 150 random intervals (@pxref{Debugging versus Testing}).
 151
 152 @item bochs-2.2.6-triple-fault.patch
 153
 154 Causes Bochs to break to GDB when a triple fault occurs and
 155 the GDB stub is active (@pxref{Triple Faults}).
 156
 157 @item bochs-2.2.6-ms-extensions.patch
 158
 159 Needed for Bochs to compile with GCC on some hosts.  Probably
 160 harmless elsewhere.
 161
 162 @item bochs-2.2.6-solaris-tty.patch
 163
 164 Needed for Bochs to compile in terminal support on Solaris
 165 hosts.  Probably harmless elsewhere.
 166
 167 @item bochs-2.2.6-solaris-link.patch
 168
 169 Needed on Solaris hosts.  Do not apply it elsewhere.
 170 @end table
 171
 172 To apply all the patches, @command{cd} into the Bochs directory, then
 173 type:
 174 @example
 175 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch
 176 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch
 177 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch
 178 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch
 179 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch
 180 patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch
 181 @end example
 182 @noindent
 183 You will have to supply the proper @env{$PINTOSDIR}, of course.  You can
 184 use @command{patch}'s @option{--dry-run} option if you want to test
 185 whether the patches would apply cleanly before trying to apply them.
 186
 187 Sample commands to build and install Bochs for Pintos are supplied in
 188 @file{src/misc/bochs-2.2.6-build.sh}.