/*
 * Copyright (c) 2012-2014:  G-CSC, Goethe University Frankfurt
 * Author: Martin Rupp
 * 
 * This file is part of UG4.
 * 
 * UG4 is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License version 3 (as published by the
 * Free Software Foundation) with the following additional attribution
 * requirements (according to LGPL/GPL v3 §7):
 * 
 * (1) The following notice must be displayed in the Appropriate Legal Notices
 * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (2) The following notice must be displayed at a prominent place in the
 * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (3) The following bibliography is recommended for citation and must be
 * preserved in all covered files:
 * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
 *   parallel geometric multigrid solver on hierarchically distributed grids.
 *   Computing and visualization in science 16, 4 (2013), 151-164"
 * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
 *   flexible software system for simulating pde based models on high performance
 *   computers. Computing and visualization in science 16, 4 (2013), 165-179"
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 */

/** \page pageTroubleshooting Troubleshooting

[TOC]

This file is intended for troubleshooting.
Please provide information about as much errors as possible.
It might be a very stupid error for you, but there's a high chance someone else 
has the same problem and spends hours on solving it.

<hr>
\section troubleshooting_compiler_errors Known Internal Compiler Errors
<hr>
There are some compiler versions which fail to compile ug4 because of bugs in the compilers:
\subsection secLLVM3_3 llvm/clang 3.3
Internal Compiler Bug: Impossible TemplateArgument UNREACHABLE executed at TypeLoc.cpp:335. 

Solution: llvm/clang 3.4.

\subsection secCMake_GCC412 GCC 4.1.2
<em>GCC v. 4.1.2</em>, like it is default on \em cekon, is not able to compile 
a debug build (i.e. configured with <tt>cmake -DDEBUG=ON ..</tt>) because of an 
internal compiler error (<tt>internal compiler error: in force_type_die, at 
dwarf2out.c...</tt>). The error seems also to be there on gcc 4.3.
In this case it is possible to configure \ug4 by specifying <em>GCC v. 
4.4.4</em>, which is also installed on \em cekon as an alternative compiler:
\verbatim
cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++44 ..
\endverbatim

Alternatively one can instruct the (default) compiler to produce the debug 
infos in <a href="http://gcc.gnu.org/ml/gcc/2001-04/msg01028.html">another 
format</a>. 
To do so, call \em CMake with
\verbatim
cmake -DDEBUG_FORMAT=-gstabs ..
\endverbatim

This sets \em STABS as format of debug infos.

If you need to choose another compiler, please consider writing your own 
toolchain file, so others can benefit from your knowledge. 

<hr>
\section troubleshootingCompiling Problems with Compiling
<hr>

\subsection troubleshooting_cant_compile_or_link Can not compile or link
<dl>
	<dt>Symptoms</dt>
	<dd>
		- You can't compile/link your program
		- "dyld: lazy symbol binding failed: Symbol not found" (link error)
		- "duplicate symbol" (link error)
	</dd>
	<dt>Possible Cause</dt>
	<dd>
		- Part of \ug4 compiled with one cmake setting, other part compiled with another.
		- OR Wrong settings in CMake, missing libraries, wrong library paths.
		- If the problem persists, copy/paste all your console output and email it to someone.
	</dd>
	<dt>Solution</dt>
	<dd>
		If you can't compile your program, it is sometimes a good idea to recompile or relink parts of \ug4.
		Try the following:
		- use <tt>ugrelib</tt> (that is: delete ug4/bin/ugshell, ug4/lib/*, ug4/bin/plugins/*), recompile.
		- If that doesn't work, also do a `make clean` and a make.
		- If that doesn't work, also reset your build configuration 
		  by deleting your build directory (e.g. `ug4/debug`).
		  You will have to redo a `cmake ..` and reenter all your \em CMake parameters 
		  like `-DDIM` and plugins.
		- If that doesn't help, it may be a problem with external libraries.
		  Read the error line. Memorize the error message. Think about it. Does it complain about something with MPI or any library you know?
		  If there are filepaths or filenames, are they correct? Where do they point to?
	</dd>
</dl>

\subsection troubleshooting_ugshell_old_cmake can't set up with cmake
<dl>
	<dt>Symptoms</dt>
	<dd>\em cmake prints "parse error in cache file" and "offending entry", later won't compile or link
	<dt>Possible Causes</dt>
	<dd>
		CMake too old. Minimum version is 2.8.6.
	</dd>
	<dt>Solution</dt>
	<dd>
		Update your cmake version. For this, you can use <tt>uginstall cmake</tt>.
	</dd>
</dl>


\subsection troubleshooting_ugshell_registry_errors ugshell crashes on startup with registry errors
<dl>
	<dt>Symptoms</dt>
	<dd>\em ugshell keeps crashing on startup with registry errors</dd>
	<dt>Possible Causes</dt>
	<dd>
		A plugin might got renamed or deleted and \em CMake is not able to detect previous 
		and not deprecated library files in `ug4/bin/plugins`.
	</dd>
	<dt>Solution</dt>
	<dd>
		Delete the content of `ug4/bin/plugins`, reconfigure (i.e. run \em CMake in your
		build directory) and recompile \ug4.
	</dd>
</dl>

\subsection troubleshooting_compile_plugin_diff_config Compiling plugin with different configuration Plugin initialization shows error
<dl>
	<dt>Symptoms</dt>
	<dd>
		\verbatim
*** glibc detected *** gravtree: corrupted double-linked list: 0x000000001aa0fc50 ***
		\endverbatim
	</dd>
	<dt>Cause</dt>
	<dd>Compiling plugin seperately with different configurations</dd>
	<dt>Solution</dt>
	<dd>
		Delete contents `ug4/bin/plugins` of directory.
		Use the `-D[pluginname]` option of cmake.
		Recompile \ug4.
	</dd>
</dl>

<hr>
\section troubleshootingParallel Parallel execution
<hr>

\subsection troubleshooting_multiple_parallel_output Output appears multiple times
<dl>
	<dt>Symptoms</dt>
	<dd>Parallel output appears multiple times even though `-outproc 0` was chosen.</dd>
	<dt>Possible Cause </dt>
	<dd>
		\ug4 was not compiled with `UG_PARALLEL`.
		Try to use `PrintBuildConfiguration()` in LUA/ugshell or enter `cmake ..` in 
		your build dir.
		There you should get `PARALLEL: ON`.
	</dd>
	<dt>Solution</dt>
	<dd>
		Enter `cmake -DPARALLEL=ON ..`.
		If you get errors that MPI could not be found, ask someone.
	</dd>
</dl>



<hr>
\section troubleshootingOther Other
<hr>

\subsection troubleshooting_cant_find_scripts Can't find [ugsubmit/ugrelib/cdug etc.]
<dl>
	<dt>Symptoms</dt>
	<dd>You want to run e.g. ugsubmit, but it says it is not found</dd>
	<dt>Solution</dt>
	<dd>
		All bash script extensions of ug are located in ug4/scripts/shell, go to \ref pageBashTools to learn more.
	</dd>
</dl>
 

\subsection troubleshooting_SVN I have a problem with SVN
See \ref secSVNTroubleshooting.


*/
