%%
%% getstart.tex -- Flight Gear documentation: Installation and Getting Started
%% Chapter file
%%
%% Written by Michael Basler % Bernhard Buckel, starting September 1998.
%%
%% Copyright (C) 2002 Michael Basler (pmb@epost.de)
%%                  & Bernhard Buckel (buckel@wmad95.mathematik.uni-wuerzburg.de)
%%
%% This program is free software; you can redistribute it and/or
%% modify it under the terms of the GNU General Public License as
%% published by the Free Software Foundation; either version 2 of the
%% License, or (at your option) any later version.
%%
%% 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
%% General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
%% $Id: missed.tex,v 0.6 2002/09/09 michael
%% (Log is kept at end of this file)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Missed approach: If anything refuses to work\label{missed}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\markboth{\thechapter.\hspace*{1mm} MISSED APPROACH
}{\thesection\hspace*{1mm} ???}

In the following section, we tried to sort some \Index{problems} according to operating system,
but if you encounter a problem, it may be a wise idea to look beyond ''your'' operating system -- just in case. If you are experiencing problems, we would strongly advise you to first check the \Index{FAQ} maintained by Cameron Moore\index{Moore Cameron} at
\medskip

\web{http://www.flightgear.org/Docs/FlightGear-FAQ.html}.
\medskip


Moreover, the source code contains a directory \texttt{docs-mini} containing numerous
ideas on and solutions to special problems. This is also a good place to go for further reading.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{FlightGear Problem Reports}\index{problem report}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The best place to look for help is generally the \Index{mailing lists}, specifically the  \textbf{[Flightgear-User]} mailing list. If you happen to be running a CVS version of \FlightGear{}, you may want to subscribe to the \textbf{[Flightgear-Devel]} list. Instructions for subscription can be
found at
 \medskip

\web{http://www.flightgear.org/mail.html}.
 \medskip

\noindent
It's often the case that someone has already dealt with the issue you're dealing with, so it may be worth your time to search the mailing list archives at
 \medskip

http://www.mail-archive.com/flightgear-users\%40flightgear.org/

http://www.mail-archive.com/flightgear-devel\%40flightgear.org/.
 \medskip

\noindent
There are numerous developers and users reading the lists, so questions are generally answered. However, messages of the type

\textit{FlightGear does not compile on my system. What shall I do?}

 \noindent
are hard to answer without any further detail given, aren't they? Here are some things to consider including in your message when you report a problem:
 \medskip

\begin{itemize}
\item \textbf{Operating system:} (Linux Redhat 7.0\ldots/Windows 98SE\ldots)

\item \textbf{Computer:} (Pentium III, 1GHz\ldots)

\item \textbf{Graphics board/chip:} (Diamond Viper 770/NVIDIA RIVA TNT2\ldots)

\item \textbf{Compiler/version:} (Cygnus version 1.0\ldots)

\item \textbf{Versions of relevant libraries:} (PLIB 1.2.0, Mesa 3.0\ldots)

\item \textbf{Type of problem:} (Linker dies with message\ldots)

\item \textbf{Steps to recreate the problem:} Start at KSFO, turn off brakes \ldots

\end{itemize}

For getting a trace of the output which \FlightGear{} produces, then following command may come in handy (may need to be modified on some OSs or may not work on others at all, though):
\medskip

\texttt{\%FG$\underline{~~}$ROOT/BIN/fgfs >log.txt 2>\&1}
\medskip

\textbf{One final remark:} Please avoid posting binaries to these lists! List subscribers are widely distributed, and some users have low bandwidth and/or metered connections. Large messages may be rejected by the mailing list administrator. Thanks.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{General problems}\index{problems!general}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{itemize}

\item{\FlightGear{} runs SOOO slow.}\\
 If \FlightGear{} says it's running with something like 1\,fps
 (frame per second) or below you typically don't have working hardware
 \Index{OpenGL} support. There may be several reasons for this. First,
 there may be no OpenGL hardware drivers available for older
 cards. In this case it is highly recommended to get a new board.

 Second, check if your drivers are properly installed. Several
 cards need additional OpenGL support drivers besides the
 ''native'' windows ones. For more detail check Appendix
 \ref{opengl}.

\item{Either \texttt{configure} or \texttt{make} dies with not found \PLIB{} headers or
 libraries.}\\
  Make sure you have the latest version of \PLIB{} ($>$ version 1.2) compiled and installed.
  Its headers like \texttt{pu.h} have to be under \texttt{/usr/include/plib} and its libraries, like \texttt{libplibpu.a} should be under \texttt{/lib}. Double check there are no stray \PLIB{} headers/libraries sitting elsewhere!

  Besides check careful the error messages of \texttt{configure}. In several cases it
  says what is missing.
 \end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Potential problems under Linux}\index{problems!Linux}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Since we don't have access to all possible flavors of Linux distributions, here are some
thoughts on possible causes of problems. (This Section includes contributions by Kai
Troester.)\index{Troester, Kai}

\begin{itemize}

\item{Wrong library versions}\\
  This is a rather common cause of grief especially when you prefer to
  install the libraries needed by \FlightGear{} by hand. Be sure that
  especially the Mesa library contains support for the
  \Index{3DFX} board and that \Index{GLIDE} libraries are installed and can be
  found. If a \texttt{ldd `which fgfs`} complains about missing
  libraries you are in trouble.

  You should also be sure to \em{always} keep the \em{latest} version
  of \PLIB{} on your system. Lots of people have
  failed miserably to compile \FlightGear{} just because of an outdated
  plib.


\item{Missing \Index{permissions}}\\
 In case you are using \Index{XFree86} before release 4.0 the \FlightGear{} binary may need to be  setuid root in order to be capable of  accessing some accelerator boards (or a special kernel module as described earlier in this document) based on 3DFX chips.
  So you can either issue a

  \texttt{chown root.root /usr/local/bin/fgfs ;}\\
  \texttt{chmod 4755 /usr/local/bin/fgfs}

  to give the \FlightGear{} binary the proper rights or install
  the 3DFX module. The latter is the ''clean''
  solution and strongly recommended!


\item{Non-default install options}\\
  \FlightGear{} will display a lot of diagnostics while starting up.
  If it complains about bad looking or missing files, check that you
  installed them in the way they are supposed to be installed (i.e. with the latest
  version and in the proper location). The canonical location \FlightGear{}
  wants its data files under \texttt{/usr/local/lib}.
   Be sure to grab the latest versions of everything that might be needed!

\item{Compile problems in general}\\
  Make sure you have the latest (official) version of gcc. Old versions of
  gcc are a frequent source of trouble! On the other hand, some versions
  of the RedHat 7.0 reportedly have certain problems compiling \FlightGear{} as they include
  a preliminary version of GCC.

\item{Problems with linking}\\
There may be several reasons; however in case you get a message like

\texttt{libmk4.so.0}: cannot open shared object file

the reason is a missing library package called Metakit. This is provided with \SimGear{} in packed form. On its installation, see Sec. \ref{metakeitinstall}.
 \end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Potential problems under Windows}\index{problems!Windows}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{itemize}
\item{The executable refuses to run.}\\
 You may have tried to start the executable directly either by
 double-clicking \texttt{fgfs.exe} in Windows Explorer or by invoking it
 within a MS-DOS shell. Double-clicking via Explorer does never work
 (unless you set the environment variable \texttt{FG\_ROOT}
 in \texttt{autoexec.bat} or otherwise). Rather double-click \texttt{runfgfs.bat}.
  For more details, check Chapter \ref{takeoff}.

 Another cause of grief might be that you did not download the
 most recent versions of the base package files required by \FlightGear{}$\!$, or
 you did not download any of them at all. Have a close look
 at this, as the scenery/texture format is still under development and may
 change frequently.  For more details, check Chapter \ref{prefligh}.

 Next, if you run into trouble at runtime, do not use windows utilities for unpacking the
 \texttt{.tar.gz}. If you did, try it in the Cygnus shell with \texttt{tar xvfz}
 instead.

\item{\FlightGear{} ignores the command line parameters.}\\
 There is a problem with passing command line options containing a
 ''='' to windows batch files. Instead, include the options into
 \texttt{runfgfs.bat}.

\item{I am unable to build \FlightGear{} under \Index{MSVC}/\Index{MS DevStudio}.}\\
 By default, \FlightGear{} is build with GNU GCC. The Win32 port of GNU GCC is known as
 \Index{Cygwin}. For hints on Makefiles
 required for MSVC for MSC DevStudio have a look into
  \medskip

 \web{ftp://www.flightgear.org/pub/flightgear/Source/}.
  \medskip

 \noindent
In principle, it should be possible to compile \FlightGear{} with the project files provided with the source code.

\item{Compilation of \FlightGear{} dies.}\\
 There may be several reasons for this, including true bugs. However, before trying to do
 anything else or report a problem, make sure you have the latest version of the
 \Cygwin{} compiler, as described in Section \ref{building}. In case of doubt, start
 \texttt{setup.exe} anew and download and install the most recent versions of bundles
 as they possibly may have changed.
\end{itemize}


%% revision 0.10  1998/10/01  bernhard
%% added win stuff michael
%% final proofreading for release
%% revision 0.11  1998/11/01  michael
%% Remark on mini-OpenGL drivers, new general Section
%% Access violation error under win32 added
%% Command line problem in win32 added
%% revision 0.12  1999/03/07  bernhard
%% Remark on EGCS compiler
%% revision 0.12  1999/03/07  michael
%% Added Contribution by Kai Troester
%% Reworked Win32 Stuff
%% revision 0.20  1999/06/04  michael
%% added hint to FAQ, gfc problem
%% revision 0.22 XXX
%% added hint on install.exe with Cygnus
%% revision 0.3 2000/04/20 michael
%% hint on revised PLIB paths, removed outdated stuff
%% revision 0.3 2000/04/20 michael
%% Deleted some outdated stuff
%% Added Old PLIB problem
%% revision 0.31 2000/05/01 michael
%% Reworked/Added Achnowledgements
%% Added hint on gunzip/tar from Marc Anderson
%% revision 0.4 2001/05/12 michael
%% added some points (RedHat...), deleted some outdated ones
%% complete rewrite and check still to be done ... sometime
%% revision 0.5 2002/01/01 michael
%% removed several outdated issues
%% Added problem linking Metakit