Howto Building QMapShack on OS-X ( 21/8/2019 )
********************************

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)
- git (git) command line tool
- Xcode and Xcode Command Line Tools

Because brew nowadays does not include qt5 with mysql the best way is to install most of the required packages by using MacPorts and some by using brew.
When your build machine runs Mojave 10.14 QMapShack will also need 10.14 to run. For older OS X build system has to be an older version too.

Download the adequate MacPorts package 2.5.4 from https://github.com/macports/macports-base/releases/tag/v2.5.4, install it and use terminal to install the following packages:

sudo port install cmake
sudo port install qt5-qtbase
sudo port install qt5-mysql-plugin
sudo port install qt5-sqlite-plugin
sudo port install qt5-qttranslations
sudo port install qt5-qtwebengine
sudo port install gdal
sudo port install mercurial
sudo port install proj6
sudo port install quazip

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 the required packages:
brew install svn

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


Building QMapShack and QMapTool
*******************************
To get the source of QMapShack:
git clone https://github.com/Maproom/qmapshack.git QMapShack

In the same directory as this how to is the bash script "bundle-all.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 commands:

mkdir build_QMapShack
cd build_QMapShack
cmake ../QMapShack -DCMAKE_PREFIX_PATH=/opt/local/libexec/qt5 -DCMAKE_OSX_DEPLOYMENT_TARGET=10.12 -DROUTINO_DEV_PATH=... -DCMAKE_BUILD_TYPE=Release -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON -DQUAZIP_INCLUDE_DIR=/opt/local/include/quazip5 -DQUAZIP_LIBRARIES=/opt/local/lib/libquazip5.1.0.0.dylib -DPROJ4_ROOT=/opt/local/lib/proj6 -DPROJ4_INCLUDE_DIRS=/opt/local/lib/proj6/include -DPROJ4_LIBRARIES=/opt/local/lib/proj6/lib/libproj.15.dylib
make

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

The 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.12 is the Sierra OS-X, see https://en.wikipedia.org/wiki/OS_X#Versions for a full list, best results when set to the OS X of build machine)
ROUTINO_DEV_PATH  The path to the routino library (is the same as you set previously with ROUTINO_LIB_DIR)
CMAKE_BUILD_TYPE "Debug" or "Release" depending what you want
DCMAKE_VERBOSE_MAKEFILE enable verbose output from Makefile builds
DQUAZIP_INCLUDE_DIR path to used include directory for Quazip
DQUAZIP_LIBRARIES path to used libraries for Quazip
DPROJ4_ROOT look exclusively in this directory
DPROJ4_INCLUDE_DIRS path to used include directory for proj
DPROJ4_LIBRARIES path to used libraries for proj


Bundling QMapShack and QMapTool
*******************************
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, z.B. /opt/local/libexec/qt5 )
GDAL_DIR=...          (absolute path to the gdal library base package, z.B. /opt/local )
PROJ_DIR=...          (absolute path to the proj4 library base package, z.B. /opt/local/lib/proj6)
ROUTINO_LIB_DIR=..    (absolute path to the routino library base package, same as ROUTINO_LIB_DIR / ROUTINO_DEV_PATH, z.B. /Users/.../Desktop/ROUTINO_BUILD )
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-all.sh bundle

If everything is ok, you will get the package "QMapShack.app" and QMapTool.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==/opt/local/libexec/qt5 -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.
