subsurface/INSTALL

Building Subsurface from Source
===============================

Subsurface uses quite a few open source libraries and frameworks to do its
job. The most important ones include libdivecomputer, Qt, libxml2, libxslt,
libsqlite3, libzip, libgrantlee5 and libgit2.

Below are instructions for building Subsurface
- on some popular Linux distributions,
- MacOSX,
- Windows (cross-building)
- Android (cross-building)
- iOS (cross-building)


Getting Subsurface source
-------------------------

You can get the sources to the latest development version from our git
repository:
    git clone http://github.com/Subsurface-divelog/subsurface.git

You keep it updated by doing:
    git checkout master
    git pull -r
    
If you plan on making pull requests, you need furthermore to:
   - clone subsurface.git to your GitHub account
   - make a new local work branch, name it after the patch like e.g. myFirstPatch
   - Do the work you want to do (including testing it)
   - Commit and Push myFirstPatch to your forked repo on github
   - Make the pull request
   - REMEMBER do not delete this branch, until your pull request is merged
     this is because if changes are requested, you simply add a new commit/push
   - Also remember 1 pull-request == 1 branch
   

Getting our flavor of libdivecomputer
-------------------------------------

All our prebuilt binaries (see https://subsurface-divelog.org/download)
are built using our own custom "flavor" of libdivecomputer
see https://github.com/Subsurface-divelog/libdc.git

In order to get the modified sources, do
- locate yourself in the subsurface repo on your local computer
- run "git submoule init"
- run "git submodule update"

The branches won't have a pretty history and will include ugly merges,
but they should always allow a fast forward pull that tracks what we
believe developers should build against. All our patches are contained
in the "Subsurface-branch" which are also HEAD.

This should allow distros to see which patches we have applied on top of
upstream. They will receive force pushes as we rebase to newer versions of
upstream so they are not ideal for ongoing development (but they are of
course easy to use for distributions as they always build "from scratch",
anyway).

The rationale for this is that we have no intention of forking the
project. We simply are adding a few patches on top of their latest
version and want to do so in a manner that is both easy for our
developers who try to keep them updated frequently, and anyone packaging
Subsurface or trying to understand what we have done relative to their
respective upstreams.


Getting Qt5
-----------

We use Qt5 in order to only maintain one UI across platforms. Qt5.8 is the
oldest version supported.

Download the Open Source version from https://www.qt.io/download and 
follow the Qt instructions to install it or alternatively follow the
instruction specific to a distribution (see build instructions).

To save time and disk space you can unselect Android and IOS packages
(Of course unless you want to build Android/iOS versions) as well as
- Qt Data Visualisation
- Qt Purchasing
- Qt Virtual Keyboard",
- Qt WebEngine
- Qt Network Authorization
- Qt Remote Objects
- Qt WebGL Streaming
- Qt Script
- Qt 3D2
- Qt Canvas 3D
- Qt Extras
This can be done later by use of MaintenanceTool.app in your Qt folder.

Remark: most Qt installations does not make Qt available on the command
line, which is needed. In order to make Qt available you need to 
add a symbol link (do something like
ln -s <Qt location>/<version>/<type>/bin/qmake /usr/local/bin/qmake

QtWebKit is needed, if you want to print, but no longer part of Qt5,
so you need to download it and compile. We want to replace QtWebKit,
but at the moment the print process depends on functions only available
in QtWebKit. In case you just want to test without print possibility
omit this step.


Other third party library dependencies
--------------------------------------

In order for our cloud storage to be fully functional you need
libgit2 0.23 or newer.


cmake build system
------------------

As of Subsurface 4.5 we have switched our build system to cmake.
qmake based builds are no longer supported. Remark even though
no longer supported, qmake is still used by googlemaps and the iOS build.

Download from https://cmake.org/download and follow the instructions
to install it or alternatively follow the instruction specific to a
distribution (see build instructions).



Build options for Subsurface
----------------------------

The following options are recognised when passed to cmake:

 -DCMAKE_BUILD_TYPE=Release	create a release build
 -DCMAKE_BUILD_TYPE=Debug	create a debug build

The Makefile that was created using cmake can be forced into a much more
verbose mode by calling

 make VERBOSE=1

Many more variables are supported, the easiest way to interact with them is
to call

 ccmake .

in your build directory.


Building the development version of Subsurface under Linux
----------------------------------------------------------

On Fedora you need

sudo yum install git gcc-c++ make autoconf automake libtool cmake \
	libzip-devel libxml2-devel libxslt-devel libsqlite3x-devel \
	libudev-devel libusbx-devel libcurl-devel libssh2-devel\
	qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtscript-devel \
	qt5-qtwebkit-devel qt5-qtsvg-devel qt5-qttools-devel \
	qt5-qtconnectivity-devel qt5-qtlocation-devel

Note that beginning with Fedora 22, you should be using the dnf command instead
as yum is being deprecated.

Package names are sadly different on OpenSUSE

sudo zypper install git gcc-c++ make autoconf automake libtool cmake libzip-devel \
	libxml2-devel libxslt-devel sqlite3-devel libusb-1_0-devel \
	libqt5-linguist-devel libqt5-qttools-devel libQt5WebKitWidgets-devel \
	libqt5-qtbase-devel libQt5WebKit5-devel libqt5-qtsvg-devel \
	libqt5-qtscript-devel libqt5-qtdeclarative-devel \
	libqt5-qtconnectivity-devel libqt5-qtlocation-devel libcurl-devel

On Debian Stretch this seems to work

sudo apt-get install git g++ make autoconf automake libtool cmake pkg-config \
	libxml2-dev libxslt1-dev libzip-dev libsqlite3-dev \
	libusb-1.0-0-dev libssl-dev \
	qt5-default qt5-qmake qtchooser qttools5-dev-tools libqt5svg5-dev \
	libqt5webkit5-dev libqt5qml5 libqt5quick5 libqt5declarative5 \
	qtscript5-dev libssh2-1-dev libcurl4-openssl-dev qttools5-dev \
	qtconnectivity5-dev qtlocation5-dev qtpositioning5-dev \
	libcrypto++-dev libssl-dev qml-module-qtpositioning qml-module-qtlocation \
	qml-module-qtquick2

Package names for Ubuntu 16.10

sudo apt-get install git g++ make autoconf automake libtool cmake pkg-config \
	libxml2-dev libxslt1-dev libzip-dev libsqlite3-dev \
	libusb-1.0-0-dev libssl-dev \
	qt5-default qt5-qmake qtchooser qttools5-dev-tools libqt5svg5-dev \
	libqt5webkit5-dev libqt5qml5 libqt5quick5 qtdeclarative5-dev \
	qtscript5-dev libssh2-1-dev libcurl4-openssl-dev qttools5-dev \
	qtconnectivity5-dev qtlocation5-dev qtpositioning5-dev \
	libcrypto++-dev libssl-dev qml-module-qtpositioning qml-module-qtlocation \
	qml-module-qtquick2

On PCLinuxOS you appear to need the following packages

su -c "apt-get install -y autoconf automake cmake libtool gcc-c++ git \
lib64usb1.0-devel lib64zip-devel lib64qt5webkitwidgets-devel qttools5 \
qttranslations5 lib64qt5xml-devel lib64qt5test-devel lib64qtscript-devel \
lib64qt5svg-devel lib64qt5concurrent-devel lib64qt5bluetooth-devel"

In order to build Subsurface, use the supplied build script. This should
work on most systems that have all the prerequisite packages installed.

You should have Subsurface sources checked out in a sane place, something
like this:

mkdir -p ~/src
cd ~/src
git clone https://github.com/Subsurface-divelog/subsurface.git
./subsurface/scripts/build.sh # <- this step will take quite a while as it
                              #    compiles a handful of libraries before
			      #    building Subsurface

Now you can run Subsurface like this:

cd ~/src/subsurface/build
./subsurface


Note: on many Linux versions (for example on Kubuntu 15.04) the user must
belong to the dialout group.

You may need to run something like

sudo usermod -a -G dialout username

with your correct username and log out and log in again for that to take
effect.

If you get errors like:

./subsurface: error while loading shared libraries: libGrantlee_Templates.so.5: cannot open shared object file: No such file or directory

You can run the following command:

sudo ldconfig ~/src/install-root/lib


Building Subsurface under MacOSX
--------------------------------

You have 2 options for the first time install, either using homebrew or manual,
depending on what else you have installed on your mac.

0) You need to have XCode installed. The first time (and possibly after updating OSX)

0.1) run "xcode-select --install"

homebrew option:

1) brew install libzip cmake libusb pkg-config automake libtool hidapi curl libssh2

2) cd <repo>/..; bash <repo>/scripts/build.sh


Manual option:
1) install pkg-config

1.1) download http://sourceforge.net/projects/macpkg/files/PkgConfig/0.26/PkgConfig.pkg/download

1.2) run "PkgConfig.pkg"

1.3) run "sudo ln -s /opt/pkgconfig/bin/pkg-config /usr/local/bin/pkg-config"

2) install autoconf tools

2.1) curl -OL http://ftpmirror.gnu.org/autoconf/autoconf-latest.tar.gz

2.2) tar -xzf autoconf-latest.tar.gz

2.3) cd autoconf-*

2.4) ./configure && make && sudo make install

2.5) cd ..

3) install 

4) cd <repo>/..; bash <repo>/scripts/build.sh -build-deps -desktop

After the above is done, Subsurface.app will be available in the
subsurface/build directory. You can run Subsurface with the command

A) open subsurface/build/Subsurface.app
   this will however not show diagnostic output

B) subsurface/build/Subsurface.app/Contents/MacOS/Subsurface
   the TAB key is your friend :-)
   
Debugging can be done with either Xcode or QtCreator.

To install the app for all users, move subsurface/build/Subsurface.app to /Applications.


Cross-building Subsurface on MacOSX for iOS
-------------------------------------------

1) build SubSurface under MacOSX
2) build as described in subsurface/packaging/ios




Cross-building Subsurface on Linux for Windows
----------------------------------------------

Subsurface builds nicely with MinGW - the official builds are done as
cross builds under Linux (currently on Ubuntu 14.04). A shell script to do
that (plus the .nsi file to create the installer with makensis) are
included in the packaging/windows directory.

Please read through the explanations and instructions in
packaging/windows/mxe-based-build.sh if you want to build the Windows
version on your Linux system.


Building Subsurface on Windows
------------------------------

This is NOT RECOMMENDED. To the best of our knowledge there is one single
person who regularly does this. The Subsurface team does not provide support
for Windows binary build from sources natively under Windows...

The lack of a working package management system for Windows makes it
really painful to build Subsurface natively under Windows,
so we don't support that at all.



Cross-building Subsurface on Linux for Android
----------------------------------------------

To compile the mobile version you will need:

-Qt for Android (this can be downloaded from: http://www.qt.io/download-open-source/)
-Android SDK
-Android NDK

In the packaging/android folder, open the build.sh file and add the paths to the SDK,
NDK and Qt for android at the top.

After that, you can run: ./subsurface/packaging/android/build.sh

This will generate an apk file in ./subsurface-mobile-build-arm/bin