ParaView/Superbuild

Introduction

This page describes how to build ParaView binaries along with most, if not all, of the external dependencies that ParaView needs to generate a full featured build of ParaView.

We use CMake External Projects to provide users/developers with a uber cmake project that can build ParaView and its dependencies and hence we refer to it as the ParaView Superbuild. For instructions on building ParaView itself, providing installed or prebuilt versions of the dependencies, refer to ParaView:Build And Install instructions.

The process described here can be used to generate redistributable binaries and is indeed the process we use to generate binaries available for download from ParaView download page. Although, the user can control some of the feature set, advanced capabilities are not exposed requiring users to dig into the cmake files to change esoteric configuration parameters. We summarize the structure of the cmake files at the end of this document. These can be easily customized to adapt for building extra dependencies or plugins or custom applications.

Prerequisites

• ParaView-Superbuild requires CMake, version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (8 or later). Follow these instructions to download and install cmake. This document assumes familiarity with using CMake and your platform specific build tools.
• A working Git installation to checkout the source.

Obtaining the source

ParaView-Superbuild is available as separate Git repository. Simply clone the ParaViewSuperbuild.git repo. One may browse the repositories online using the Gitweb interface at http://paraview.org/gitweb.

Repository	Purpose	Access	URL
ParaViewSuperbuild.git	ParaView Super-Build	fetch (git)	git://paraview.org/ParaViewSuperbuild.git
		fetch (http)	http://paraview.org/ParaViewSuperbuild.git
		push (ssh)	git@paraview.org:ParaViewSuperbuild.git

This repository is tested nightly on the ParaView Dashboards under the Super-Build subsection. The generated binaries are uploaded to CDash as well and can be used as nightly builds for ParaView.

To clone the git repository, for the very first time:

 > git clone git://paraview.org/ParaViewSuperbuild.git
        OR
 > git clone http://paraview.org/ParaViewSuperbuild.git

Refer to a git Manual or any online git tutorial for details on how to obtain latest updates.

Configure With CMake

Create a separate build directory wherein we will configure and build. Refer to ParaView Build Instructions for an overview of using CMake to configure projects. On configure, CMake will present users with options that control how the project is built. The general concept is that for every component that the ParaViewSuperbuild can build it provides an ENABLE_<component> option. If you want that component in the generated binaries, enable that option. If you turn on a component, all components that it depends on will automatically be turned on e.g. if you turn on ENABLE_numpy, since numpy needs Python, ENABLE_python will be forced ON (and hidden so that users can't turn it OFF). ParaView itself is offered and component controlled by the flag ENABLE_paraview.

Certain components, when enabled, offer additional options. One of these additional option is USE_SYSTEM_<component>. For example, when ENABLE_mpi is ON, users are presented with USE_SYSTEM_mpi option. Turn this ON if you don't want ParaViewSuperbuild to build MPI and use an existing installation of MPI instead. Typically, if USE_SYSTEM_<component> is turned ON, CMake may offer additional variables that help CMake locate the component on the system, e.g. for MPI, we need the path to the mpiexec executable.

Useful CMake Options

download_location : PATH

When one starts building, ParaViewSuperbuild downloads the source tar-balls for all enabled projects using the URL mentioned in the versions.cmake file. These tar-balls are downloaded at this location. If an appropriate tar-ball is already present in this location, then it will not be re-downloaded. Set this path to location where you have pre-downloaded all the needed source tar balls, if any.

qt_DISABLE_WEBKIT : BOOL

Off by default (available when ENABLE_qt is ON and USE_SYSTEM_qt is OFF). Turn this On if you are having trouble with Qt builds due to WebKit. This will drop the WebKit support from Qt and ParaView. It implies that the generated ParaView application will not support inline documentation (available when users hit F1).

CMAKE_INSTALL_PREFIX : PATH

This is the path where the project will be installed on "make install". If you are planning to build a redistributable package (tar-ball, zip, DMG, or Windows installer), this need not be changed/set.

Building

Once you're done configuring and generating the CMake project, simply build the project using the platform/generator specific build command. Refer to ParaView Build Instructions to get an overview of what that typically entails. As the project builds, it will download all needed source files for each of the enabled components and then build them.

Generating a Redistributable Package

To generate a package that you can distribute, use cpack (included in CMake installation as follows) in the build directory

 > cpack -G <Generator>

Try "cpack --help" for a list of available. Typically, the generator can be TGZ on Linux, ZIP or NSIS on Windows, and DragAndDrop on OsX.

Note that if you're planning to build a redistributable package, don't turn on USE_SYSTEM_* for any of the components. Let ParaViewSuperbuild build all the necessary components so that they will get packaged.

Installing

Instead of generating a package, you can also install for use on the local machine at the install location defined by CMAKE_INSTALL_PREFIX. Use "make install" or "ninja install" as appropriate for the buildsystem you choose.

Platform-specific Notes

Linux

Notes for Package Maintainers for Linux Distributions

[place holder for notes on how to use superbuild for generating packages for common distributions]

Windows

1. Use Visual Studio 2008 (VS9) especially when building with Python enabled and not using system Python. For any other version, you will have to edit ParaViewSuperbuild/Projects/win32/python.cmake.
2. It's recommended to use CMake 2.8.9+ and use Ninja generator. Always launch CMake/Ninja from within the appropriate Visual Studio shell.
3. Ensure that your build directory is not deeply nested. Windows has characters limit on command lines and during the long build process, its possible to run out of the limit. So root your build directory fairly lower e.g. C:/pvs-x64.
4. Ensure that your source and build directories are on the same drive.
5. If you run into weird build/runtime issues, clean your your PATH environment variable.
6. Since building Qt is a time consuming task on most Windows machines, ParaViewSuperbuild supports using external Qt and packaging the Qt (release) dlls (controlled by the CMake option PACKAGE_SYSTEM_QT).

Mac Os X

1. ParaView Super-Build has only been tested for x86_64 architecture using 10.6 (Snow Leopard) SDK.
2. Ensure that you set CMAKE_OSX_ARCHITECTURES, CMAKE_OSX_DEPLOYMENT_TARGET, CMAKE_OSX_SYSROOT correctly to ensure that the binaries generated build on your target platform. Refer to ParaView Binaries Build Information for details of the compiler we use for our binaries.
3. Although, ParaView can build custom Python, one is better off using the system Python python extensions that the user installs on his machine are available to ParaView. Hence ParaViewSuperbuild/Projects/apple/python.cmake forces use of system Python. You need to ensure that the you pick the right version of Python for your deployment target.
4. Qt 4.8.2 is affected by a bug when using Xcode 4.3 or later. The ParaView Super-Build indeed patches the code before building to overcome the issue.
5. Qt 4.8.2 is affected by a bug when building for target 10.5. Fixing this is not handled by the Super-Build currently and hence 10.5 builds are not directly supported at this time.

Developer Notes

This section describes the under-pinnings of the cmake files that build ParaView and its dependencies. You should read this section if you are planning on adding support for new components to be included in your superbuild or, customize/adapt the scripts for your custom applications.

Design Overview

ParaView Super-Build is used to build and package multiple projects. The general strategy is that we build sub-projects, including ParaView, and install the sub-project using its install rules under a specific root directory. By passing CMAKE_PREFIX_PATH to point to this root, we rely on sub-projects finding each other as needed. Once all sub-projects are built and installed in this internal root directory, we run a cmake script that generates the redistributable package. This script tends to be highly customized for the platform and the application since it is expected to leverage all the knowledge about files that need to go into the package and where should they be placed.

For every sub-project, there exists a <project-name>.cmake file. This file includes a call to add_external_project(...) which defines the rules to build/install the subproject as well an lists any other sub-projects it depends on. For every subproject added, the user is presented with a ENABLE_<project-name> cmake option that he can use to enable/disable a sub-project. We use a topological sort internally to automatically resolve dependencies thus is project-A depends on project-B and the user turns ENABLE_A ON, then ENABLE_B option is hidden from the user and automatically enabled.

For certain sub-projects, we may want to present the user with an option to simply use an existing installed version of the subproject. We refer to this mode as using system version for the sub-project. In that case, the sub-project must use a add_external_project_or_use_system(..) call instead of add_external_project(...). When add_external_project_or_use_system(..) is used and the project is enabled (explicitly or indirectly due to dependency resolution), a USE_SYSTEM_<project-name> option is provided to the user. User can turn this ON to use a system version.

When USE_SYSTEM_<project-name> is ON, CMake tries to locate <project-name>.use.system.cmake file and import that. This file is expected to include the rules to find the system installation and provide variables that will help dependent sub-projects to use the system version. To facilitate that, we provide a macro add_extra_cmake_args(...) that can be called in <project-name>.use.system.cmake file. (The macro can also be used in <project-name>.cmake file for providing extra variables to dependent subprojects to assist in locating the project, in general). All arguments specified to the add_extra_cmake_args(...) macro are automatically passed to any sub-project that says it explicitly depends on this sub-project. We use this mechanism to enable the user to use a system mpi installation, and pass the appropriate flags to the ParaView cmake configuration stage, for example.

Directory Structure

The directory structure is as follows:

 ParaViewSuperbuild/   --  top level cmake files 
 ParaViewSuperbuild/CMake/ -- custom cmake files defining  new macros, functions, etc.
 ParaViewSuperbuild/Projects/ -- <project-name>...cmake files common to all platforms
 ParaViewSuperbuild/Projects/apple -- <project-name>...cmake files specific to MacOSX
 ParaViewSuperbuild/Projects/unix -- <project-name>...cmake files specific to Unix-based (non MacOSX) systems
 ParaViewSuperbuild/Projects/win32 -- <project-name>...cmake files specific to Windows

Submitting Changes

ParaViewSuperbuild repository uses gerrit for review and merging changes into the repository. To setup the development environment, simply run the following once you have checked out the git-repo

 > ./Scripts/setup-for-development.sh

The script will setup aliases for pushing topics to gerrit.

To push a topic that is the current HEAD, one simply does the following:

 > git gerrit-push

The topic can then be reviewed and merged using Kitware Gerrit. It is expected that every change is reviewed by at least one other developer.

Assorted Notes

1. When passing a value for any variable (typically CMake variables) in add_external_project(...), add_external_project_or_use_system(...), or add_extra_cmake_args(...) call that is a CMake list, don't use ';' to separate the list items, instead use '+'. e.g.

 add_extra_cmake_args(
    -DMPI_C_LIBRARIES:STRING=${install_location}/lib/libmpi.lib+${install_location}/lib/libopen-rte.lib
 )