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

The \OOMMF\ developers rely on reports from \OOMMF\ users to alert them
to problems\index{reporting~bugs} with the software and its
documentation, and to guide the selection and implementation of new
features.  See the \hyperrefhtml{Credits}{Credits
(Sec.~}{)}{sec:credits} for instructions on how to contact the
\OOMMF\ developers.

The more complete your report, the fewer followup messages will be
required to determine the cause of your problem.  Usually when a problem
arises there is an error message produced by the \OOMMF\ software.  A
stack trace may be offered that reveals more detail about the error.
When reporting an error, it will help the developers diagnose the
problem if users cut and paste into their problem report the error
message and stack trace exactly as reported by \OOMMF\ software.  In
addition, \textbf{PLEASE} include a copy of the output generated by
\cd{tclsh oommf.tcl +platform}\index{platform}; this is important
because it will help \OOMMF\ developers identify problems that are
installation or platform dependent.

Before making a report to the \OOMMF\ developers, please check the
following list of fixes for known problems.  Additional problems
discovered after release will be posted to version specific ``patch''
pages at the
\htmladdnormallink{\OOMMF\ web site.}{http://math.nist.gov/oommf/}
\begin{enumerate}
\item When
\hyperrefhtml{compiling}{compiling
(Sec.~}{)}{sec:install.compile},
there is an error about being unable to open system header files like
\fn{stdlib.h}, \fn{time.h}, \fn{math.h}, or system libraries and related
program startup code.  This usually indicates a bad compiler
installation.  If you running on Windows and building with the the
Microsoft Visual C++ command line compiler, did you remember to run
\fn{vcvars32.bat} to set up the necessary environment variables?  If
you are using the Borland C++ compiler, are the \fn{bcc32.cfg} and
\fn{ilink32.cfg} files properly configured?  In all cases, check
carefully any notes in the chapter
\hyperrefhtml{Advanced Installation}{Advanced Installation
(Sec.~}{)}{sec:install.advanced} pertaining to your compiler.

\item When
\hyperrefhtml{compiling}{compiling
(Sec.~}{)}{sec:install.compile},
there is an error something like:
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
<30654> pimake 1.x.x.x MakeRule panic:
Don't know how to make '/usr/include/tcl.h'
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

This means the header file \fn{tcl.h} is missing from your
\Tcl\ installation.  Other missing header files might be
\fn{tk.h} from the \Tk\ installation, or \fn{Xlib.h} from an
X Window System installation on \Unix.  In order to compile \OOMMF, you
need to have the development versions of \Tcl, \Tk, and (if needed) X
installed.  The way to achieve that is platform-dependent.  On \Windows\
you do not need an X installation, but when you install \Tcl/\Tk\ be
sure to request a ``full'' installation, or one with ``header and
library files''.  On Linux, be sure to install developer packages
%(for example, the XFree86-devel RPM)
as well as user packages.  Other
platforms are unlikely to have this problem.  In the case of
\fn{Xlib.h}, it is also possible that the \fn{tkConfig.sh} file has an
incorrect entry for \cd{TK\_XINCLUDES}.  A workaround for this is to
add the following line to your
\fn{oommf/config/platforms/}\textit{platform} file:
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
$config SetValue TK_XINCLUDES "-I/usr/X11R6/include"
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
Adjust the include directory as appropriate for your system.

\item When
\hyperrefhtml{compiling}{compiling
(Sec.~}{)}{sec:install.compile}, there is an error
indicating that exceptions are not supported.

Parts of \OOMMF\ are written in C++, and exceptions have been part
of the C++ language for many years.  If your compiler does not
support them, it is time to upgrade to one that does.  \OOMMF\ 1.2
requires a compiler capable of compiling source code which uses
C++ exceptions.

\item \hyperrefhtml{Compiling}{Compiling
(Sec.~}{)}{sec:install.compile} with gcc produces syntax errors
on lines involving \cd{auto\_ptr} templates.

This is known to occur on RedHat 5.2 systems.  The \cd{auto\_ptr}
definition in the system STL header file \cd{memory} (located on RedHat
5.2 systems in the directory \cd{/usr/include/g++}) is disabled by two
\cd{\lb if} statements.  One solution is to edit this file to turn off
the \cd{\lb if} checks.  If you do this, you will also have to fix two
small typos in the definition of the \cd{release()} member function.

\item When \hyperrefhtml{compiling}{compiling
(Sec.~}{)}{sec:install.compile} there is an error message arising from
system include directories being too early in the include search path.
Try adding the offending directories to the
\cd{program\_compiler\_c++\_system\_include\_path} property in the
platform file, e.g.,
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
$config SetValue program_compiler_c++_system_include_path \
      [list /usr/include /usr/local/include]
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

\item On Solaris, gcc reports many errors like 
\begin{quote}
\cd{ANSI C++ forbids declaration `XSetTransientForHint' with no type}
\end{quote}

On many Solaris systems, the header files for the X Window System
are not ANSI compliant, and gcc complains about that.  To work around
this problem, edit the file \fn{oommf/config/platforms/solaris.tcl} to add the
option \cd{-fpermissive} to the gcc command line.

\item On Windows, when first starting \cd{oommf.tcl}, there is an error:
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Error launching mmLaunch version 1.x.x.x:
	couldn't execute "...\omfsh.exe": invalid argument
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

This cryptic message most likely means that the pre-compiled
\OOMMF\ binaries which were downloaded are for a different version
of \Tcl/\Tk\ than is installed on your system.  Download \OOMMF\ again,
taking care this time to retrieve the binaries that match the
release of \Tcl/\Tk\ you have installed.

\item When first starting \cd{oommf.tcl}, there is an error:
\begin{quote}
\raggedright
\cd{Error in startup script: Neither Omf\_export nor Omf\_export\_list set in}
\end{quote}

The file \fn{oommf/pkg/net/omfExport.tcl} may be missing from your 
\OOMMF\ installation.  If necessary, download and install \OOMMF\ again.

\item When launching \cd{oommf.tcl} on \Unix\ systems, there is an error
of the form: 
\begin{quote}
\raggedright
\cd{error while loading shared library: libtk8.4.so: cannot
open shared object file: No such file or directory}
\end{quote}

This typically happens because the libtk\lb.\lb.so (and/or
libtcl\lb.\lb.so) files are installed in a directory not included in the
ld.so runtime linker/loader search path. One way to fix this is to add
that directory (say /usr/local/lib) to the \cd{LD\_LIBRARY\_PATH}
environment variable. For example, include
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib 
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
in your \cd{\~{}/.bashrc} file (bash shell users) or
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/usr/local/lib 
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
in your \cd{\~{}/.cshrc} file (csh or tcsh shell users).  Another option
is to modify the ld.so cache; see the ld.so and ldconfig man pages for
details.

%\item \index{sockets}When launching multiple \OOMMF\ applications on
%  \Windows~9X, there is an error:
%\begin{quote}
%\raggedright
%\cd{couldn't open socket: no buffer space available}
%\end{quote}
%\OOMMF\ uses network sockets for communications between its various
%components.  On \Windows~9X, the socket resources are limited, and
%most \OOMMF\ applications use several sockets.  The only workaround is
%to close unneeded \OOMMF\ applications, and any other applications
%that may be using network resources.  The system command line utility
%\cd{netstat} can be used to monitor network communications.  This
%problem does not arise on \Windows~NT or \Unix\ systems.

\item When starting \OOMMF\ in the Cygwin environment on \Windows, the
mmLaunch window appears briefly, then disappears without any error
messages.

Some old versions of \Tcl/\Tk\ included with the Cygwin environment
(i.e., \cd{/usr/bin/tclsh}) had bugs in the socket code
that caused \OOMMF\ to crash in this manner.  This problem is fixed in
current Cygwin releases.

\item I ran out of memory!

Are you using \hyperrefhtml{\app{mmGraph}}{\app{mmGraph}
(Sec.~}{)}{sec:mmgraph}\index{application!mmGraph} to monitor a
long-running simulation?  All data sent to \app{mmGraph} is kept in
memory by default.  See the \app{mmGraph} documentation for information
on how to manage this problem.

\end{enumerate}



