ParaView/Superbuild

From KitwarePublic
Jump to navigationJump to search

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.

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.

Downloading nightly binaries for ParaView

Platform-specific Notes

Common

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 another 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
 )