path: root/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, 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/subsurface.git

You keep it updated by doing:
    git checkout master
    git pull -r
    
   

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/libdc.git

In order to get the modified sources, do
- locate yourself in the subsurface repo on your local computer
- run "git submodule 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-NG".

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.9.1 is the oldest version supported if ONLY building Subsurface
Qt5.12 is the oldest version supported if also building Subsurface-mobile

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 3D2
- Qt Canvas 3D
- Qt Extras
This can be done later by use of MaintenanceTool.app in your Qt folder.

Remark: most Qt installations do not make Qt available on the command
line, which is needed. In order to make Qt available you need to 
add qmake to the path, do something like
PATH=$PATH:<Qt location>/<version>/<type>/bin

QtWebKit is needed, if you want to print, but no longer part of Qt5,
so you need to download it and compile. 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.26 or newer.


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

Our main build system is based on cmake. But qmake is needed
for the googlemaps plugin 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 dnf install autoconf automake bluez-libs-devel cmake gcc-c++ git \
	libcurl-devel libsqlite3x-devel libssh2-devel libtool libudev-devel \
	libusbx-devel libxml2-devel libxslt-devel make \
	qt5-qtbase-devel qt5-qtconnectivity-devel qt5-qtdeclarative-devel \
	qt5-qtlocation-devel qt5-qtscript-devel qt5-qtsvg-devel \
	qt5-qttools-devel qt5-qtwebkit-devel redhat-rpm-config \
	bluez-libs-devel libgit2-devel libzip-devel libmtp-devel


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 \
	bluez-devel libgit2-devel libmtp-devel

On Debian Buster this seems to work

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

In order to build and run mobile-on-desktop, you also need

sudo apt install \
	qtquickcontrols2-5-dev qml-module-qtquick-window2 qml-module-qtquick-dialogs \
	qml-module-qtquick-layouts qml-module-qtquick-controls2 qml-module-qtquick-templates2 \
	qml-module-qtgraphicaleffects qml-module-qtqml-models2 qml-module-qtquick-controls


Package names for Ubuntu 20.04

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

In order to build and run mobile-on-desktop, you also need

sudo apt install \
	qtquickcontrols2-5-dev qml-module-qtquick-window2 qml-module-qtquick-dialogs \
	qml-module-qtquick-layouts qml-module-qtquick-controls2 qml-module-qtquick-templates2 \
	qml-module-qtgraphicaleffects qml-module-qtqml-models2 qml-module-qtquick-controls


On Raspberry Pi (Raspian Buster and Ubuntu Mate 20.04.1) this seems to work

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

In order to build and run mobile-on-desktop, you also need

sudo apt install \
	qtquickcontrols2-5-dev qml-module-qtquick-window2 qml-module-qtquick-dialogs \
	qml-module-qtquick-layouts qml-module-qtquick-controls2 qml-module-qtquick-templates2 \
	qml-module-qtgraphicaleffects qml-module-qtqml-models2 qml-module-qtquick-controls


Note that on Ubuntu Mate on the Raspberry Pi, you may need to configure
some swap space in order for the build to complete successfully. There is no
swap space configured by default. See the dphys-swapfile package.

On PCLinuxOS you appear to need the following packages

su -c "apt-get install -y autoconf automake cmake gcc-c++ git libtool  \
lib64bluez-devel lib64qt5bluetooth-devel lib64qt5concurrent-devel \
lib64qt5help-devel lib64qt5location-devel lib64qt5quicktest-devel \
lib64qt5quickwidgets-devel lib64qt5script-devel lib64qt5svg-devel \
lib64qt5test-devel lib64qt5webkitwidgets-devel lib64qt5xml-devel \
lib64ssh2-devel lib64usb1.0-devel lib64zip-devel qttools5 qttranslations5"

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/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 by manually building the dependencies from source, 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 autoconf automake libtool hidapi libusb libxml2 libxslt libzip openssl pkg-config libgit2 libssh2 libjpg libpng libmtp

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-*; ./configure && make && sudo make install; cd ..

3) 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 and iOS

1.1) cd <repo>/..; bash <repo>/scripts/build.sh -build-deps -both
note: this is mainly done to ensure all external dependencies are downloaded and set
      to the correct versions

2) continue 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.

In addition you can use the Docker container the same way that CI builds do modify/test 
 modifications to the container build environment following instructions in 
/scripts/docker/mxe-build-container/instructions.md

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 folder containing the subsurface source dir run: bash subsurface/packaging/android/android-build-wrapper.sh
This will download and install the required NDK, SDK and Qt required to build the app.

After that, you can run: ./subsurface/packaging/android/build.sh everytime you want to build a new version.

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