Building and Deployment

Building

In general, there are two ways of building depthmapX - either using the command line or in an IDE set up for [developing depthmapX]. This page will describe command line builds as used for a release. Generally, the build is very similar on all platforms - as a prerequisite, git, a version of the QT5 SDK and a compiler toolchain must be installed, which allow to run qmake and then make to build the software. To run the regression tests, also an installation of python >= 3.5 is required

Windows

depthmapX on Windows uses the Microsoft Visual studio compiler and require MSVC 2015 or later as we started to rely heavily on C++-11 features. You need to go to https://www.qt.io/ and get an open source version of QT5 installed on your machine.

With Qt5 on the path and the command line compiler toolchain set up using the scripts provided by Microsoft (vsvars32.bat for 32 bit compiler, the 64 bit version is slightly more complicated). You should then be able to do the following in a cmd window:

C:\code>git clone https://github.com/SpaceGroupUCL/depthmapX  <-- clone the git repo
C:\code>cd depthmapX
C:\code\depthmapX>md build                                    <-- create a folder for the build outpu
C:\code\depthmapX>cd build
C:\code\depthmapX\build>qmake ..                              <-- run qmake on the main project file
C:\code\depthmpaX\build>nmake                                 <-- invoke the MSVC command line build

Running the tests

To run the unit tests, run:

C:\code\depthmapX\build>cliTest\release\cliTest.exe
C:\code\depthmapX\build>GuiUnitTest\release\GuiUnitTest.exe
C:\code\depthmapX\build>genlibTest\release\genlibTest.exe
C:\code\depthmapX\build>salaTest\release\salaTest.exe

For regression tests, see Regression Testing

To run the freshly built depthmapX: C:\code\depthmapX\build>GuiApp/release/depthmapX.exe

Linux

Linux development and testing is carried out on Ubuntu 16.04LTS at the moment - any other distributions might just work, but are not tested. Required compilers are clang >= LLVM 3.4 or gcc >= 4.8.4 You can either install an open source QT5 from https://qt.io (https://wiki.qt.io/Install_Qt_5_on_Ubuntu) or use a version from launchpad, e.g. https://launchpad.net/~beineri/+archive/ubuntu/opt-qt58-trusty You will also need python >= 3.5 to run the regression tests.

Alternatively, there is a docker image available to run depthmapX builds, if you have docker installed you can run docker run -it blackseamonster/depthmapx-buildenv

With all this installed, you should be able to build depthmapX in a shell (example from the docker build image)

root@d9ccf58f65ab:/code/depthmapX# mkdir build
root@d9ccf58f65ab:/code/depthmapX# cd build
root@d9ccf58f65ab:/code/depthmapX/build# /opt/qt57/bin/qmake -spec linux-g++ ..
root@d9ccf58f65ab:/code/depthmapX/build# make

If you want to use CLang for building depthmapX, use the respective build spec for qmake:

root@d9ccf58f65ab:/code/depthmapX/build# /opt/qt57/bin/qmake -spec linux-clang ..

Run the unit tests:

root@d9ccf58f65ab:/code/depthmapX/build# ./cliTest/cliTest && ./GuiUnitTest/GuiUnitTest && ./genlibTest/genlibTest && ./salaTest/salaTest

Check Regression Testing for running the regression tests.

Run the depthmapX executable (obviously not on docker as it needs an X server)

/home/sar/code/depthmapX/build$ ./GuiApp/depthmapX

Deployment

The build phase will generate the required executables (.exe, .app) for running depthmapX in the system it was built in, but to distribute them, the various QT libraries need to be bundled with them.

Windows

The build phase will create an executable (depthmapX.exe) in the GuiApp directory of the build folder. The automated process for bundling will bring all the libraries into the folder depthmapX.exe is located, so ideally it should first be moved somewhere else. Navigate to that directory with the windows command prompt and run:

<QT version directory>/bin/windeployqt depthmapX.exe

This should bring all the required libraries into the same folder. The whole folder is required to run depthmapX.

Note: If you have multiple QT versions installed make sure windeployqt uses the same version as the one used for building the executable (i.e. by making sure it is the only QT version on the path of your current command prompt - this particularly important if you have 32 bit and 64 bit QT installed, as it will look fine other wise but crash with a hard to understand 0xc000007b error when trying to run) More details can be found on the QT Windows deployment page

MacOS (Previously Mac OSX)

The build phase will create an app-bundle file (depthmapX.app) in the GuiApp directory of the build folder. Navigate to that directory with the terminal and run:

macdeployqt depthmapX.app

This should bring all the required libraries into the app-bundle.

Note: If you have multiple QT versions installed make sure macdeployqt uses the same version as the one used for building the app-bundle (i.e. by adding it to the PATH of the current terminal session)

More details can be found on the QT OSX deployment page