View source for Documentation/BuildSystem Description

= Overview =

CTK is a toolkit composed of three different kinds of modules:
* Libraries
* Plugins 
* Applications

Based on set of custom CMake macros and functions, CTK buildsystem allows to make the developer easier and increase its productivity.

Each one of these modules may have specific dependencies (like VTK, Log4Qt, QtMobility, ... ). CTK buildsystem provides the ability to checkout and build these external projects only if required. 
Note also that in some case, the developer want to use a local build of a given external project, this is also possible specifying the proper variable when CMake is invoked.

In addition to external projects, libraries, applications and plugins may also have inter dependencies.

= Specifying dependencies =

Based on Superbuild, CTK is build in two steps:
* 1) Checkout and build external dependencies 
* 2) Build CTK itself using the external dependencies build at step 1

In order to checkout the expected external project, the developer need to specify which module he wants to build at "configuration time" before even executing step1.
Moreover, if application X is enabled, all dependent plugins, libraries, etc .. need to be enabled.

It means, dependencies of a given CTK module need to be done at time of step 1. To achieve that, dependencies of each module are specified within a file named ''target_libraries.cmake''.

For example, the content of file CTK/Libs/Visualization/VTK/Core/target_libraries.cmake is the following:
<pre>
#
# See CMake/ctkMacroGetTargetLibraries.cmake
# 
# This file should list the libraries required to build the current CTK libraries
#

SET(target_libraries
  VTK_LIBRARIES
  CTKCore
  )
</pre>

In this example, the library CTKVisualizationVTKCore depends on CTKCore and the also external project VTK_LIBRARIES. 

On the other hand, the file allowing to specify VTK external project (CTK/CMakeExtermals/VTK.cmake) look like:
<pre>
#
# VTK
#
SET (VTK_DEPENDS)
ctkMacroShouldAddExternalProject(VTK_LIBRARIES add_project)
IF(${add_project})
  # Sanity checks
  IF(DEFINED VTK_DIR AND NOT EXISTS ${VTK_DIR})
    MESSAGE(FATAL_ERROR "VTK_DIR variable is defined but corresponds to non-existing directory")
  ENDIF()

  SET(VTK_enabling_variable VTK_LIBRARIES)
  
  SET(additional_vtk_cmakevars )
  IF(MINGW)
    SET(additional_vtk_cmakevars "-DCMAKE_USE_PTHREADS:BOOL=OFF")
  ENDIF()

  SET(proj VTK)
  SET(proj_DEPENDENCIES)
  
  SET(VTK_DEPENDS ${proj})
  
  IF(NOT DEFINED VTK_DIR)
#     MESSAGE(STATUS "Adding project:${proj}")
    ExternalProject_Add(${proj}
      GIT_REPOSITORY ${git_protocol}://vtk.org/VTK.git
      GIT_TAG "origin/master"
      INSTALL_COMMAND ""
      CMAKE_GENERATOR ${gen}
      CMAKE_ARGS
        ${ep_common_args}
        ${additional_vtk_cmakevars}
        -DVTK_WRAP_TCL:BOOL=OFF
        -DVTK_WRAP_PYTHON:BOOL=OFF
        -DVTK_WRAP_JAVA:BOOL=OFF
        -DBUILD_SHARED_LIBS:BOOL=ON 
        -DDESIRED_QT_VERSION:STRING=4
        -DVTK_USE_GUISUPPORT:BOOL=ON
        -DVTK_USE_QVTK_QTOPENGL:BOOL=ON
        -DVTK_USE_QT:BOOL=ON
        -DQT_QMAKE_EXECUTABLE:FILEPATH=${QT_QMAKE_EXECUTABLE}
      DEPENDS
        ${proj_DEPENDENCIES}
      )
    SET(VTK_DIR ${ep_build_dir}/${proj})
    
    # Since the link directories associated with VTK is used, it makes sens to 
    # update CTK_EXTERNAL_LIBRARY_DIRS with its associated library output directory
    LIST(APPEND CTK_EXTERNAL_LIBRARY_DIRS ${VTK_DIR}/bin)
    
  ELSE()
    ctkMacroEmptyExternalProject(${proj} "${proj_DEPENDENCIES}")
  ENDIF()

  SET(${VTK_enabling_variable}_INCLUDE_DIRS VTK_INCLUDE_DIRS)
  SET(${VTK_enabling_variable}_FIND_PACKAGE_CMD VTK)
ENDIF()
</pre>

= Enabling and building dependencies =

Before performing step1, the target_libraries.cmake file associated with each module is read. 
Then, the dependency graph is validated. If not error occured, the dependent modules and external projects are enabled.

The dependency graph is validated using a small tool named DGraph. This executable is a lightweight application also built by CTK buildsystem.

The DGraph tool helps also to:
- obtain the topological order of the different module. This is later used by the dashboard driver script to build, test, compute coverage of each module in the correct order.
- generate the project.xml file used to tell CDash what is the dependency graph.