Cancer Imaging Phenomics Toolkit (CaPTk)  1.7.0
Build CaPTk from Source

Source code for the CaPTk graphical interface and applications is distributed for sites that wish to examine the code, collaborate with CBICA in future development, and for compatibility.

Contents


PRE-REQUISITES

Before building CaPTk, the following software libraries are required to be installed. Please note that to build in Windows, CMake needs to be used an appropriate compiler (Win64 version of Visual Studio is recommended). The selected solution platform is needed to match with dependent libraries.

Package

Version

Description

Archiver n/a gzip (http://www.gzip.org/) is recommended.
Windows Users: 7-zip (http://www.7-zip.org/)
C++ compiler n/a Visual Studio 2017, GCC/4.9.2, LLVM 6.0.1 are supported; C++11 compliant compiler is needed
CMake (http://www.cmake.org/) 3.10 or higher To configure the CaPTk compilation along with its dependencies.
Qt (http://qt-project.org/downloads) 5.10.x The main GUI interface for CaPTk. Download and install the precompiled library.
VTK (http://www.vtk.org/) 8.1.0 Install Qt before setting VTK up. Instructions to compile VTK are given at http://www.vtk.org/Wiki/VTK/Configure_and_Build. During CMake configuration, enable the VTK_USE_QT and VTK_USE_QVTK_QTOPENGL flags.
GCC Users: For compilation use the command make CXXFLAGS=-std=c++11.
OpenCV (http://opencv.org/downloads.html) 3.4 or higher All machine learning algorithms. This generally comes pre-compiled; if not found for your system, steps similar to those done for VTK and ITK compilation can be followed.
GCC Users: For compilation use the command make CXXFLAGS=-std=c++11.
ITK (http://www.itk.org/) 4.13 and above Build VTK before proceeding to compile ITK. Instructions to compile ITK are given at http://www.itk.org/Wiki/ITK/Configuring_and_Building. During CMake configuration, enable the Module_ITKVtkGlue, Module_ITKVideoBridgeOpenCV and VCL_INCLUDE_CXX_0X flags.
GCC Users: For compilation use the command make CXXFLAGS=-std=c++11.
Doxygen (http://www.stack.nl/~dimitri/doxygen/) 1.8+ [OPTIONAL] For documentation only.

Ensure all dependencies are met before proceeding.


BUILD

Please follow commands below in a shell/terminal (e.g., Bash (http://www.gnu.org/software/bash/)). They will configure and build CaPTk using GNU Make (http://www.gnu.org/software/make/). The main CMake configuration file (CMakeLists.txt) is located in the root directory of the package. Windows users need to follow the equivalent graphical interface.

Extract source files and create the build directory:

tar xzf CaPTk-${version}-source.tar.gz
mkdir CaPTk-${version}-build
cd CaPTk-${version}-build

Windows Users: an appropriate compression program (e.g., 7-zip (http://www.7-zip.org/)) might be used to extract the files.


RUN CMAKE TO CONFIGURE THE BUILD TREE

cmake ../CaPTk-${version}-source

Use the CMake variable CMAKE_INSTALL_PREFIX to specify the installation directory, as in:

cmake -DCMAKE_INSTALL_PREFIX=/opt/software/captk ../CaPTk-${version}-source

For GCC users, CaPTk needs the C++11 flag, so ensure that "-std=c++11" option gets added for CMAKE_CXX_FLAGS during the CMake configuration step. This should get done automatically by the CMakeLists.txt file provided but in case of custom build environments, it might get overwritten with other options.

Windows Users: open CMake-GUI and select CaPTk-${version}-source as the "source" directory and select CaPTk-${version}-build as the "build" directory. Click on "Configure" and select the appropriate C++ compiler. If there weren't any configuration errors, click "Generate".

CMake should be able to find the dependencies if they are specified in the $PATH variable in your environment. If you have custom installation directories, then ensure that they have been added to the $PATH variable or point the variable(s) ${Dependency}_DIR to the appropriate build paths where ${Dependency}Config.cmake is/are present (for example, in the case of ITK, point ITK_DIR to the directory where ITKConfig.cmake is present) - this should be either the build directory or the installation directory. If you are using a bash shell, it can be done using the following command:

cmake -DITKDIR=${path_to_custom_ITK_build_dir} -DVTK_DIR=${path_to_custom_VTK_build_dir} -DQT_QMAKE_EXECUTABLE=${path_to_custom_qt_installation} CaPTk-${version}-source

Windows Users: set the variables ITK_DIR, VTK_DIR and QT_QMAKE_EXECUTABLE using the CMake-GUI.

This step will generate compiler-specific project files (for example, Make file for GCC and Visual Studio solution file for MSVC). For a full list of generators, please see the CMake documentation on generators at https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html. CMake can be used to set various other configuration options and some of those options are:

BUILD_DOCUMENTATION Builds the documentation (HTML and PDF) from scratch
BUILD_TESTING Enables unit testing of the software package
CMAKE_INSTALL_PREFIX Path where the project will be installed
PACKAGE_PROJECT Create installer for project (not available for all platforms)

COMPILE THE PROJECT

make CXXFLAGS=-std=c++11 #this ensures c++11 flag is enabled for this build

Windows Users: you should launch the generated solution file of Visual Studio (by default, only Release version of the code will be compiled - if this needs to be changed, it can be done so by editing the variable CMAKE_CONFIGURATION_TYPE during the CMake configuration step), and then build solution.

Compiling LIBRA

Open MATLAB runtime and change the directory to CaPTk-${version}-source/src/applications/binaries/libra/Source within the main directory of the LIBRA package and run the following command in MATLAB environment:

libra_compile('CaPTk-${version}-source/src/applications/binaries/libra/') # In Unix

Windows Users: Use following command:

libra_compile('CaPTk-${version}-source\src\applications\binaries\libra\') # In Unix

[REQUIRED] Install

make install

Windows Users: you should build the INSTALL project.

Upon the success of the above compilation and build process, CaPTk is installed into the directory specified by the CMAKE_INSTALL_PREFIX, which was set during step 3.2 above.


[OPTIONAL]

  • Compile the documentation

To build the documentation from scratch, the BUILD_DOCUMENTATION option in the CMake configuration needs to be enabled.

make doc

Windows Users: the documentation is built automatically if BUILD_DOCUMENTATION is enabled.

  • Test the Compilation

To perform tests, the BUILD_TESTING option in the CMake configuration needs to be enabled.

make test

Windows Users: you should build the RUN_TESTS project.

In case of failing tests, re-run the tests, but this time by executing CTest (http://www.cmake.org/cmake/help/v2.8.8/ctest.html) directly with the '-V' option to enable verbose output and redirect the output to a text file, as in the example below (works for both Windows and Linux on the command line or shell):

ctest -V >& CaPTk-test.log

And send the file CaPTk-test.log as attachment of the issue report to softw.nosp@m.are@.nosp@m.cbica.nosp@m..upe.nosp@m.nn.ed.nosp@m.u.

  • Strip executables (Linux only)
make install/strip

Note - this is not needed if you plan to package the project.

  • Package Project

Enable the PACKAGE_PROJECT flag in the CMake configuration step to package the project.

make package
sudo dpkg -i CaPTk-Linux.deb

Windows Users: Build the PACKAGE project in Visual Studio; you will need NSIS (http://nsis.sourceforge.net/Main_Page) to package the project as an installer.


Linux Build Guide

Note: Make sure you have Qt 5.10.0 installed and in your PATH. You can download the open source version installer for free from the Qt website.

The Linux installer is an automated build script that takes care of the entirety of going from source code to a packaged binary that can be run anywhere.

Firstly, locate the build script within the scripts folder of the CaPTk root directory. The linux installation script is called captk-pkg.

Open up a terminal window in the scripts directory, and mark the script as executable with the following command:

chmod +x ./captk-pkg

After this, run the script in the terminal from the CaPTk root with the following commands:

The first will navigate you up one directory to the root, and the second will run the script.

cd ../
./scripts/captk-pkg

The installation script takes care of the whole build and deployment process. You may notice some issues if the ITK-build directory from the dependency manager isn't found or not in the PATH variable. To fix this, simply pass it in to the script via:

./captk-pkg --itk=/path/to/itk

This will generate an CaPTk.bin file in the root of CaPTk. Feel free to move this file anywhere and run it. You can run this from the commandline as such:

./CaPTk.bin