Compiling SimVascular using CMake


This guide gives an overview of compiling SimVascular using CMake. We also support standard MakeFiles.


System Requirements

Windows Apple OS X Linux
Tested Configurations:
  • Windows 10
  • C++ compilers
Supported Compilers:
  • Visual Studio 2013 Community Edition
    (version 12.0 update 5 for x64)
  • Visual Studio 2013 Professional
    (version 12.0 update 5 for x64)
Tested Configurations:
  • Version 10.10.5 (OS X Yosemite)
    with XCode 7.2.1 (command line tools installed)
  • Version 10.12.1 (macOS Sierra)
    with XCode 8.2.1 (command line tools installed)
Supported Compilers:
  • Apple LLVM version 7.0.2 (clang-700.1.81)
  • Apple LLVM version 8.0.0 (clang-800.0.42.1)
Tested Configurations:
  • Ubuntu 14.04 64-bit desktop
  • Ubuntu 16.04 64-bit desktop
Supported Compilers:
  • gcc/g++ 4.8.5
  • gcc/g++ 5.4.0

On linux, use gcc --version to see which compiler you are using. On mac, use clang --version to see which compiler you are using.

Required Libraries

Windows

You need to install:

Apple OS X

You need to install:

  • CMake, Visit cmake.org for details.
  • XCode (make sure the version of XCode is the right version for your OS).
  • The XCode command line tools need to be installed. This can done with this command:

    xcode-select --install
  • Qt developer package downloadable here.

Linux

You will need the following packages, available from the APT repository:

sudo apt-get install cmake
sudo apt-get install cmake-curses-gui
sudo apt-get install cmake-gui

Qt developer package downloadable here.

Steps for compiling

Building SimVascular can be thought of as building two separate projects:

  • SimVascular’s externals
  • SimVascular itself
  • ... SimVascularSrc
    --- CMakeLists.txt: 
      Highest level CMake file that contains very little. Simply builds the Externals project and then the SimVascular project. Should be the entrance location for anyone familiarizing themselves with SimVascular.
    --- ... Externals
      --- CMakeLists.txt:
        Main CMake file for Externals. Very involved and contains options to use different versions of the externals, to build or download certain externals, etc. Many of these options are not available using the highest level CMake file, so if fine tuning of the Externals is desired, this is the spot to be.
    --- ... Code
      --- CMakeLists.txt:
        Main CMake file for SimVascular. Very involved and contains options for building/not building certain libraries, shared/static libraries, etc. Many of these options are also not available using the highest level CMake file, so if fine tuning of the SimVascular build is desirec, this is the spot to be.
    --- ... Remaining Src

    Building it all

    This is the easiest and most basic way to build SimVascular. If using a supported operating system and compiler, this is likely to work.

    Follow the setup instructions for Mac, Linux, or Windows.

    Use git to clone the SimVascular source:

    git clone https://github.com/SimVascular/SimVascular.git SimVascularSrc

    Or fork the project on github, and then clone the forked repository:

    git clone https://github.com/githubusername/SimVascular.git SimVascularSrc

    CMake command line

    If you use cmake on the command line (you must install cmake command line tools), enter the source and setup the project:

    cd SimVascularSrc
    mkdir Build
    cd Build
    ccmake ..

    Configure the project with ‘c’. CMake will run and then error because it needs Qt. Point it to the location of the Qt5Config.cmake file:

    <img src="documentation/compile/imgs/cmakecommandfindqt.png" alt="...">

    Reconfigure the project with ‘c’ until you can generate make files with ‘g’.

    If you have no errors, generate the make files with ‘g’.

    Proceed to building the project.

    CMake GUI

    If you use the cmake GUI, start the GUI and point to the source directory and a new build directory. You can choose a non-existent build directory, cmake will generate it for you.

    ...

    Configure the project with ‘c’. Unless you want to specify custom compilers, use the default compilers. CMake will run and then error because it needs Qt. Point it to the location of the Qt5Config.cmake file:

    ...

    Configure the project again and if Qt is found succesfully, Qt variables will show up in the GUI. Configure one more time, and then the ‘Generate’ button should be clickable. Generate the build files with Generate and exit the CMake GUI.

    Proceed to building the project.

    Toplevel SimVascular Variables

    Most likely, all these variables should be fine and they should not be changed. These variables indicate what version of the pre-built binaries to download from the simvascular server. You can navigate and see the available pre-buit binaries here.The toplevel variables you can edit correspond to the directory structure.

    $SV_PLATFORM_DIR -> Platform being used (mac_osx, ubuntu, windows)
    $SV_PLATFORM_VERSION_DIR -> Platform version #
    $SV_COMPILER_DIR -> Compiler being used
    $SV_COMPILER_VERSION_DIR -> Compiler version #
    $SV_ARCH_DIR -> Architecture (x32, x64)
    $SV_BUILD_TYPE_DIR -> Compile type (Release, Debug, RelWithDebInfo, MinSizeRel)

    Note that changing these variables will only change the versions of the pre-built binaries downloaded. They will not change your physical configuration settings! For example, to actually change the compiler being used, the CMAKECXXCOMPILER variable should be changed.

    Build the project

    Navigate to the cmake build directory where you just generated the makefiles.

    cd /Users/username/Documents/Software/SimVascularSrc/Build
    make

    If the build immediately errors, the system you are using is most likely not supported.

    If you see warnings, please read them. It may be the case that your system does not have pre-built binaries of the externals. In which case, a default version of the pre-built externals will be download; however, it could cause errors when finally building the SimVascular project.

    The build will proceed in two steps:

    1. The externals will first be downloaded and then SimVascular will be automatically configured to build with these pre-built downloaded externals. If the build errors during the download of the externals, see the section about the Externals.
    2. The SimVascular project itself will be built second. If the build errors during the actual build of SimVascular, see the section about building standalone SimVascular.

    If the build did not error, navigate to the SimVascular build directory and launch the project!

    cd SimVascular-build
    ./mysim -qt

    SimVascular’s Externals

    SimVascular depends directly on 9 major open source libraries:

    1. Tcl/Tk
    2. Python
    3. FreeType
    4. GDCM
    5. ITK
    6. VTK
    7. MMG
    8. OpenCASCADE
    9. MITK

    Building all of these dependencies can take quite a while; thus, pre-built binaries are provided for the supported operating systems.

    If you want to build all of SimVascular, this information is likely unnecessary and go to building it all.

    Downloading SimVascular’s Externals

    To download the most basic version of the externals, navigate to the externals, create a build directory, and configure:

    cd SimVascularSrc/Externals
    mkdir Build
    cd Build
    ccmake ..

    By default, all externals should be set to be downloaded. To turn on and off certain externals, toggle the SVEXTERNALSENABLE‘External’ variables.

    Building SimVascular’s Externals

    If using pre-built binaries isn’t working for your system, you may need to build your own externals.

    To do this, toggle off the SVEXTERNALSDOWNLOAD‘External’ variables.

    Building of externals has only been tested on the supported platforms, so there may be difficulties that arrise on other platforms

    Note that on Mac you will need to obtain MacPorts with additional libraries, while on linux, additional packages will likely have to be installed with the package manager.

    The source versions of the externals are available through github and on SimVascular’s server.

    Building Standalone SimVascular

    If you choose to build SimVascular by itself, you will have to make sure you have all of SimVascular’s dependencies. If you are using your own versions of some of the externals like ITK, VTK, Python, Tcl, MITK, etc., be very careful. A VTK not built with the same version of Python, or an MITK not built with the corresponding versions of ITK, VTK, and Python can cause significant build issues. In addition, different versions of the externals have varying nuances that could cause both build problems and performance problems. This is why the suggested way to build is with the pre-built externals if possible. If not, the next best solution is to build the externals with the default versions of the externals.

    If proceeding, create a build directory and configure the project

    cd SimVascularSrc/Code
    mkdir Build
    cd Build
    ccmake ..

    You should come across a series of errors in which you need to specify the location of the externals package. For most externals, the location of the Config.cmake file needs to be specified; however, for TCL, PYTHON, MMG, and FREETYPE, the location of the toplevel directory needs to be specified.

    Examples of configuration setting can be found in the SimVascular source.

    Running SimVascular

    To run SimVascular and other executables you need to run the startup script which will set up the environmnet variables and start the executable. These scripts should be run from the top level of the build directory:

    Executable Linux/OSX Script Windows Script
    SimVascular mysim mysim.bat

    Additional Notes

    Linux: Multiple Compilers

    Some versions of the needed software do not compile correctly using certain versions of gcc/g++. We use gcc-4.6 to compile many of the external libraries. It is easy to obtain gcc-4.6 without overwriting your current version using update-alternatives. Below is an example of how to install both gcc-4.6 and gcc-4.8 on a ubuntu system.

    apt-get install c++-4.6 c++-4.8
    
    update-alternatives --remove-all gcc
    update-alternatives --remove-all g++
    
    update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.6 10
    update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 20
    
    update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.6 10
    update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.8 20
    
    update-alternatives --install /usr/bin/cc cc /usr/bin/gcc 30
    update-alternatives --set cc /usr/bin/gcc
    
    update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++ 30
    update-alternatives --set c++ /usr/bin/g++
    
    update-alternatives --config gcc
    update-alternatives --config g++