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, we have some hints how to do so
here as well.

As of Subsurface 4.3 all of the prebuilt binaries that we provide (right
now Windows64, Windows32, Mac, Ubuntu and LinuxMint) 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.3 branch)
git://git.subsurface-divelog.org/libdc (in the Subsurface-4.3 branch)

Both of these repositories also have a Subsurface-testing branch. That
branch is explicitly marked as NOT STABLE and will receive force pushes.
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 so those testing branches get frequently rebased.

Also, all of the prebuilt binaries (with the exception of the Windows32
build) are now Qt5 based and Qt5 is considered the stable and supported
framework to use for building Subsurface.

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

The following options are recognized when passed to qmake:

 -config debug        Create a debug build
 -config release      Create a release build
		      The default depends on how Qt was built.
 V=1                  Disable the "silent" build mode
 LIBDCDEVEL=1         Search for libdivecomputer in ../libdivecomputer
 LIBMARBLEDEVEL=path  Search for marble library and includes in path
 LIBGIT2DEVEL=path    Search for libgit2 library and includes in path
 INCLUDEPATH+=xxx     Add xxx to the include paths to the compiler
		      (pass the actual path, without -I)
 LIBS+=xxx            Add xxx to the linker flags. -l and -L options are
		      recognized.

The INCLUDEPATH and LIBS options are useful to tell the buildsystem
about non-standard installation paths for the dependencies (such as
Marble). They can be repeated as often as needed, or multiple
arguments can be passed on the same switch, separated by a space. For
example:

  qmake LIBS+="-L$HOME/marble/lib -L$HOME/libdivecomputer/lib" \
	INCLUDEPATH+="$HOME/marble/include $HOME/libdivecomputer/include"


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

FIXME -- Debian package names needed

On Debian style distributions you can install the required development
packages by running (once Qt version of subsurface is available in your
distribution)
$ sudo apt-get build-dep subsurface
but on many of them this will give you the build dependencies for the
official package (which is often way out of date). So be careful that this
doesn't get you a Qt4 based environment

If you want to install the required packages individually instead you
need libqt4-dev, qt4-qmake, libxml2-dev, libxslt1-dev, zlib1g-dev,
libzip-dev, libmarble-dev, libsqlite3-dev, libqtwebkit-dev
(and libusb-1.0-0-dev if you're going to compile libdivecomputer).


First you need to compile our version of libdivecomputer:

$ mkdir ~/src # unless you have this already
$ cd ~/src
$ git clone -b Subsurface-4.3 git://subsurface-divelog.org/libdc libdivecomputer
       # or -b Subsurface-testing to get the testing version - careful,
       #                          careful - this gets rebased and may be broken

$ cd libdivecomputer
$ autoreconf --install
$ ./configure --disable-shared
$ make
$ sudo make install

Then you compile our custom branch of libmarblewidget

$ cd ~/src
$ git clone -b Subsurface-4.3 git://subsurface-divelog.org/marble marble-source
       # or -b Subsurface-testing to get the testing version - careful,
       #                          careful - this gets rebased and may be broken

$ mkdir marble-build
$ cd marble-build
$ 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
$ make # <- this step will take quite a while... if you have more cores
       #    try make -j8 or something like that
$ sudo make install

Finally you can compile Subsurface:

$ cd ~/src
$ git clone git://subsurface-divelog.org/subsurface.git
$ cd subsurface
$ cd git checkout v4.3   # this get's you the last release
                         # skip this step to build the latest development
			 # version
$ qmake  # on Fedora you need qmake-qt5
$ make
$ sudo make install    # [optionally, add: prefix=/usr/local]

At least on Fedora you need to make sure that /usr/local/lib is searched
for shared libraries (this is where the steps above installed
libdivecomputer and libmarblewidget in oder not to conflict with system
pacakges). So you need to do the following:
$ sudo echo "/usr/local/lib" > /etc/ld.so.conf.d/local.conf
$ sudo ldconfig

Now you should be able to start the Subsurface binary you just created
with

$ ./subsurface


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.github.com/mxcl/homebrew/go/install)"

2) Install needed dependencies

$ brew install asciidoc libzip qt sqlite cmake libusb pkg-config

3) Make the brew version of sqlite the default

$ brew link --force sqlite

4) Install Marble

$ mkdir -p ~/src/marble/build
$ git clone -b KDE/4.11 git://anongit.kde.org/marble ~/src/marble/sources
$ cd ~/src/marble/build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DQTONLY=TRUE -DCMAKE_INSTALL_PREFIX=/usr/local ../sources
 - or -
$ cmake -DCMAKE_BUILD_TYPE=Release -DQTONLY=TRUE -DCMAKE_INSTALL_PREFIX=/usr/local ../sources
$ cd src/lib
$ make -j4
$ install_name_tool -id /usr/local/lib/`echo libmarblewidget.??.dylib` libmarblewidget.dylib
$ cp *dylib /usr/local/lib/
$ mkdir -p /usr/local/include/marble
$ cd ../../../sources/src/lib
$ cp $(find . -name '*.h') /usr/local/include/marble/

5) Install Libdivecomputer

$ brew install automake libtool
$ cd ~/src
$ git clone git://git.libdivecomputer.org/libdivecomputer
$ cd libdivecomputer
$ git checkout release-0.4
$ autoreconf --install
$ ./configure --disable-shared
$ make
$ make install

6) Compile Subsurface

$ cd ~/src
$ git clone git://subsurface-divelog.org/subsurface.git
$ cd subsurface
$ qmake
$ make
$ make install_mac_bundle

After the above is done, Subsurface will be installed to
/Applications.

Another option is to create a .dmg for distribution:

$ qmake
$ make
$ make mac-create-dmg

NOTES: macdeployqt assumes that the plugins are located "next" to the
frameworks. The frameworks are linked from /usr/local/lib - but the
plugins are not in /usr/local/plugins.
The easiest workaround is to create a symbolic link from
/usr/local/plugins to /usr/local/Cellar/qt/4.8.5/plugins (or whatever
version of Qt you have built earlier).

Building the Qt version under MacOSX (using MacPorts)
-----------------------------------------------------

1)  Install MacPorts

Please refer to http://www.macports.org/install.php

2)  Install needed dependencies

$ sudo port -vp install asciidoc libzip libusb sqlite cmake qt4-mac marble libdivecomputer libgit2

3)  Check dependencies' versions

$ port installed qt4-mac libdivecomputer marble libzip asciidoc libusb sqlite cmake
The following ports are currently installed:
  asciidoc @8.6.9_1 (active)
  cmake @2.8.12_3 (active)
  libdivecomputer @0.4.1_0 (active)
  libgit2 @0.20.0_0 (active)
  libusb @1.0.18_0 (active)
  libzip @0.11.1_0 (active)
  marble @4.12.2_0 (active)
  qt4-mac @4.8.5_1 (active)

4) Compile Subsurface

$ cd ~/src
$ git clone git://subsurface-divelog.org/subsurface.git
$ cd subsurface
$ qmake
$ make
$ make install_mac_bundle

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 19). A shell script to do
that (plus the .nsi file to create the installer with makensis) are
included in the packaging/windows directory.

The best way to get libdivecomputer to build appears to be

$ mkdir -p ~/src
$ git clone git://git.libdivecomputer.org/libdivecomputer ~/src/libdivecomputer
$ cd ~/src/libdivecomputer
$ git checkout release-0.4
$ mingw32-configure --disable-shared
$ mingw32-make
$ sudo mingw32-make install

To compile Marble, use:

$ mkdir -p ~/src/marble/build
$ git clone -b KDE/4.11 git://anongit.kde.org/marble ~/src/marble/sources
$ cd ~/src/marble/build
$ mingw32-cmake -DCMAKE_BUILD_TYPE=Debug -DQTONLY=TRUE ../sources
 - or -
$ mingw32-cmake -DCMAKE_BUILD_TYPE=Release -DQTONLY=TRUE ../sources
$ mingw32-make -j4
$ mingw32-make install

To compile libgit2, use:

$ mkdir -p ~/src/libgit2/build
$ git clone git://github.com/libgit2/libgit2 ~/src/libgit2
$ cd ~/src/libgit2/build
$ mingw32-cmake ..
$ mingw32-cmake --build .

To compile Subsurface, use:

$ mkdir -p ~/src/subsurface
$ git clone git://subsurface-divelog.org/subsurface.git ~/src/subsurface
$ cd ~/src/subsurface
$ packaging/windows/mingw-make.sh
$ 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-mingw32/sys-root/mingw/bin
Similarly, the paths used in packaging/windows/mingw-make.sh may need to
be adjusted according to your distributions layout


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

1) Install msys-git:
http://msysgit.github.io

Tools part of MSYS are required for building Subsurface, while you also
need Git to be upstream and contribute to the project.
Make sure that the msys/bin (or git/bin) folder is in PATH.

2) Install Qt
http://qt-project.org/downloads

Subsurface is currently built against Qt 4.8.5.

3) Install a MinGW toolchain
https://docs.google.com/open?id=0B4D8x6CJEmtuczdiQklwMEs4RUU

Qt 4.8.5 comes without a compiler and you will have to download it from
a separate location. Other compiler may work, but there are no guaranties for
that. Make sure that the mingw/bin folder is in PATH.

4) Install Libdivecomputer
Use similar steps to the previous section, without the sudo command.

5) Install CMake (required for building Marble):
http://www.cmake.org/cmake/resources/software.html

Make sure that the cmake/bin folder is in PATH.

5) Download and build Marble
http://marble.kde.org/sources.php
http://techbase.kde.org/Projects/Marble/WindowsCompiling#Compiling_Marble_using_MingW

Make sure you build both the Debug and Release versions.

6) Install pkg-config
http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/pkg-config_0.26-1_win32.zip

pkg-config depends on DLL files such as libglib-2.0-0.dll and has to be in
PATH, so it's best that you copy the executable to msys/bin.

7) Install other dependencies
Subsurface also depends on the following libraries:

* libxml2
http://www.xmlsoft.org/downloads.html
* libxslt
http://xmlsoft.org/XSLT/
* libusb-1.0
http://sourceforge.net/apps/trac/libusb-win32/wiki
* zlib
http://www.zlib.net/
* libzip
http://www.nih.at/libzip/

Once you have the libraries, create .pc files (pkg-config) for them and place
the files in a folder that is indicated by the PKG_CONFIG_PATH environment
variable - e.g. PKG_CONFIG_PATH=c:\msys\pkg-config

To build subsurface, use:

$ git clone git://subsurface-divelog.org/subsurface.git
$ cd subsurface
$ qmake
$ make
$ make install
$ make installer