subsurface/INSTALL

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

Subsurface uses a few open source libraries and frameworks to do its
job. The most important ones include libdivecomputer, Qt, Marble
(more precisely libmarblewidget), libxml2, libxslt, libsqlite3, libzip,
and libgit2.

Below are instructions for building Subsurface under some popular
Linux distributions, for building Subsurface using Homebrew on a Mac,
and for cross-building Subsurface for 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.

All of the prebuilt binaries that we provide (right now Windows, Mac,
Ubuntu/Debian/LinuxMint, and openSUSE/Fedora) are built using our own
custom "flavors" of libdivecomputer and libmarblewidget. You can get
these from

git://git.subsurface-divelog.org/marble (in the Subsurface-4.4 branch)
git://git.subsurface-divelog.org/libdc (in the Subsurface-4.4 branch)

Both of these repositories also have a Subsurface-branch branch. That
branch is intended for developers trying to track our development here.
It won't have a pretty history and will include ugly merges, but it should
always allow a fast forward pull that tracks what we believe developers
should build again.

In contrast to that both repositories also have Subsurface-clean branches.
These 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 either of
these two projects. We simply are adding a few patches on top of their
latest versions 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.

Also, all of the prebuilt binaries are now Qt5 based and Qt5 is considered
the stable and supported framework to use for building Subsurface. As of
Subsurface 4.5 we are switching our build system to cmake. qmake based
builds are no longer supported.

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

The following options are recognized 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

Building Subsurface 4 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 \
	libgit2-devel libudev-devel libusbx-devel \
	qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtscript-devel \
	qt5-qtwebkit-devel qt5-qtsvg-devel qt5-qttools-devel \
	qt5-qtconnectivity-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 libgit2-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

On Debian Jessie and recent Ubuntu flavors this seems to work

sudo apt-get install git g++ make autoconf libtool cmake pkg-config \
	libxml2-dev libxslt1-dev libzip-dev libsqlite3-dev \
	libusb-1.0-0-dev libgit2-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 libgrantlee-dev

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 git://subsurface-divelog.org/subsurface
./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
install-root/bin/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:

install-root/bin/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 (using Homebrew)
-------------------------------------------------

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

$ xcode-select --install

1)  Install Homebrew

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

2) Install needed dependencies

$ brew install asciidoc libzip sqlite cmake libusb pkg-config automake libtool

3) Make the brew version of sqlite the default

$ brew link --force sqlite

4) Download and install Qt

You can build Qt from source or use the prebuilt binaries for Mac. Start
by downloading the online installer:

$ curl -L -o ~/Downloads/qt-unified-mac-x64-online.dmg \
	http://download.qt.io/official_releases/online_installers/qt-unified-mac-x64-online.dmg
$ open ~/Downloads/qt-unified-mac-x64-online.dmg

Double click on the Qt installer shown in the Finder window.

In the installer, chose an install folder (the build script we are using
below assumes that you accept the default of /home/<your username>/Qt), in
"Select components" select the most recent version and (if you want to
build Qt from source) be sure you also install the "Source Components".
To save time and disk space you can unselect Android and IOS packages
as well as QtWebEngine, Qt3D, Qt Canvas 3D and the Qt Extras.

If you want to build from source (which takes a very long time and a lot of disk)

$ cd ~/Qt/5.5/Src/

$ ./configure -prefix /usr/local -opensource

$ make -j4

$ make install

5) run the build script

cd ~/src
bash subsurface/scripts/build.sh

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

$ open subsurface/build/Subsurface.app

or you can move this folder to /Applications to install Subsurface for
every user.


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

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

On OpenSUSE, for mingw64 packages you should add the specific
repository from their site. After that you can run the following
command:
sudo zypper install mingw64-cross-libqt5-qttools mingw64-mpc-devel \
      mingw64-filesystem mingw64-pkg-config mingw64-cross-gcc \
      mingw64-gcc-c++ mingw64-libusb-1_0-devel \
      mingw64-cross-libqt5-qttools mingw64-libqt5-qtwebkit \
      mingw64-libqt5-qtwebkit-devel mingw64-cross-libqt5-qmake \
      mingw64-libqt5-qtscript mingw64-libqt5-qtscript-devel \
      mingw64-libqt5-qtsvg mingw64-libqt5-qtsvg-devel \
      mingw64-libqt5-qtdeclarative mingw64-libqt5-qtdeclarative-devel \
      mingw64-libssh2-devel mingw64-libzip-devel \
      mingw64-sqlite-devel mingw64-win_iconv-devel \
      mingw64-libxslt-devel mingw64-libqt5-qttools

[Observation] - Sometimes on OpenSUSE platform there is a problem with
the mingw64-libzip-devel package(the zipconf header is not installed in
the right place) and you have to create a symbolic link using the following
command:
  sudo ln -s /usr/x86_64-w64-mingw32/sys-root/mingw/lib/libzip/include/zipconf.h \
	     /usr/x86_64-w64-mingw32/sys-root/mingw/include/zipconf.h

Everywhere below the mingw64- prefix is used for the cross tools. If you
really need a 32bit binary you need to use mingw32- as prefix and you may
also run into issues creating an installable binary with Qt5 (i.e., you
may have to go back to Qt4).

The best way to get libdivecomputer to build appears to be

$ mkdir -p ~/src
$ cd ~/src
$ git clone -b Subsurface-4.4 git://subsurface-divelog.org/libdc libdivecomputer
       # or -b Subsurface-branch to get the development version
       #
       # -> when not building a release version of Subsurface but the
       #    latest master, it may be necessary to build against the
       #    Subsurface-branch branch

$ cd libdivecomputer
$ autoreconf --install
$ mingw64-configure --disable-shared
$ mingw64-make
$ sudo mingw64-make install

To compile Marble, use:

$ cd ~/src
$ git clone -b Subsurface-4.4 git://subsurface-divelog.org/marble marble-source
       # or -b Subsurface-branch to get the development version

$ mkdir marble-build
$ cd marble-build
$ mingw64-cmake -DQTONLY=ON -DQT5BUILD=ON \
	-DBUILD_MARBLE_APPS=OFF -DBUILD_MARBLE_EXAMPLES=OFF \
	-DBUILD_MARBLE_TESTS=OFF -DBUILD_MARBLE_TOOLS=OFF \
	-DBUILD_TESTING=OFF -DWITH_DESIGNER_PLUGIN=OFF \
	-DBUILD_WITH_DBUS=OFF ../marble-source
$ mingw64-make # <- this step will take quite a while... if you have more cores
               #    try ming64-make -j8 or something like that
$ sudo mingw64-make install

To compile libgit2, use:

$ git clone git://github.com/libgit2/libgit2 ~/src/libgit2
$ mkdir ~/src/libgit2/build
$ cd ~/src/libgit2
$ git checkout v0.23.1
$ cd build
$ mingw64-cmake ..
$ mingw64-make
$ sudo mingw64-make install

To compile Subsurface, use:

$ cd ~/src
$ git clone git://subsurface-divelog.org/subsurface.git
$ cd subsurface
$ cd git checkout v4.4.2   # this get's you the last release
                         # skip this step to build the latest development
			 # version
$ packagin/windows/mingw-make.sh Qt5 SPECIAL_MARBLE_PREFIX=1
$ packaging/windows/mingw-make.sh install
$ packaging/windows/mingw-make.sh installer

The last step assumes that you have a link from packaging/windows/dll to
the correct directory in your MinGW installation. On my machine that is
/usr/i686-w64-mingw64/sys-root/mingw/bin
Similarly, the paths used in packaging/windows/mingw-make.sh may need to
be adjusted according to your distributions layout

Also, at least one version of Qt DLLs shipping with Fedora was
self-inconsistent at caused random crashes at startup. Unless you have
good reasons to build your own binaries, on Windows you may be better off
with the pre-compiled binaries we provide.


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...