%%$Id: installbinary.tex,v 1.10 2009-03-02 16:15:15 potyra Exp $
%% vim:tabstop=8:shiftwidth=8:textwidth=72

% Copyright (C) 2003-2009 FAUmachine Team <info@faumachine.org>.
% This program is free software. You can redistribute it and/or modify it
% under the terms of the GNU General Public License, either version 2 of
% the License, or (at your option) any later version. See COPYING.

This chapter briefly lists the hardware and software requirements which
need to be fulfilled to run \package. You then learn how to install the
precompiled \package-binaries from a tarball, rpm or debian package.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Requirements}
\label{s:installbinary.requirements}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
This section tells you, what kind of hardware and operating system you
will need to run a \package virtual machine.
\notgb{%% Leave this here for DBench cross-compilation!
The requirements for
building \package from scratch are much more extensive and are listed
in chapter \ref{s:buildfromsource} "\cbuildfromsource".
}%\notgb

%%======================================================================
\subsection{Hardware}
\label{s:installbinary.requirements.hw}
%%======================================================================
Except for the fact, that the processor must be an Intel i386 or
compatible, there are no known special hardware requirements.

You should keep in mind, though, that apart from the space needed to
install a minimal \package binary distribution, you will need enough
room on your harddisk for the harddisks of the virtual machines you
create as well as their main memory.
The files containing the disk-images and memory-images of the virtual
machines cannot be split across partitions.

Of course, the faster your hardware is, the faster the virtual machines
will be, too.
You should have enough main memory for both the guest and the host
operating system. Otherwise, performance will drop dramatically
as the host operating system is forced to use swap space.


%%======================================================================
\subsection{Software}
\label{s:installbinary.requirements.sw}
%%======================================================================
\package currently only runs on Linux.
We have completed a raw prototype running on Windows with Cygwin
installed as a feasibility study, but due to the lack of manpower, we
currently do not pursue the Windows/Cygwin port.

The precompiled \package binaries and kernels should run on all
default 2.4
kernel-versions, i.e. \package should work fine on any current Linux
distribution (except Debian, which still uses a 2.2 kernel per
default; however, Debian provides an upgrade package to a 2.4 kernel).

As we currently do not provide \package binaries for 2.2 kernels, if
you need \package to run on a 2.2 kernel you will need to compile it
yourself. You might also have to compile your own \package binaries if
you built your own kernel and changed parameters concerning the
placement and size of your kernel's kernel memory (for details see
chapter \ref{s:buildfromsource}).

Because of the simulation method used by \package, you need
kernels and boot loaders which are modified to run in the simulator.
Several modified versions are already available for major distributions.
Upon boot, the bootloader and kernel from your simulated system
will be replaced by the corresponding modified version provided by
\package. I.e., if you want to run SuSE 8.2 on FAUmachine, you will need
to install the \distpackage-suse-8.2 package in addition to
\distpackage-base.

If you think \package runs a little slow, we do have kernel patch for
some kernel versions which will speed up \package. To install it on your
real machine would entail patching the kernel sources and
building/installing a new kernel. If you are interested in the patch,
send an email to \mailfaum.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Installation}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Version \version of \package includes rpms for SuSE 8.1, SuSE 8.2 and
SuSE 9.0 as well as for RedHat
8.0 and RedHat 9. There are debs for Debian 3.0r0 and a tarball for all
the rest.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installation of \package Binary RPM}
\label{s:installbinary.rpm}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Download the current rpms from our download area at \wwwfaum.
To get the files necessary for the distribution on your real machine,
follow the appropriate link. For each real system, the following files
are available:
\begin{itemize}
\item{\distpackage-base-\version-1.i386.rpm:\newline the basic binaries
(configuration wizard, simulator, network bridge, etc.)
}
\item{\distpackage-debian-*-\version-1.i386.rpm,\newline
	\distpackage-redhat-*-\version-1.i386.rpm,\newline
	\distpackage-suse-*-\version-1.i386.rpm:\newline
	bootloaders and kernels of the respective distribution
	precompiled to run on FAUmachine. I.e. if you want to run Redhat
	8.0 on your FAUmachine, you will need to install the
	\distpackage-redhat-8.0-\version-1.i386.rpm.}
\end{itemize}
You will need at least the base-package and one of the support packages.

To install the rpms you will need to be root. Type
\begin{alltt}
rpm -hiv \replaceable{packagename}
\end{alltt}
at the command prompt to install the package.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installation of \package Binary Debian Package}
\label{s:installbinary.pkg}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

You can tell your \command{apt} about \package by adding the line
\begin{alltt}
deb http://www3.informatik.uni-erlangen.de/FAUmachine/debian ./
\end{alltt}
to
\Filename{/etc/apt/sources.list}, then execute
\command{apt-get update} and \command{apt-get install faumachine}
as root.
You can update these packages through the usual
\command{apt-get upgrade}.

You can also download the current debs from our download area at
\wwwfaum (follow the appropriate link).
\begin{itemize}
\item{\distpackage-base\_0-\version.1\_i386.deb:\newline
	the basic binaries
	(configuration wizard, simulator, network bridge, etc.)
}
\item{\distpackage-debian-*\_0-\version.1\_i386.deb,\newline
	\distpackage-redhat-*\_0-\version-1\_i386.deb,\newline
	\distpackage-suse-*\_0-\version-1\_i386.deb:\newline
	bootloaders and kernels of the respective distribution
	precompiled to run on FAUmachine. I.e. if you want to run Redhat
	8.0 on your FAUmachine, you will need to install the
	\distpackage-redhat-8.0\_0-\version-1\_i386.deb. }
\end{itemize}
You will need at least the base-package and one of the support packages.

To install the debs you will need to be root. Type
\begin{alltt}
apt-get install \replaceable{package}
\end{alltt}
at the command prompt to install the package.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Installation of \package Binary Tarball}
\label{s:installbinary.tar}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Download the current binary tarball
\Filename{\distpackage-\version.tar.gz} from our download area at
\wwwfaum. This contains the virtual machine, graphical user interface
and ready-to-run \package-kernels for the supported distributions.
This is all you need to get started.

If you want other kernels, it becomes more difficult, as you will have
to build these yourself. Please refer to chapter
\ref{s:buildfromsource}.

Extract the tarball into directory of your choice, e.g. using the
command\newline \command{tar xzf \Filename{\distpackage-\version.tar.gz}}.
This directory will be referred to as \package install directory from
now on.

After extracting the binary tarball you will have several subdirectories
called
\bindir, \libdir, \mandir, and \docdir.
The following list gives an overview.
\begin{description}
\item[\bindir/]{\anchor\newline
	\package{} program binaries for graphical frontend, virtual
	machines and automatic experiment controller.
}
\item[\docdir]{\anchor\newline
	This \package{} documentation as HTML and PDF.
}
\item[\kernelsdir/]{\anchor\newline
	Precompiled \package-kernels for Debian3.0r0, SuSE 8.1, SusE 8.2,
	RedHat8.0, RedHat9.
}
\item[\toolsdir/]{\anchor\newline
	Additional binaries, useful in combination with the
	automatic experiment controller.
}
\item[\vhdldir/]{\anchor\newline
	VHDL libraries needed for scripting the automatic
	experiment controller.
}
\item[\xpmdir/]{\anchor\newline
	Pixmaps for the graphical frontend.
}
\item[\mandir]{\anchor\newline
	\command{man} pages.
}
\end{description}

Add \bindir of your \package install directory to the PATH environment
variable so that your shell can find the binaries
automatically or call \binlauncher with an absolute path.
All programs part of \package automatically load the
necessary libraries (they figure out the path to the library from the
path used to call \binlauncher), so no further configuration is necessary.

