X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pintos-anon;a=blobdiff_plain;f=doc%2Finstallation.texi;fp=doc%2Finstallation.texi;h=bdcdfc3547426603602c26aab66705f92f487267;hp=0000000000000000000000000000000000000000;hb=392931f3f604f0c8ceb7d97dba21c7fefa2a2187;hpb=7641b4a058aedefcf6430000ec7742881f9e2a9f diff --git a/doc/installation.texi b/doc/installation.texi new file mode 100644 index 0000000..bdcdfc3 --- /dev/null +++ b/doc/installation.texi @@ -0,0 +1,188 @@ +@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}.