15.8 KB
Newer Older

Ben Boeckel's avatar
Ben Boeckel committed
3 4
# Introduction

5 6 7 8 9 10 11 12 13 14 15
ParaView-Superbuild, henceforth referred to as "superbuild", is a project to
build ParaView and its dependencies. ParaView itself can be easily built using
CMake as long as the required external dependencies are available on the build
machine. However, ParaView's several external dependencies, e.g. Qt, CGNS,
FFMPEG, etc. can be very tedious to build. Also, if you want to generate
redistributable binaries, you need to take extra care when building and
packaging these dependencies. To make our lives easier in supporting both these
use-cases, the superbuild project was born.

Although primarily designed to build the official ParaView binaries, the
superbuild has since been regularly used to build and install ParaView
16 17
on various supercomputing systems.

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
18 19
# Obtaining the source

20 21
To obtain the superbuild source locally, clone this repository using
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
22 23 24

    $ git clone --recursive

25 26
# Building

The superbuild can be built with a Makefiles or Ninja CMake generator. The IDE
28 29
generators (Xcode and Visual Studio) are not supported.

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
30 31
## Building a specific version

32 33
The superbuild project uses the same versioning scheme as ParaView,
and gets tagged for every release of ParaView.  For example, to build
ParaView version 5.4.1, checkout the `v5.7.0` tag of ParaView and
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
36 37 38 39

Currently available tags are shown

To checkout a specific tag from the superbuild git repository:
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
41 42 43

    $ cd paraview-superbuild
    $ git fetch origin # ensure you have the latest state from the main repo
    $ git checkout v5.7.0 # replace `v5.7.0` with tag name of your choice
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
45 46
    $ git submodule update

47 48 49
At this point, your superbuild has all of the *rules* that were used
when building the selected version of ParaView. Also, note that it's
possible to build a version of ParaView using a different superbuild
version.  For example, you could use superbuild `v5.7.0`, to build the
51 52 53 54 55
latest master (i.e., development) version of ParaView, or a custom
branch.  This is done by first checking out the superbuild for the
appropriate version and then setting the CMake variables that affect
which ParaView source is to be used.  There are several ways to
control how superbuild finds its source packages:
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed

57 58 59 60 61
 1. If you want to use git to checkout ParaView source (default), then set
    `paraview_SOURCE_SELECTION` to `git`, ensure `paraview_GIT_REPOSITORY` is
    pointing to the ParaView git repository you want to clone (by default it is
    set to the offical ParaView repository) and then set the `paraview_GIT_TAG`
    to be a specific tagname or branch available for the selected git
62 63
    repository. Use `master` for latest development code, `v5.7.0` for the
    5.7.0 release, `release` for latest stable release, or a specific ParaView
    commit SHA. In this setup, when building the superbuild, it will clone and
    checkout the appropriate revision from the ParaView git repository automatically.
66 67 68
 2. Instead of letting superbuild do the cloning and updating of the ParaView
    source, you can also manually check it out and keep it updated as needed.
    To use this configuration, set `paraview_SOURCE_SELECTION` to `source`, and
69 70
    set `paraview_SOURCE_DIR` to point to a custom ParaView source tree. See 'offline
    builds' below for instructions to download needed dependency packages.
 3. Another option is to use a source tarball of a ParaView release. For that,
    set `paraview_SOURCE_SELECTION` to the version to build such as `5.7.0`.
73 74 75
    The superbuild offers the lastest stable release as well as release
    candidate in preparation for the release. This is the best way to build a
    released version of ParaView.
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed

**NOTE:** If you switch to a superbuild version older than 5.2, the instructions
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
78 79 80 81
described on this page are not relevant since the superbuild was refactored and
changed considerably for 5.2. For older versions, refer to instructions on the

Ben Boeckel's avatar
Ben Boeckel committed
82 83 84
**ALSO NOTE:** Since this README is expected to be updated for each version,
once you checkout a specfic version, you may want to refer to the README for
that specific version.
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed

86 87 88 89 90 91 92 93 94 95 96 97 98
## Incremental builds

The superbuild is kind of naïve for changes to project sources within the
superbuild. This is due to the superbuild not tracking all source files for
each project and instead only "stamp files" to indicate the steps performed.

When changing the source of a subproject, the best solution is to delete the
"stamp file" for the build step of that project:

   $ rm superbuild/$project/stamp/$project-build

and to rerun the superbuild's build step.

99 100
## Projects and Features

101 102 103 104 105 106
The superbuild contains multiple projects which may be used to enable
different features within the resulting ParaView build. Most projects involve
downloading and adding the feature to the resulting package, but there are a
few which are used just to enable features within ParaView itself.

The `catalyst` and `paraview` projects are mutually exclusive (the libraries
107 108
conflict in the install tree). One of these two projects must be enabled.
The `catalyst` package is only available on Linux.
109 110

The `paraviewsdk` project enables the building of a package which includes
headers and libraries suitable for developing against ParaView. It is only available
112 113 114 115
on Linux (at the moment).

The `paraviewweb` project adds web services into the resulting package.

116 117
The `paraviewgettingstartedguide`, and `paraviewtutorialdata` packages add
startup documentation and example data to the package.
118 119

ParaView supports multiple rendering engines including `egl`, `mesa`,
Ben Boeckel's avatar
Ben Boeckel committed
`osmesa`, and `qt5`. All of these are incompatible with each other. If none of
these are chosen, a UI-less ParaView will be built (basically just
Ben Boeckel's avatar
Ben Boeckel committed
122 123
`pvpython`). On Windows and macOS, only the `qt5` rendering engine is
124 125 126 127 128 129 130 131

The `python` package is available to enable Python support in the package. In
addition, the `matplotlib` and `numpy` packages are available.

The following packages enable other features within ParaView:

  * `adios`: Enable readers and writers for visualization data in the ADIOS
    file format.
Ben Boeckel's avatar
Ben Boeckel committed
  * `boxlib`: Enable reading the boxlib3D file format.
  * `las`: Enable reading the LAS file format
134 135 136 137 138 139 140 141 142 143 144
  * `cosmotools`: Enables Cosmo file format readers and related filters and
  * `ffmpeg`: Video encoding library for macOS and Linux.
  * `ospray`: A ray tracing rendering backend from Intel.
  * `silo`: Support reading the silo file format.
  * `tbb`: Improved parallel processing support within various VTK and
    ParaView filters and algorithms.
  * `visitbridge`: Enables readers for file formats provided from the VisIt
  * `vortexfinder2`: A collection of tools to visualize and analyze vortices.
  * `vrpn`: Virtual reality support.
  * `vtkm`: VTK-m Accelerator Filters
  * `xdmf3`: A meta file format built on top of HDF5.

148 149
## Offline builds

150 151 152 153 154 155
The superbuild has a `download-all` target that will download all of
the files from the network that are necessary for the currently
configured build. By default, they are placed into the `downloads`
directory of the build tree.  This superbuild-plus-downloads tree may
then be copied to a non-networked machine and pointed at using the
`superbuild_download_location` variable (or placed in the default
156 157

158 159 160 161 162 163 164 165 166 167
## Installing

The superbuild supports the `install` target by selecting a template package
using the `SUPERBUILD_DEFAULT_INSTALL` variable. The default and availability
depends on the platform and selected projects, but valid values for this

  * `paraview/ZIP`
  * `paraview/DragNDrop`
  * `paraview/TGZ`
  * `paraview/TXZ`
  * `catalyst/TGZ`
  * `catalyst/TXZ`
  * `paraviewsdk/TGZ`
  * `paraviewsdk/TXZ`
173 174 175 176 177 178 179

The CMake cache editors (`ccmake` and `cmake-gui`) have dropdown options for
the supported options.

The selected package logic will be used to install ParaView and its
dependencies into `CMAKE_INSTALL_PREFIX` rather than being placed into a
package. For example, the `DragNDrop` generator creates `.app` bundles which
will be created whereas the `TGZ`, `TXZ`, and `ZIP` generators use the standard
181 182 183 184 185 186 187 188 189 190 191 192 193
`bin/`, `lib/`, etc. directories.

### Caveats

If using the `git` source selection for ParaView, the build will rerun when
using the `install` target due to limitations in the external project
mechanisms and the way CPack works. There are two ways to avoid this:

  * the `SUPERBUILD_OFFLINE_BUILD` option may be set to `ON` to unlink the git
    update step from the configure/build steps; or
  * the initial build can just be run using the `install` target instead of
    the usual `make && make install` pattern.

194 195 196 197 198 199
## External plugins

The superbuild supports building more plugins into ParaView using the
`paraviewexternalplugins` project. As an example, to build two external
plugins `a` and `b`, the following settings should be used:

  * `ENABLE_paraviewexternalplugins:BOOL=ON`: Enables building using external
201 202 203 204 205 206 207 208
  * `paraview_PLUGINS_EXTERNAL:STRING=a;b`: The list of plugins to build.
  * `paraview_PLUGIN_a_PATH:PATH=/path/to/plugin/a`: The path to plugin `a`'s
    source directory. It must contain a `plugins.cmake` to be picked up by
  * `paraview_PLUGIN_b_PATH:PATH=/path/to/plugin/b`: Same as above, but for
    plugin `b`.

209 210
## CMake Variables

211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
### Style Guide

Note that currently not all project and configuration variables follow this
style guide but any new projects should use this convention while any
existing projects and configuration variables will transition to this over

  * All references to a given project name will be lowercase.
  * Underscores will be used as word seperators in variable names.
  * All project specific configuration variables will be lower-case project
    name followed by upper-case setting name.
    Examples include:
      * `mesa_USE_SWR` : Enable the OpenSWR driver for (OS)Mesa.
      * `ospray_BUILD_ISA` : Select the SIMD architecture used to build OSPray.
  * Internal variables used within a given project's projectname.cmake file
    will be all lower-case.
227 228 229 230 231 232 233 234
  * Multiple versions:
      * Use the `superbuild_set_selectable_source` macro to allow multiple
        versions of a given project.
      * Specify source selection versions as numeric, i.e. without any "v" or
        "V" prefix.
      * If the project is going through a release candidate cycle, add the
        available RCs as additional sources as they become availabe.  Once
        a final release is made, replace all the RCs with the updated release.

236 237 238 239 240 241 242 243 244 245 246
### Build Variables

  * `superbuild_download_location` (default `${CMAKE_BINARY_DIR}/downloads`):
    The location to store downloaded source artifacts. Usually, it is changed
    so that it is preserved across a wipe of the build directory.
  * `SUPERBUILD_PROJECT_PARALLELISM` (default based on the number of available
    processors): When using a Makefiles generator, subproject builds use `-j`
    explicitly with this number.
  * `ENABLE_xxx` (generally, default `OFF`): If selected, the `xxx` project
    will be built within the superbuild. See above for descriptions of the
    various projects. `ENABLE_` flags are not shown for projects which must be
Ben Boeckel's avatar
Ben Boeckel committed
247 248
    enabled due to a project depending on it (e.g., `visitbridge` requires
    `boost`, so enabling `visitbridge` will hide the `ENABLE_boost` option).
249 250 251
  * `USE_SYSTEM_xxx` (default `OFF`): If selected, the `xxx` project from the
    build environment is used instead of building it within the superbuild.
    Not all projects support system copies (the flag is not available if so).
252 253 254
  * `SUPERBUILD_DEBUG_CONFIGURE_STEPS` (default `OFF`): If set, the superbuild
    will log configure steps for each `xxx` project into
    `superbuild/xxx/stamp/xxx-configure-*.log` files.
255 256 257

The following flags affect ParaView directly:

  * `paraview_SOURCE_SELECTION` (default `5.7.0`): The source to use for
259 260 261 262 263 264 265
    ParaView itself. The version numbers use the source tarballs from the
    website for the release. The `source` selection uses the
    `paraview_SOURCE_DIR` variable to look at a checked out ParaView source
    directory. The `git` selection has the superbuild clone and builds a
    checkout of ParaView from git repository controlled by the
    `paraview_GIT_REPOSITORY` and `paraview_GIT_TAG` variables. By default, the
    `master` branch of the main repository is used.
266 267 268 269 270

    **Note**: When using the `source` selection, incremental builds to the
    superbuild may not rebuild ParaView even if the source tree has changed.
    This is because the superbuild is "blind" to the source tree other than
    its existence.
271 272 273 274 275
  * `CMAKE_BUILD_TYPE_paraview` (default is the same as the superbuild):
    ParaView may be built with a different build type (e.g., `Release` vs.
    `RelWithDebInfo`) as the rest of the superbuild using this variable.
  * `PARAVIEW_BUILD_WEB_DOCUMENTATION` (default `OFF`): Have ParaView build
    its HTML documentation.
  * `mesa_USE_SWR` (default `ON`): If `mesa` is enabled, this enables
    Intel's software rasterization backend (x86 only).
278 279 280 281 282 283 284 285
  * `PARAVIEW_INITIALIZE_MPI_ON_CLIENT` (default `ON`): If `mpi` is enabled, this
    enables MPI to be initialized automatically when running the GUI or pvpython.
    Some readers use MPI IO and thus must have MPI initialized in order to be
    used so this is the default for general ease of use. For some MPI implementations,
    a code that initializes MPI must be run with the appropriate mpi launcher
    (e.g. mpirun) which in this case it may be desirable to disable this option.
    Note that the `--mpi` or `--no-mpi` command line options to paraview and
    pvpython can be used to override this option.
286 287 288
  * `PARAVIEW_EXTRA_CMAKE_ARGUMENTS` (default `""`: Extra CMake arguments to
    pass to ParaView's configure step. This can be used to set CMake variables
    for the build that are otherwise not exposed in the superbuild itself.
289 290 291 292 293 294 295 296 297 298 299 300

The following flags affect Catalyst:

  * `PARAVIEW_CATALYST_EDITION` (default `Essentials`): The edition of
    Catalyst to build (also available: `Extras` and `Rendering-Base`).
  * `PARAVIEW_CATALYST_PYTHON` (default `ON`): Enable Python support in

### Packaging Variables

  * `PARAVIEW_PACKAGE_SUFFIX` (default based on selected options): The suffix
    for the name generated by the package.
301 302
  * `paraview_PLUGINS_AUTOLOAD`: List of plugins to autoload in the packaged

304 305 306 307 308
# Packaging

The packages may be built using the `cpack-paraview` tests via `ctest`. The
easiest way to build all available packages is to run `ctest -R cpack`.

Ben Boeckel's avatar
Ben Boeckel committed
# Learning Resources
310 311 312 313 314 315 316 317 318 319 320 321 322 323

* General information is available at the [ParaView Homepage][].

* Community discussion takes place on the [ParaView Mailing Lists][].

* Commercial [support][Kitware Support] and [training][Kitware Training]
  are available from [Kitware][].

[ParaView Homepage]:
[ParaView Mailing Lists]:
[Kitware Support]:
[Kitware Training]:

Ben Boeckel's avatar
Ben Boeckel committed
# Reporting Bugs
325 326 327 328 329

If you have found a bug:

1. If you have a patch, please read the [][] document.

2. Otherwise, please join one of the [ParaView Mailing Lists][] and ask
331 332 333 334 335 336 337 338
   about the expected and observed behaviors to determine if it is
   really a bug.

3. Finally, if the issue is not resolved by the above steps, open
   an entry in the [ParaView Issue Tracker][].

[ParaView Issue Tracker]:

Ben Boeckel's avatar
Ben Boeckel committed
# License

Ben Boeckel's avatar
Ben Boeckel committed
341 342 343
Like ParaView, ParaView-Superbuild is distributed under the OSI-approved BSD
3-clause License. See [Copyright.txt][] for details. For additional licenses,
refer to [ParaView Licenses][].
344 345 346 347

[Copyright.txt]: Copyright.txt
[ParaView Licenses]:

Ben Boeckel's avatar
Ben Boeckel committed
# Contributing
349 350 351 352

See [][] for instructions to contribute.