ParaView/Superbuild

THIS PAGE IS UNDER CONSTRUCTION FOR THE UPCOMING PARAVIEW RELEASE. PLEASE CHECKBACK LATER

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.

• On Windows, in order to enable scripting support, installed Python is required. We do not build Python from source on Windows (and also on Mac OSX, but Python is preinstalled on OSX, so one doesn't need to manually install it). Note this is only for the machine on which the binaries are being built and not the machine on which the binaries are installed.

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.

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]

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.

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