ParaView/Superbuild: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
(Replaced content with "Updated for ParaView Superbuild have moved to the [https://gitlab.kitware.com/paraview/paraview-superbuild/ source repository] starting with ParaView 5.2. For docs for ear...")
 
(34 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<font color="green">'''THIS PAGE IS UNDER CONSTRUCTION FOR THE UPCOMING PARAVIEW RELEASE. PLEASE CHECKBACK LATER'''</font>
Updated for ParaView Superbuild have moved to the [https://gitlab.kitware.com/paraview/paraview-superbuild/ source repository] starting with ParaView 5.2. For docs for earlier versions, please check out the history tab for this page.
 
=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 [http://www.kitware.com/media/html/BuildingExternalProjectsWithCMake2.8.html 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 [http://paraview.org 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 [http://cmake.org 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 [[ParaView:Build_And_Install#Download_And_Install_CMake|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 [http://python.org 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 [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://paraview.org/gitweb.
 
{|border="1" cellspacing="0" cellpadding="3"
!Repository
!Purpose
!Access
!URL
|-
|rowspan=3|<code>ParaViewSuperbuild.git</code>
|rowspan=3|ParaView Super-Build
|fetch (git)
|<code>git://paraview.org/ParaViewSuperbuild.git</code>
|-
|fetch (http)
|<code>http://paraview.org/ParaViewSuperbuild.git</code>
|-
|push (ssh)
|<code>git@paraview.org:ParaViewSuperbuild.git</code>
|}
 
This repository is tested nightly on the [http://open.cdash.org/index.php?project=ParaView 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]
 
==Windows==
 
==Mac Os X==
 
# ParaView Super-Build has only been tested for x86_64 architecture using 10.6 (Snow Leopard) SDK.
# 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 | ParaView Binaries Build Information]] for details of the compiler we use for our binaries.
# 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.
# Qt 4.8.2 is affected by a [https://bugreports.qt-project.org/browse/QTBUG-24498 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
 
[[Category:ParaView]]

Latest revision as of 15:01, 15 October 2016

Updated for ParaView Superbuild have moved to the source repository starting with ParaView 5.2. For docs for earlier versions, please check out the history tab for this page.