% -*- latex -*-
%
% Copyright (c) 2001-2003 The Trustees of Indiana University.  
%                         All rights reserved.
% Copyright (c) 1998-2001 University of Notre Dame. 
%                         All rights reserved.
% Copyright (c) 1994-1998 The Ohio State University.  
%                         All rights reserved.
% 
% This file is part of the LAM/MPI software package.  For license
% information, see the LICENSE file in the top level directory of the
% LAM/MPI source distribution.
%
% $Id: trouble.tex,v 1.9 2003/06/24 16:54:43 jsquyres Exp $
%

\chapter{Troubleshooting}
\label{sec:trouble}

In general, LAM builds correctly on a wide variety of platforms with
no problems.  Due to the wide variety of platforms using LAM, problems
do occur from time to time.  The primary resource for assistance is
the LAM web page and the LAM mailing list.  If LAM built and installed
without error, please see the LAM/MPI User's Guide for additional
troubleshooting information.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{What To Do When Something Goes Wrong}
\label{sec:trouble:report}

It is highly recommended that you execute the following steps {\em in
order}.  Many people have similar problems with configuration and
initial setup of LAM, and most common problems have already been
answered in one way or another.

\begin{enumerate}
\item Check the LAM FAQ:
 
  \vspace{11pt}

  \centerline{\url{http://www.lam-mpi.org/faq/}}
  
\item Check the mailing list archives.  Use the ``search'' features to
  check old posts and see if others have asked the same question and
  had it answered:
  
  \vspace{11pt}

  \centerline{\url{http://www.lam-mpi.org/MailArchives/lam/}}
  
\item If you do not find a solution to your problem in the above
  resources, and your problem specifically has to do with {\em
    building} LAM, send the following information to the LAM mailing
  list (See Section~\ref{sec:trouble:lists} -- please compress the
  files before sending them!):
  
  \begin{itemize}
  \item All output (both compilation output and run time output,
    including all error messages)
    
  \item Output from when you ran \cmd{./configure} to configure LAM
    ({\bf please compress!})
    
  \item The \file{config.log} file from the top-level LAM directory
    ({\bf please compress!})
    
  \item Output from when you ran \cmd{make} to build LAM ({\bf please
      compress!})
    
  \item Output from when you ran \cmd{make install} to install LAM
    ({\bf please compress!})
  \end{itemize}

  To capture the output of the configure and make steps you can use
  the script command or the following technique if using a csh style
  shell:

\lstset{style=lam-cmdline}
\begin{lstlisting}
shell% ./configure {options} |& tee config.LOG
shell% make all              |& tee make.LOG
shell% make install          |& tee make-install.LOG
\end{lstlisting}

or if using a Bourne style shell:

\lstset{style=lam-cmdline}
\begin{lstlisting}
shell$ ./configure {options} 2>&1 | tee config.LOG
shell$ make all 2>&1              | tee make.LOG
shell$ make install 2>&1          | tee make-install.LOG
\end{lstlisting}
% stoopid emacs mode: $

To compress all the files listed above, we recommend using the
\cmd{tar} and \cmd{gzip} commands. For example (using a
\cmd{csh}-style shell):

\lstset{style=lam-cmdline}
\begin{lstlisting}
shell% mkdir $HOME/lam-output
shell% cd /directory/for/lam-7.0 
shell% ./configure |& tee $HOME/lam-output/configure.LOG
# ...lots of output...
shell% cp config.log share/include/lam_config.h $HOME/lam-output
shell% make all |& tee $HOME/lam-output/make.LOG
# ...lots of output...
shell% make install |& tee $HOME/lam-output/make-install.LOG
# ...lots of output...
shell% cd $HOME
shell% tar cvf lam-output.tar lam-output
# ...lots of output...
shell% gzip lam-output.tar
\end{lstlisting}

Then send the resulting \file{lam-output.tar.gz} file to the LAM
mailing list.

If you are using an \cmd{sh}-style shell:

\lstset{style=lam-cmdline}
\begin{lstlisting}
shell$ mkdir $HOME/lam-output
shell$ cd /directory/for/lam-7.0 
shell$ ./configure 2>&1 | tee $HOME/lam-output/configure.LOG
# ...lots of output...
shell$ cp config.log share/include/lam_config.h $HOME/lam-output
shell$ make all 2>&1 | tee $HOME/lam-output/make.LOG
# ...lots of output...
shell$ make install 2>&1 | tee $HOME/lam-output/make-install.LOG
# ...lots of output...
shell$ cd $HOME
shell$ tar cvf lam-output.tar lam-output
# ...lots of output...
shell$ gzip lam-output.tar
\end{lstlisting}
% stupid emacs mode: $

Then send the resulting \file{lam-output.tar.gz} file to the LAM
mailing list.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{The LAM/MPI Mailing Lists}
\label{sec:trouble:lists}

There are two mailing lists: one for LAM/MPI announcements, and
another for questions and user discussion of LAM/MPI.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Announcements}
  
This is a low-volume list that is used to announce new version of
LAM/MPI, important patches, etc.  To subscribe to the LAM announcement
list, visit its list information page (you can also use that page to
unsubscribe or change your subscription options):

\vspace{11pt}

\centerline{\url{http://www.lam-mpi.org/mailman/listinfo.cgi/lam-announce}}

\vspace{11pt}

\noindent {\bf NOTE: Users cannot post to this list; all such posts
  are automatically rejected -- only the LAM Team can post to this
  list.}
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{General Discussion / User Questions}

{\bf BEFORE YOU POST TO THIS LIST:} {\em Please} check all the other
resources listed in this chapter first.  Search the mailing list to
see if anyone else had a similar problem before you did.  Re-read the
error message that LAM displayed to you (LAM can sometimes give {\em
  incredibly} detailed error messages that tell you {\em exactly} how
to fix the problem).  This, unfortunately, does not stop some users
from cut-n-pasting the entire error message, verbatim (including the
solution to their problem) into a mail message, sending it to the
list, and asking ``How do I fix this problem?''  So please: think (and
read) before you post.\footnote{Our deep appologies if some of the
  information in this section appears to be repetitive and
  condescending.  Believe us when we say that we have tried all other
  approaches -- some users simply either do not read the information
  provided, or only read the e-mail address to send ``help!'' e-mails
  to.  It is our hope that big, bold print will catch some people's
  eyes and enable them to help themselves rather than having to wait
  for their post to distribute around the world and then further wait
  for someone to reply telling them that the solution to their problem
  was already printed on their screen.  Thanks for your time in
  reading all of this!}

\vspace{11pt}
  
This list is used for general questions and discussion of LAM/MPI.
User can post questions, comments, etc. to this list.  {\bf Due to
  recent increases in spam, only subscribers are allowed to post to
  the list}.  If you are not subscribed to the list, your posts will
be discarded.

To subscribe or unsubscribe from the list, visit the list information
page:

\vspace{11pt}
\centerline{\url{http://www.lam-mpi.org/mailman/listinfo.cgi/lam}}
\vspace{11pt}
  
After you have subscribed (and received a confirmation e-mail), you
can send mail to the list at the following address:
  
\vspace{11pt}
\centerline{{\bf You must be subscribed in order to post to the list}}
\centerline{\url{lam@lam-mpi.org}}
\centerline{{\bf You must be subscribed in order to post to the list}}
\vspace{11pt}
  
Be sure to include the following information in your e-mail:

\begin{itemize}
\item The \file{config.log} file from the top-level LAM directory, if
  available ({\bf please compress!}).
  
\item The output of ``\icmd{laminfo}\ \ \cmdarg{-all}''.

\item A {\em detailed} description of what is failing.  The more
  details that you provide, the better.  E-mails saying ``My
  application doesn't work!'' will inevitably be answered with
  requests for more information about {\em exactly what doesn't work};
  so please include as much detailed information in your initial
  e-mail as possible.
\end{itemize}
  
{\bf NOTE:} People tend to only reply to the list; if you subscribe,
post, and then unsubscribe from the list, you will likely miss
replies.
  
Also please be aware that \url{lam@lam-mpi.org} is a list that goes to
several hundred people around the world -- it is not uncommon to move
a high-volume exchange off the list, and only post the final
resolution of the problem/bug fix to the list.  This prevents
exchanges like ``Did you try X?'', ``Yes, I tried X, and it did not
work.'', ``Did you try Y?'', etc. from cluttering up peoples' inboxes.

