===============================================================================
Building and installing Cumulus under X11 and Qt4.8.x for Linux/Unix

Last update: 2012-01-11 by Axel Pauli

SVN info: $Id: INSTALL 4785 2012-01-11 14:16:06Z axel $
===============================================================================

These are the instructions to build and install Cumulus from source under
Linux/Unix. The basic assumption is, that you will do it as normal user and
not as root!

Step 1)

You will need to set up a build environment for Cumulus under X11. The
following components are mandatory:

  a) The g++ tool, GNUs C++ compiler
  b) The Qt tools qmake, moc and lrelease
  c) The Qt libraries libQtCore, libQtGui, libQtNetwork, libQtXml
  d) The Qt header files
  e) The Bluetooth header files and the libbluetooth library
  
At least a Qt Release 4.7.0 or higher has to be used.

The different Linux distributions do provide normally installable packages for
that. For XUbuntu 11.10 you have to execute the following command to get them:

  sudo apt-get install g++ subversion
  sudo apt-get install qt4-qmake qt4-dev-tools libqtcore4 libqtgui4 \
                       libqt4-dev libqt4-network libqt4-xml
  sudo apt-get install libbluetooth-dev bluez-utils bluez

You can build too Qt from the sources but that is not recommend, if you not
familiar with that. 

If all Qt stuff is already available you can continue with step 2)

To build your own Qt from scratch download a X11/Qt release from
ftp.qt.nokia.com/qt/source. I recommend the release:

ftp://ftp.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.8.0.tar.gz

I did the development with this release. For Cumulus you need the standard
Qt4 libraries libQtCore, libQtGui, libQtNetwork and libQtXml. If you want to
debug Cumulus together with Qt it is recommend to activate the debug option
during run of the configure script.

Copy the Qt tar ball in a local directory of your Linux desktop and extract it
with:
  
  tar zxf qt-everywhere-opensource-src-4.8.0.tar.gz

Call the configure script in the root directory of your Qt source tree with the
following options:
              
  ./configure -prefix /opt/qt4.8.0 -opensource -no-largefile -no-qt3support\
              -no-multimedia -no-audio-backend -no-phonon\
              -no-phonon-backend -no-webkit -no-javascript-jit -no-script\
              -no-scripttools -no-declarative -no-declarative-debug\
              -nomake examples -nomake demos -no-nis -no-cups -no-opengl\
              -silent -graphicssystem raster              
              
Note, that all options must be passed on one line. If you want to set another
prefix option please do it now. The installation is done under this path and
under /opt/... you need later on root rights. To build Qt with debugging on add
the option -debug to the others.
            
If configure has finished successfully, call as next:

  make

That can take a while (1-3 hours). If make has finished successfully call:

  su -c 'make install' or sudo make install

For executing this command you need root rights to install the Qt installation
under /opt/... Please enter the root password when you ask for it.

Now you should have installed a Qt installation under the directory of your
-prefix option.

To use your own Qt version, you have to add the
<QT_INSTALLDIR>/bin component at the first position of your PATH variable.

e.g. BASH example

  PATH=/opt/qt4.8.0/bin:$PATH
  export PATH
	
  in the assumption, that <QT_INSTALLDIR> is '/opt/qt4.8.0'.

The PATH variable can be displayed by calling 'echo $PATH' on a shell
command line.

Step 2)

Check if you can call 'g++ --version' from a shell command line. You should
see some output like this:

  g++ (Ubuntu/Linaro 4.6.1-9ubuntu3) 4.6.1
  
Check if you can call 'qmake -v' from a shell command line. You should
see some output like this:

  QMake version 2.01a
  Using Qt version 4.8.0 in /opt/qt4.8.0/lib
   
Check if you can call 'moc -v' from a shell command line. You should
see some output like this:

  Qt Meta Object Compiler version 63 (Qt 4.8.0)
   
If both checks are successfully Qt is right installed. If a call fails or you
see a version less than 4.7.0 check the PATH variable for containing the right
Qt bin directory at the first position (see above).

Step 3)

Download the Cumulus sources from the subversion archive or as snapshot tar ball.

a) Get it from subversion:

To checkout the source tree from the subversion archive you need an installed
subversion client on your Linux desktop. If the command 'svn --version' fails you
have not installed subversion. Alternatively you can download a snapshot tar ball.
See below how to do this.

Checkout a Cumulus snapshot file tree in a local directory of your Linux desktop
from the subversion archive with:

  1) svn co https://svn.kflog.org/svn/repos/cumulus/qt4/trunk
  2) svn export https://svn.kflog.org/svn/repos/cumulus/qt4/trunk

Variant 2) is free from any svn overhead like .svn directories.

To checkout a certain release you have to use a url which starts with:

  https://svn.kflog.org/svn/repos/cumulus/qt4/tags/
  
followed by a release tag e.g. Release_2.12.0. You can browse through the
Cumulus subversion archive with your Internet browser to see the release tags.
Type in the following url:

  https://svn.kflog.org/svn/repos/cumulus
  
Maybe your browser will aks you to enable an exception rule for the KFLog
certificate, it is not officially signed. You have to commit the question to
get access to the archive. Under the path qt4/trunk you can see the latest
checked in sources. Releases are to find under the path qt4/tag.

b) Get it as snapshot tar ball:

You can also download a snapshot tar ball by using this link:

  http://www.kflog.org/fileadmin/user_upload/cumulus_snapshots/CumulusQt4-snapshot.tbz
  
Copy the tar ball in a local directory of your Linux desktop and extract it with:
  
  tar jxf CumulusQt4-snapshot.tbz

Step 4)

Go into the trunk directory of your subversion copy or in the root directory of
the extracted tar ball. To build the Cumulus application issue the following
command:

  make -f Makefile.X11
	
  The following make targets are available:
	
  all      Builds all parts of Cumulus
  clean    Cleans the build area and removes all generated objects.
           Use it after done modifications of qmake project files.
  install  Installs Cumulus under $(INSTALL_ROOT), normally /opt/cumulus
  
If you want to build a smaller release you can switch off the features
Flarm, Internet download, Bluetooth or Welt2000 thread in the related qmake
project file. Go into the subdirectory cumulus and edit the file cumulusX11.pro.
Comment out one or more of the lines:

CONFIG += flarm
CONFIG += internet
CONFIG += bluetooth
CONFIG += welt2000thread

with a hash mark. That disables the related feature. The bluetooth feature must
be disabled too in the project file gpsClient/gpsClientX11.pro.

Step 5)

The installation structure of Cumulus is oriented on the Filesystem Hierarchy
Standard of Unix (www.pathname.com/fhs). The default installation directory of
the Cumulus application is therefore /opt/cumulus further called INSTALL_ROOT.

To install Cumulus issue the following command:

  su -c 'make -f Makefile.X11 install'
  
  or under Ubuntu
  
  sudo make -f Makefile.X11 install

'su -c' or sudo are necessary for the installation under /opt/cumulus. You need
root rights to do that. Please enter the root password when you ask for it.
If you would prefer another installation place, you can change the installation
directory during call of 'make install' in the following way:

  make -f Makefile.X11 INSTALL_ROOT=<my-install-path> install

Step 6)

The needed map data (airfields, airspaces and landscape) have to be installed
under the following directory structure:

                   +-/airfields/ (Only Welt2000 data file is supported)
$HOME/Cumulus/maps/+-/airspaces/ (Only OpenAir file format is supported)
                   +-/landscape/ (Use map data from KFLog's map room)

Note, that Cumulus can handle airspace data only in openair format.
Airfield and outlanding data are taken from the Welt2000 data file.
The former support of KFLog airspace and airfield files has been removed.

See in Cumulus online help under

http://www.kflog.org/fileadmin/user_upload/cumulus_help/en/cumulus-maps.html

for more information.

The landscape files are to find in the KFLog Map room. 

http://www.kflog.org/maproom/ground-and-terrain-data

Welt2000 and landscape data files are downloaded automatically by Cumulus
after the startup, if you permit that.

Step 7)

To start Cumulus issue the command:

  INSTALL_PATH/bin/cumulus

Personal stuff is stored under $HOME/Cumulus. There you can find the task file
'tasks.tsk', the waypoint file 'cumulus.kwp' and the IGC log files.

The Cumulus configuration file is stored under $HOME/.config/Cumulus.conf.

To get more information about the Cumulus usage look in the online help of your
running Cumulus or under this link:

http://www.kflog.org/fileadmin/user_upload/cumulus_help/en/cumulus.html

Step 8)

Usage of NMEA Simulator

Under INSTALL_ROOT/bin you can find a NMEA simulator with name 'nmeaSimu'. You
can use it for generation of NMEA data. Call it without any arguments and you
will get a help usage displayed. The simulator writes its output in a named
pipe. Select in Cumulus as GPS device /tmp/nmeasim and Cumulus will read
the data from the simulator.

===============================================================================

Cumulus package for Maemo

Cumulus packages for the Nokia Internet Tablets N8x0 and N900 can only be built
in a scratchbox environment called Maemo SDK. How to setup it look here:

  http://maemo.org/development/

The makefiles Makefile.Maemo4 or Makefile.Maemo5 will do the package build.

Issue the following make comand for Maemo4 (N8x0)

  make -f Makefile.Maemo4 all dpkg dpkg_lang

Issue the following make comand for Maemo5 (N900)

  make -f Makefile.Maemo5 all dpkg dpkg_lang

in the right Maemo SDK envrironment to get a dpkg package of Cumulus. Maemo 4
and Maemo 5 uses different SDK installations. The make target dpkg_lang provides
a German language package for the GUI. The built debian packages are to find in
the subdirectories dpkg/n810, dpkg/n900 and dpkg/Languages.

Hints, improvements or help are always welcome. Please contact the maintainer of
Cumulus, Axel Pauli, via email axel@kflog.org or use the mailing lists of KFLog
to find under www.kflog.org/mailman/listinfo.

Have fun with Cumulus ...

===============================================================================
License of Cumulus
===============================================================================

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 3 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
(www.gnu.org/copyleft/gpl.html) for more details.
