Howto Building QMapShack on OS-X
********************************

This document describes how to build QMapShack on OS-X.
All commands listed in this how to are executed in a terminal. Bash version 3 and
above must be installed to execute the scripts.

Additional Software & Installation
**********************************
To be able to build QMapShack there are several software packages and libraries 
required:
- proj4 library (version 4.9.x)
- gdal library (version 2.1.x)
- qt5 framework (version 5.5.x)
- routino library (version 3.1.x)
- quazip library (version 0.7.x)
- qmapshack
- cmake (version 3.x and above)
- svn command line tool (for routino)
- mercurial (hg) command line tool

The best way is to install most of the required packages is by using brew.
Download the brew package manager if you not already have:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After istalling brew use it to install most of the required packages:
brew install proj4
brew install gdal  (unfortunately not the newest version is prvided with brew)
brew install cmake
brew install qt5 --with-d-bus, --with-mysql
brew install svn
brew install hg

The qt5 package needs some patience if you have selected the options "--with-d-bus" 
and "--with-mysql".
But you will need this to successfully build QMapShack. You may also considering 
to install the qt5 additions "--with-docs --with-examples --with-developer"


The routino library source must be downloaded from the SVN repository
"http://routino.org/svn/trunk/" built manually.
To checkout routino create a new directory where the source should be stored,
cd into the directory and checkout routino with the command:
svn checkout http://routino.org/svn/trunk/

To make the build easier, there is the bash script "build-routino.sh" in the same 
directory as this how to. To run the script, you need to set two environment 
variables in advanced:

ROUTINO_LIB_DIR=... (absolute path to directory where the build library and other files will be stored)
ROUTINO_SRC_DIR=... (absolute path to directory where the source code will be checked out)

Script call:
./build-routino.sh routino-build

For building the Quazip library there is the bash script "build-quazip.sh" in the MacOSX subdirectory.
The Quazip source has to be downloaded manually from "https://sourceforge.net/projects/quazip/".
To run the script, you need to set three environment variables in advanced:
QUAZIP_LIB_DIR=..   (absolute path to directory where the build library and other files will be stored)
QUAZIP_SRC_DIR=..   (absolute path to directory where the extracted source code has been saved to)
QT_DIR=..           (absolute path to directory where QT has been installed to. If done with brew, it is like /usr/local/Cellar/qt5/5.5..)

Script call:
./build-quazip.sh quazip-build


Building and Bundling QMapShack
*******************************
To get the source of QMapShack:
hg clone https://bitbucket.org/maproom/qmapshack

In the same directory as this how to is the bash script "bundle.sh". The script 
does all steps for packaging the application but not building the binary.
So you need to build the binary first with the command:

mkdir build_QMapShack
cd build_QMapShack
cmake ../QMapShack -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.5... -DCMAKE_OSX_DEPLOYMENT_TARGET=10.12 -DROUTINO_DEV_PATH=... -DQUAZIP_DEV_PATH=... -DCMAKE_BUILD_TYPE=Release
make

"QMapShack" is the relative path to where you have checked out QMapShack.

The four passed parameter are more or less self describing:

CMAKE_PREFIX_PATH path to used libraries by QMapShack, QT5 needs to be set by default.
CMAKE_OSX_DEPLOYMENT_TARGET the target system of the build (10.11 is the El Capitan OS-X, see https://en.wikipedia.org/wiki/OS_X#Versions for a full list)
ROUTINO_DEV_PATH  The path to the routino library (is the same as you set previously with ROUTINO_LIB_DIR)
QUAZIP_DEV_PATH   The path to the quazip library (is the same as you set previously with QUAZIP_LIB_DIR)
CMAKE_BUILD_TYPE "Debug" or "Release" depending what you want.

If the build was successful, you can run the packaging with several environment 
variables set:

QT_DIR=...            (absolute path to the qt5 library base package, same as in CMAKE_PREFIX_PATH)
GDAL_DIR=...          (absolute path to the gdal library base package)
PROJ_DIR=...          (absolute path to the proj4 library base package)
ROUTINO_LIB_DIR=..    (absolute path to the routino library base package, same as ROUTINO_LIB_DIR / ROUTINO_DEV_PATH)
QUAZIP_LIB_DIR=..     (absolute path to the Quazip library base package)
BUILD_DIR=..          (absolute path to the QMapShack build directory, the created directory "build_QMapShack" for the cmake build)
QMS_SRC_DIR=...       (absolute path to the QMapShack source, the directory "QMapShack" used by cmake)
BUILD_BIN_DIR=...     (absolute path to the directory with the qmapshack binary, typically build_QMapShack/bin for cmake build; depends on IDE)
BUILD_RELEASE_DIR=... (absolute path to the directory where the application bundle should be placed)

./bundle.sh bundle

If everything is ok, you will get the package "QMapShack.app" in the directory "BUILD_RELEASE_DIR".
Double-click on the package and have fun with QMapShack.


Debugging QMapShack
*******************
The best way to debug QMapShack is using your IDE. To open QMapShack do for...

* Create Xcode project from source:

mkdir build_xcode
cmake ../QMapShack -G Xcode -D....

The same command as described in the build with cmake, except of the additional 
option "-G Xcode".

* JetBrains CLion:
Nothing to be done, just open the Project folder in CLion.
You need to set "CMake options" under "Preferences > Build, Execution, Development > CMake".

-DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.5... -DCMAKE_OSX_DEPLOYMENT_TARGET=10.12 -DROUTINO_DEV_PATH=... -DQUAZIP_DEV_PATH=...
The list is the same as described for the cmake build above.


A note about directory structure in QMapShack
********************************************
QMapShack relies on the directory structure of a OS-X application bundle. This 
means that you can not run QMapShack correctly if you just make a build (binary)
and run this. You need many different files placed with the correct relative path
to the binary. If you don't have this, you will get already at the startup of 
QMapShack an error message (which you can click away at your own risk).
The easiest way to have a fully working version from within your IDE of QMapShack:
- Create a bundle as described above in "Building and Bundling QMapShack"
- Open the bundle QMapShack.app and copy the subdirectory Contents/Resources
- Paste the copied directory Resources relative one directory up to the binary
qmapshack directory (../Resources)

When starting qmapshack now, there shouldn't be an error message anymore.
