NifTK  16.4.1 - 0798f20
CMIC's Translational Medical Imaging Platform
Build Instructions

Are you really a NifTK developer?

If you just want to use NifTK, and don't plan on extending it, and don't need up to the minute code changes, then you can just use the binary packages that can be download from the following address from within UCL network:

If you are keen to build your own then read on.

The super-build process

NifTK and most of its dependencies are built using CMake, through a single process called 'super-build'. However, the super-build can't be expected to do absolutely everything. The number of combinations of how a machine is setup would be overwhelming. So, the super-build assumes that Qt, Doxygen, Git and certain system libraries are in place. In effect the super-build is really taking care of the application specific libraries, not the necessary system libraries.

The application specific dependencies (Boost, VTK, ITK etc.) are automatically downloaded from:

http://cmic.cs.ucl.ac.uk/platform/dependencies

which can be accessed on the CS Unix filesystem here:

/cs/sys/www0/marine/html/cmic.cs.ucl.ac.uk/platform/dependencies

The directory is mounted on the CS managed Linux machines and e.g. jet.cs.ucl.ac.uk.

In principal, the super-build concept is identical on Linux, Windows and Mac, and it considerably simplifies the build process. The steps are summarised below, with screenshots from a Mac.

1. Before You Get Started - Known Caveats

2. Installing CMake

Minimum required version is CMake 3.2.0. NifTK is currently regularly tested with CMake 3.3.2.

Pre-compiled binaries of CMake are available for Windows, Linux and Mac. You can safely choose the 32bit version on a 64bit Windows.

http://www.cmake.org

Please install the downloaded binary distribution to a convenient location and make sure to add the bin folder to your system PATH (e.g. "c:\Program Files\CMake_3.3.2\bin" or "/opt/cmake-3.3.2/bin").

3. Installing Qt

We recommend to compile Qt from sources. Supported Qt versions are Qt 4.8-5.4. From Qt 4.8 you need the latest release (4.8.7). Qt 5.5 is not supported. The source code is available here:

https://download.qt.io/official_releases/qt

On Linux and Mac, you need the 'tar.gz' version (e.g. qt-everywhere-opensource-src-5.4.2.tar.gz), on Windows you need the 'zip' (e.g. qt-everywhere-opensource-src-5.4.2.zip).

The sources can also be obtained from the Qt git repository using this command for Qt 4:

git clone git://code.qt.io/qt/qt.git

or these commands for Qt 5:

git clone git://code.qt.io/qt/qt5.git
cd qt5
git checkout 5.4
perl init-repository

3.1 Compiling Qt on Windows

On Windows follow the instructions below to build Qt:

First of all, on Windows only the Visual Studio builds are currently supported (no mingw or msys), so you'll need to have Microsoft Visual Studio installed (2012 Professional (or better) and 2013 Community (or better) version is recommended). Note that if you use Microsoft Visual Studio 2012 please install Update4.

You might also want to have the Qt integration pack installed for VS: Qt VS Integration

3.1.1 Compiling Qt 5.4.2 on Windows

Download the Qt 5.4.2 binaries with open_gl located here http://download.qt.io/archive/qt/5.4/5.4.2/qt-opensource-windows-x86-msvc2013_64_opengl-5.4.2.exe. Binaries for 64-bit version of Qt 5.4.2 with Visual Studio 2012 are not available.

3.1.2 Compiling Qt 4.8.7 on Windows

If you the 64-bit version of Qt 4.8.7 (or if you are an adventurous Win32 user) you have to build Qt from source.

Uncompress the downloaded files obtained in the previous section into a build directory of your choice (e. g. "C:\Qt\4.8.7-build"), and create a directory where you want Qt installed (e.g. "C:\Qt\4.8.7").

Note: The install path must not contain any spaces or Windows specific file system characters.

To configure Qt a Windows version of Perl will be required. Get the installer from here: StrawberryPerl. Install the package and make sure that the "bin" folders of Perl are added to your system path.

On Windows you'll have to install OpenSSL before attempting to build Qt (OpenSSL is required for the XNAT functionality). Please download the installer from here: Win OpenSSL.

Install the package somewhere, but make sure that the install path must not contain any spaces or Windows specific file system characters (e.g. c:-Win64).

If you need symbols (to be able to debug a crashed release-build, for example, or to performance-profile your code), you'll need to hack mkspec: You need to edit 

qtsrc/mkspecs/win32-msvc2012/qmake.conf

Add to QMAKE_CFLAGS_RELEASE the -Zi flag, and to QMAKE_LFLAGS_RELEASE the /debug flag. For example: 

...
QMAKE_CFLAGS_RELEASE = -O2 -MD -Zi
...
QMAKE_LFLAGS_RELEASE = /INCREMENTAL:NO /DEBUG /OPT:REF
...

The compilation is done from the Visual Studio command prompt. On 64bit Windows make sure that you use the "Visual Studio x64 Win64 Command Prompt"!

To open the command prompt launch:

where XXXX is the Visual Studio version you'd like to use.

The next step is to configure Qt for the build: 

cd /D C:\Qt\4.8.7-build
configure -no-dbus -no-phonon -no-phonon-backend -no-accessibility -no-sql-mysql -no-sql-psql -no-sql-oci -no-sql-odbc -no-sql-tds -no-sql-db2 -no-sql-sqlite2 -no-sql-ibase -no-qt3support -nomake examples -nomake tests -debug-and-release -shared -mp -script -openssl -opensource -confirm-license -platform win32-msvc2012 -prefix c:\Qt\4.8.7 -I c:\OpenSSL-Win64\include -L c:\OpenSSL-Win64\lib

The last four parameters have to be adjusted. Set "-platform win32-msvcXXXX" to match the desired Visual Studio version (e.g. -platform win32-msvc2013 or -platform win32-msvc2012). Note when you use x64 command prompt Qt is compiled to x64, despite the "win32" parameter setting.

Also, you'll need to specify the installation prefix to specify where to install Qt (e.g. "c:\Qt\4.8.7").

The -I and -L parameters are to specify additional include paths and library paths, respectively. Please edit these to point to your installation of OpenSSL, so qmake can find them.

If you later need to reconfigure and rebuild Qt from the same location, ensure that all traces of the previous configuration are removed by entering the build directory and typing "nmake distclean" before running configure again.

The next step is to compile and build Qt, so type: 

nmake

The build process can easily take more an hour. After it's finished type: 

nmake install
nmake clean

This will remove all the temporary files used during build-time.

The last step is to add the bin directory to your system path. For newer versions of Windows, PATH can be extended through the Control Panel|System|Advanced|Environment variables menu. Look for 'PATH' and add "c:\Qt\4.8.7\bin;" to the FRONT of the path string.

You'll have to log off / log on for the changes to make effect.

3.2 Compile Qt on Linux

Use the following commands to extract the Qt tarball and to compile and install Qt 4.8.7:

tar xvfz qt-everywhere-opensource-src-4.8.7.tar.gz
cd qt-everywhere-opensource-src-4.8.7
./configure -prefix /opt/qt-4.8.7 -opensource -confirm-license -release -shared -script -openssl -no-phonon -no-phonon-backend -nomake examples -nomake demos -nomake tests
make
sudo make install

With Qt 5.4.2 (in general 5.X.X) you can use the following commands:

tar xvfz qt-everywhere-opensource-src-5.4.2.tar.gz
cd qt-everywhere-opensource-src-5.4.2
./configure -prefix /opt/qt-5.4.2 --opensource -confirm-license -release -shared -openssl -nomake examples -nomake tests -no-gtkstyle
make
sudo make install

Then set your PATH variable to contain the /opt/qt-4.8.7/bin (or /opt/qt-5.4.2/bin ) directory where the binaries were just installed.

3.3 Compiling Qt on Mac

Use the following commands to extract the Qt tarball and to compile and install Qt 4.8.7:

tar xvfz qt-everywhere-opensource-src-4.8.7.tar.gz
cd qt-everywhere-opensource-src-4.8.7
./configure -prefix /opt/qt-4.8.7 -opensource -confirm-license -release -shared -script -openssl -no-phonon -no-phonon-backend -nomake examples -nomake demos -nomake tests
make
sudo make install

With Qt 5.4.2 (in general 5.X.X) you can use the following commands:

tar xvfz qt-everywhere-opensource-src-5.4.2.tar.gz
cd qt-everywhere-opensource-src-5.4.2
./configure -prefix /opt/qt-5.4.2 --opensource -confirm-license -release -shared -openssl -nomake examples -nomake tests
make
sudo make install

This will build with clang and libc++. Again, set the PATH to contain the installed bin folder.

If you use El Capitan, you need to use the Yosemite system environment to build Qt. You can specify this with the '-sysroot' option:

./configure -prefix /opt/qt-4.8.7 -sysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk -opensource -confirm-license -release -shared -script -openssl -no-phonon -no-phonon-backend -nomake examples -nomake demos -nomake tests

Similary, with Qt 5.4.2 you would use:

./configure -prefix /opt/qt-5.4.2 -sysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk --opensource -confirm-license -release -shared -openssl -nomake examples -nomake tests

4. Version Control

You also need an up-to-date git client.

5. Doxygen

In order to compile the documentation you will need to have Doxygen installed. Please download Doxygen for your platform from this site.

The prefered version is 1.8.10.

6 NSIS (Windows Only)

If you would like to have an "official" NifTK installation (that appears under Programs, can be uninstalled, have icons and shortcuts and so on) you will have to create an installer.

On Windows we use NSIS for this task, which can be downloaded from here.

Please install NSIS and make sure that it is added to your system path. For further instructions about the installation please refer to Section 11.

7. Downloading the source code

You need an account on CMICLab to access the source. Download the source code through either https

git clone https://cmiclab.cs.ucl.ac.uk/CMIC/NifTK.git

or ssh

git clone git@cmiclab.cs.ucl.ac.uk:CMIC/NifTK

For authentication through https you can put your credentials in a file called '_netrc' (Windows) or '.netrc' (Linux and Mac) in your home directory, so that you do not need to type in your password over and over again. The file should have the following format:

machine  cmiclab.cs.ucl.ac.uk
login    <your CMICLab user name, not the e-mail address>
password <your CMICLab password>

For authentication through ssh you need to add your ssh public key to your account on CMICLab.

8. Configuring NifTK

You can use either 'cmake-gui' or 'ccmake' to configure the NifTK build. ccmake is available on Linux and Mac only. Below you can find screenshots about using the CMake GUI on Mac.

  1. Using CMake, select the source and a different build directory

    niftk-build-snapshot1.png
    Figure 1. Select the source folder, and a different build folder.
  2. Press configure.

  3. Select the right type of generated files. On Linux/Mac, you chose Makefiles, on Windows you choose the version of Visual Studio.

    niftk-build-snapshot2.png
    Figure 2. Select the correct generator.
  4. If you want a GUI, turn on variables NIFTK_Apps/<whatever>
  5. Set the CMAKE_BUILD_TYPE. Select either Release or Debug.
  6. Set the CMAKE_INSTALL_PREFIX. In general, this is not widely used. This is because developers just run all applications from their build folder. To distribute we use "make package" which creates an installer, which is then installed to a given folder. However, if you want to run "make install", set this variable.
  7. If you want CUDA, turn on NIFTK_USE_CUDA. This is an advanced option.

  8. Similar to the Qt build, on Mac OS X El Capitan (10.11), you have to use the system libraries for Yosemite. You must be consistent throughout the whole build. For this, specify these variables: 

          CMAKE_OSX_SYSROOT:           "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk"
      CMAKE_OSX_DEPLOYMENT_TARGET: "10.10"
      CMAKE_OSX_ARCHITECTURES:     "x86_64"

    You can pass these options to the cmake or ccmake commands in the command line like this:

          ccmake -DCMAKE_OSX_SYSROOT="/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk" -DCMAKE_OSX_DEPLOYMENT_TARGET="10.10" -DCMAKE_OSX_ARCHITECTURES="x86_64" ../NifTK

  9. Select which options you want building. These variables start with BUILD_

    niftk-build-snapshot3.png
    Figure 3. Select the build options.
  10. Press configure repeatedly, setting variables as appropriate until the generate option is available.
  11. Press the generate button to generate the make files.

If you prefer 'ccmake' with a command line user interface, create a new directory for the build, step into it, and run 'ccmake <path to="" the="" niftk="" sources>="">'. If you need to reconfigure the project later, next time it is enough to run 'ccmake .' in the build directory.

9. Compiling NifTK

9.1. Compiling NifTK on Windows

Open the Visual Studio .sln file in the build directory (NifTK-SuperBuildRelease in this example), and execute the BUILD task. Note that Visual Studio defaults to a Debug build, so if you wish to build a Release version you'll have to manually change the build configuration to Release, regardless what was set in CMake. Once successfully completed, exit Visual Studio.

The repeated cycle of code, compile, test should be done within the subdirectory called NifTK-build, where you should use the batch file startNiftyView_Debug.bat or startNiftyView_Release.bat to launch Visual Studio, and the BUILD task. Please ALWAYS use these bat files to start VS! NiftyView can be run directly within Visual Studio by setting it as the startup project.

9.2. Compiling NifTK on Linux and Mac

At the command prompt, in the build directory

make

will perform an initial build of all the external dependencies, and also NifTK. Then the repeated cycle of code, compile, test should be done within the project build directory called NifTK-build.

cd NifTK-build
make

To make the compilation faster, it is recommended to use the '-j' flag to specify parallel compilation with several threads. For example,

make -j8

9.2. Compiling NifTK on Linux and Mac

At the command prompt, in the project build directory (NifTK-build) run the following command:

ctest

See CMake documentation about more options, e.g. running the tests in parallel or running a specific test.

11. Installing NifTK

A developer can run all the applications from the build directory. Indeed, the test-code-compile-test cycle will mean that the developer is constantly running the compiled output, either through a development environment such as Eclipse, Qt Creator, or Visual Studio or via the command line. However, the developer may also wish to install the code to some installation folder for safe keeping. During the initial configuration, the CMAKE_INSTALL_PREFIX is set to be the installation folder. The software can be "installed" by typing

make install

for Linux/Mac.

On Windows, you can run the INSTALL task of the NifTK project (not the super-build) in Visual Studio, which will copy the files to the destination directory (defined by CMAKE_INSTALL_PREFIX). Please double check if you have write permissions to the installation folder.

If you have NSIS installed (and added to the system path) you can run the PACKAGE task of the NifTK project (not the Superbuild) in Visual Studio. This task will run CPack on NifTK, which will generate an NSIS script, which will get eventually processed by NSIS to generate an executable NifTK installer bundle. This executable will be placed within the NifTK-build subfolder, once the PACKAGE task finished you can run it to install NifTK onto your system (will appear in Start Menu, can be uninstalled, etc).

12. Trouble shooting

Generated on Thu Aug 4 2016 06:02:56 for NifTK by   doxygen 1.8.8