%
% x-kernel v3.3
%
% Copyright (c) 1996,1993,1991,1990  Arizona Board of Regents
%

\section{Building {\xS}}

This section describes the procedures that should be followed to install,
configure, build the {\xk}, and build and run {\xS} as a Unix process.
We assume the following throughout the rest of this note.

\begin{itemize}
\item
You will be installing the {\xk} in directory {\var /usr/xkernel}, and this
directory is reachable (via NSF, for example) from all machines on which
you want to run {\xS}.
You may choose some root directory other than {\var /usr/xkernel}.
If you do select another root directory, change the steps given below
accordingly.

\item
You will be running {\xS} on a Solaris (Sparc) workstation.
If you are building {\xS} on some other Unix platform---SunOS (on Sparc)
or OSF/1 (on Alpha)---then substitute {\var sunos} or {\var osf1} for
{\var solaris}, respectively, in the steps that follow.
\end{itemize}

\subsection{The Steps}

\begin{enumerate}
\item 
Create directory {\var /usr/xkernel} and use anonymous FTP to copy file
{\var xkernel.tar.Z} from {\var cs.arizona.edu/xkernel} into this directory.
Then type:

\begin{quote}
{\var cd /usr/xkernel}\\
{\var uncompress xkernel.tar.Z}\\
{\var tar xf xkernel.tar}
\end{quote}

This will create several subdirectories in {\var /usr/xkernel}.
A description of the {\xk} directory hierarchy can be found in
{\var /usr/xkernel/README}.
Note that you can skip this step if you are not the first person to install
and use the {\xk} or {\xS} at your site.

\item
Create a directory in which you will build an instance of {\xS}.
This is called your build directory, and in general, each different
configuration of the {\xk} and {\xS} has its own build directory.

\begin{quote}
{\var cd /usr/xkernel/simulator/build}\\ 
{\var mkdir solaris}
\end{quote}
If directory {\var /usr/xkernel/simulator/build/solaris} already
exists---because someone else has already followed this procedure---then you
have two choices.

\begin{enumerate}
\item
Select another name for your build directory (e.g., {\var mydir}) and create
a directory with this name in directory {\var /usr/xkernel/simulator/build}.
The catch to this option is that you have to either have write permission in
directory {\var /usr/xkernel/simulator/build}, or you have to have someone
that has write permission create your build directory for you.

\item
Create a build directory in your own home directory; e.g.,
{\var /usr/llp/xsim/solaris}.
This is the preferred approach if a lot of different people are going to be
building the {\xk} or {\xS}.
\end{enumerate}

\noindent
Substitute the name of your build directory, as appropriate, in the rest of
the steps.

\item
Copy configuration files into your build directory.
\begin{quote}
{\var cd /usr/xkernel/simulator/build/solaris}\\
{\var cp ../Template/Makefile.solaris Makefile}\\
{\var cp ../Template/example/* .}\\
{\var mkdir db}\\
{\var chmod 664 *}
\end{quote}

Note that if your build directory is not in
{\var /usr/xkernel/simulator/build}, then you will have to use the full path
names for these various files rather than the relative path names given above
(i.e., {\var /usr/xkernel/simulator/build/Template/example} instead of
{\var ../Template/example}).

\item
Edit the ``{\var XRT =}'' line of the {\var Makefile} you just copied into your
build directory to reflect the root of your {\xk} source tree.
Assuming your tree is at {\var /usr/xkernel}, this means changing

\begin{quote}
{\var XRT = ../../..}
\end{quote}
to
\begin{quote}
{\var XRT = /usr/xkernel}
\end{quote}

Note that this step is necessary only if your build directory is underneath
your home directory.
It is not necessary if your build directory is in
{\var /usr/xkernel/simulator/build} since from there, {\var ../../..} already
points to the root of the {\xk} source tree.

\item
Put {\var /usr/xkernel/bin/solaris-sparc} and {\var /usr/xkernel/bin} in your
search path.
They should appear before {\var /bin} and {\var /usr/bin} in order to pick up
GNU {\var make} before the standard Unix {\var make}.
If you are building {\xS} on a platform other than Solaris, then substitute
{\var sunos-sparc} or {\var osf1-alpha} for {\var solaris-sparc}, as
appropriate.
Also, make sure the GNU C compiler ({\var gcc}) is in your search path.
(At Arizona, {\var gcc} can be found in directory {\var /usr/local/bin}.)

\item
Build libraries necessary for your {\xS}.
This could take quite a while.

\begin{quote}
{\var cd /usr/xkernel/simulator/build/solaris}\\
{\var make system}
\end{quote}

Note that you can skip this step if you are not the first person to build an
{\xS} for this platform.

\item
You are now ready to build your {\xS}.

\begin{quote}
{\var cd /usr/xkernel/simulator/build/solaris}\\
{\var make compose}\\
{\var make depend}\\
{\var make}
\end{quote}

This sequence should result in the creation of the binary file {\var xkernel}
in your build directory.
Note that you may see what appear to be error messages about missing files
(e.g., {\var Makefile.local} and {\var DEPS/Makedep.*}) when you run
{\var make compose}.
These warnings can be ignored.

\item
You are now ready to run your {\xS}.

\begin{quote}
{\var cd /usr/xkernel/simulator/build/solaris}\\
{\var xsim}\\
\end{quote}

\end{enumerate}

\subsection{Debugging}

There are some debugging aids built in to {\xS}.
If you type

\begin{quote}
{\var xsim -h}
\end{quote}

\noindent
{\xS} will print the following help documentation:

\begin{verbatim}
Help for debugging xsim:

  xsim  -xsimdbg  E:<Event codes>  S:<Simulator codes>  T:<Test codes>

    where code strings are 2-letter, event specific codes

         Event codes:
           IQ  show event queue inserts
           RQ  show event queue removals
           SE  show stub executions
           ES  show evSchedule calls
           CI  show clock interupt handler execution
           SQ  show full queue in IQ and RQ
           FN  use function names when listing
           AL  equivalent to all Event codes

         Simulator codes:
           ED  show ethd stuff
           L0  show very detailed simulator stuff
           L1  show detailed simulator stuff
           L2  show coarse simulator stuff
           PC  show packet collision stuff
           AL  equivalent to all Simulator codes

         Test codes:
           ET  show ethtest stuff
           MG  show megtest stuff
           TR  show traffic stuff
           AL  equivalent to all Test codes

 Examples:     xsim -xsimdbg E:ESCIFN S:AL T:MG
           or  xsim -xsimdbg E:ES,CI,FN S:AL T:MG
\end{verbatim}