README.md 19.6 KB
Newer Older
1
![ParaView-Superbuild](Documentation/img/paraview100.png)
2

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

W. Alan Scott's avatar
W. Alan Scott committed
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

W. Alan Scott's avatar
W. Alan Scott committed
20
21
To obtain the superbuild source locally, clone this repository using
[Git](https://git-scm.org).
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
22
23
24

    $ git clone --recursive https://gitlab.kitware.com/paraview/paraview-superbuild.git

25
26
# Building

W. Alan Scott's avatar
W. Alan Scott committed
27
The superbuild can be built with a Makefiles or Ninja CMake generator. The IDE
28
29
generators (Xcode and Visual Studio) are not supported.

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
## Requirements

The superbuild tries to provide all of its own dependencies, but some tooling
is assumed to be available on the host machine.

  - Compiler toolchain
    * GCC 4.9 or newer
    * Xcode 10 or newer (older is probably supported, but untested)
    * MSVC 2017 or newer
    * ICC (minimum version unknown)
  - Tools
    * `pkg-config` is used on non-Windows platforms to find dependencies in
      some projects
    * `ninja` (or `make`) for building
    * Python (if not built by the superbuild) for building packages
45
46
47
    * If building `mesa` or `osmesa`, `bison` and `flex` are required.
    * If building packages on Linux, `chrpath` is required to make relocatable
      packages
48

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
49
50
## Building a specific version

W. Alan Scott's avatar
W. Alan Scott committed
51
52
The superbuild project uses the same versioning scheme as ParaView,
and gets tagged for every release of ParaView.  For example, to build
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
53
ParaView version 5.7.1, checkout the `v5.7.0` tag of ParaView and
W. Alan Scott's avatar
W. Alan Scott committed
54
superbuild.
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
55
56

Currently available tags are shown
57
[here](https://gitlab.kitware.com/paraview/paraview-superbuild/-/tags).
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
58

W. Alan Scott's avatar
W. Alan Scott committed
59
To checkout a specific tag from the superbuild git repository:
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
60
61
62

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

W. Alan Scott's avatar
W. Alan Scott committed
66
67
68
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
Cory Quammen's avatar
Cory Quammen committed
69
version.  For example, you could use superbuild `v5.7.0`, to build the
W. Alan Scott's avatar
W. Alan Scott committed
70
71
72
73
74
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
75

76
77
78
79
80
 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
Cory Quammen's avatar
Cory Quammen committed
81
82
    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
83
    commit SHA. In this setup, when building the superbuild, it will clone and
W. Alan Scott's avatar
W. Alan Scott committed
84
    checkout the appropriate revision from the ParaView git repository automatically.
85
86
87
 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
W. Alan Scott's avatar
W. Alan Scott committed
88
89
    set `paraview_SOURCE_DIR` to point to a custom ParaView source tree. See 'offline
    builds' below for instructions to download needed dependency packages.
90
 3. Another option is to use a source tarball of a ParaView release. For that,
Cory Quammen's avatar
Cory Quammen committed
91
    set `paraview_SOURCE_SELECTION` to the version to build such as `5.7.0`.
92
93
94
    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
95

W. Alan Scott's avatar
W. Alan Scott committed
96
**NOTE:** If you switch to a superbuild version older than 5.2, the instructions
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
97
98
99
100
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
[Wiki](http://www.paraview.org/Wiki/index.php?title=ParaView/Superbuild&oldid=59804).

Ben Boeckel's avatar
Ben Boeckel committed
101
102
103
**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
104

105
106
107
108
109
110
111
112
113
## 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:

Ben Boeckel's avatar
Ben Boeckel committed
114
    $ rm superbuild/$project/stamp/$project-build
115
116
117

and to rerun the superbuild's build step.

118
119
## Projects and Features

Ben Boeckel's avatar
Ben Boeckel committed
120
121
122
123
124
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.

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
125
The `paraview` project must be enabled to build ParaView.
Ben Boeckel's avatar
Ben Boeckel committed
126
127

The `paraviewsdk` project enables the building of a package which includes
W. Alan Scott's avatar
W. Alan Scott committed
128
headers and libraries suitable for developing against ParaView. It is only available
Ben Boeckel's avatar
Ben Boeckel committed
129
130
131
132
on Linux (at the moment).

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

133
134
The `paraviewgettingstartedguide`, and `paraviewtutorialdata` packages add
startup documentation and example data to the package.
Ben Boeckel's avatar
Ben Boeckel committed
135
136

ParaView supports multiple rendering engines including `egl`, `mesa`,
Ben Boeckel's avatar
Ben Boeckel committed
137
`osmesa`, and `qt5`. All of these are incompatible with each other. If none of
138
these are chosen, a UI-less ParaView will be built (basically just
Ben Boeckel's avatar
Ben Boeckel committed
139
140
`pvpython`). On Windows and macOS, only the `qt5` rendering engine is
available.
Ben Boeckel's avatar
Ben Boeckel committed
141
142
143
144
145
146
147
148

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.
149
  * `las`: Enable reading the LAS file format
Ben Boeckel's avatar
Ben Boeckel committed
150
151
152
153
154
155
156
157
158
159
  * `cosmotools`: Enables Cosmo file format readers and related filters and
    algorithms.
  * `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
    project.
  * `vortexfinder2`: A collection of tools to visualize and analyze vortices.
160
  * `vrpn`: Virtual reality support through the VRPN interface.
Marc's avatar
Marc committed
161
  * `vtkm`: VTK-m Accelerator Filters
Ben Boeckel's avatar
Ben Boeckel committed
162
  * `xdmf3`: A meta file format built on top of HDF5.
163

164
165
## Offline builds

W. Alan Scott's avatar
W. Alan Scott committed
166
167
168
169
170
171
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
172
173
location).

174
175
176
177
178
179
180
181
182
Note that the `nvidiaoptix` and `nvidiamdl` project sources are not available
at their URLs in the superbuild outside of Kitware due to their sources being
behind click-wrapping. They may be manually downloaded from these web pages:

  * `nvidiaoptix`: https://developer.nvidia.com/designworks/optix/download
    Though older versions are available here:
    https://developer.nvidia.com/designworks/optix/downloads/legacy
  * `nvidiamdl`: https://developer.nvidia.com/mdl-sdk

183
184
185
186
187
188
189
190
191
192
193
194
195
196
### Overriding downloaded archives

On rare occasions, you may want to replace a downloaded archive with a different
version. You may replace the archive with a newer version preserving its
name, however, on doing so, the hash verification will most likely fail during
the build step. To skip the hash verification for archives that have been
manually changed, set the `xxx_SKIP_VERIFICATION` option, where `xxx`
is the name of the project. `xxx_SKIP_VERIFICATION` must be passed on command line
when invoking CMake using `-Dxxx_SKIP_VERIFICATION:BOOL=TRUE`.

Alternatively, you can edit the `versions.cmake` files in the source repository
and modify the `URL_MDF5` or `URL_HASH` values for the specific project with
updated hashes.

197
198
199
200
201
202
203
204
205
206
## 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
include:

  * `paraview/ZIP`
  * `paraview/DragNDrop`
  * `paraview/TGZ`
Cory Quammen's avatar
Cory Quammen committed
207
  * `paraview/TXZ`
208
  * `paraviewsdk/TGZ`
Cory Quammen's avatar
Cory Quammen committed
209
  * `paraviewsdk/TXZ`
210
211
212
213
214
215
216

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
Cory Quammen's avatar
Cory Quammen committed
217
will be created whereas the `TGZ`, `TXZ`, and `ZIP` generators use the standard
218
219
220
221
222
223
224
225
226
227
228
229
230
`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.

231
232
233
234
235
236
## 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:

W. Alan Scott's avatar
W. Alan Scott committed
237
  * `ENABLE_paraviewexternalplugins:BOOL=ON`: Enables building using external
238
239
240
241
242
243
244
245
    plugins.
  * `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.
  * `paraview_PLUGIN_b_PATH:PATH=/path/to/plugin/b`: Same as above, but for
    plugin `b`.

246
247
## CMake Variables

248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
### 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
time.

  * 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.
264
265
266
267
268
269
270
271
  * 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.
272

273
274
275
276
277
278
279
280
281
282
283
### 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
284
285
    enabled due to a project depending on it (e.g., `visitbridge` requires
    `boost`, so enabling `visitbridge` will hide the `ENABLE_boost` option).
286
287
288
  * `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).
289
290
291
  * `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.
292
293
  * `CMAKE_BUILD_TYPE` (default `Release`): The build type to use for the
    build. Can be `Release`, `RelWithDebInfo`, or (on not-Windows) `Debug`.
294
295
296
  * Due to complications around shipping OpenSSL in the binaries, OpenSSL
    requires explicit settings in the build. They are
    `-DALLOW_openssl:BOOL=ON -DENABLE_openssl:BOOL=ON`.
297
298
299
  * `paraview_always_package_scipy` (default `OFF`): Force packaging `scipy` on
    Windows installer generators. Other generators do not have issues with long
    paths and will always try to include `scipy`.
300
301
302

The following flags affect ParaView directly:

303
  * `paraview_SOURCE_SELECTION` (default `5.10.1`): The source to use for
304
305
306
307
308
309
310
    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.
311
312
313
314
315

    **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.
316
317
  * `CMAKE_BUILD_TYPE_paraview` (default is the same as the superbuild):
    ParaView may be built with a different build type (e.g., `Release` vs.
318
319
320
    `RelWithDebInfo`) as the rest of the superbuild using this variable. In
    addition to `<SAME>` which uses `CMAKE_BUILD_TYPE`, any valid value for
    `CMAKE_BUILD_TYPE` is also valid.
321
322
323
324
325
326
  * `BUILD_SHARED_LIBS_paraview` (default is the same as the superbuild):
    ParaView may be built with a different selection for BUILD_SHARED_LIBS flag
    than the rest of the superbuild using this variable. For example,
    to build ParaView static while building other projects in the superbuild
    (e.g. MPI, Python, etc.) as shared, set `BUILD_SHARED_LIBS` to `ON`
    and `BUILD_SHARED_LIBS_paraview` to `OFF`.
327
328
  * `PARAVIEW_BUILD_WEB_DOCUMENTATION` (default `OFF`): Have ParaView build
    its HTML documentation.
329
  * `mesa_USE_SWR` (default `ON`): If `mesa` is enabled, this enables
330
    Intel's software rasterization backend (x86 only).
331
332
333
334
335
336
337
338
  * `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.
339
340
341
  * `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.
342
343
  * `PARAVIEW_ENABLE_CAVEInteraction` (default `ON`): Enables the CAVEInteraction. If
    `vrpn` is enabled, the CAVEInteraction will support input devices through a VRPN
344
    connection. VRUI support is enabled unconditionally on Linux.
345
346
  * `PARAVIEW_ENABLE_NODEEDITOR` (default `OFF`): Enables the NodeEditor
    plugin.
Spiros Tsalikis's avatar
Spiros Tsalikis committed
347
  * `PARAVIEW_ENABLE_XRInterface` (default `ON`): Enables the XRInterface plugin.
348

349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
#### ParaView editions

A typical ParaView build includes several modules and dependencies. While these
are necessary for a fully functional application, there are cases (e.g. in situ
use-cases) where a build with limited set of features is adequate. ParaView build supports
this using the `PARAVIEW_BUILD_EDITION` setting. Supported values for this setting are:

* `CORE`: Build modules necessary for core ParaView functionality.
  This does not include rendering.
* `RENDERING`: Build modules necessary for supporting rendering including views
  and representations. This includes everything in `CORE`.
* `CATALYST`: Build all modules necessary for in situ use cases without
  rendering and optional components like NetCDF- and HDF5-based readers and
  writers.
* `CATALYST_RENDERING`: Same as `CATALYST` but with rendering supported added.
* `CANONICAL` (default): Build modules necessary for standard ParaView build.

366
367
368
369
### Packaging Variables

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

373
374
375
376
377
# 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
378
# Learning Resources
379
380
381
382
383
384
385
386
387
388
389
390
391
392

* 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]: http://www.paraview.org
[ParaView Mailing Lists]: http://www.paraview.org/mailing-lists/
[Kitware]: http://www.kitware.com/
[Kitware Support]: http://www.kitware.com/products/support.html
[Kitware Training]: http://www.kitware.com/products/protraining.php

Ben Boeckel's avatar
Ben Boeckel committed
393
# Reporting Bugs
394
395
396

If you have found a bug:

Ben Boeckel's avatar
Ben Boeckel committed
397
 1. If you have a patch, please read the [CONTRIBUTING.md][] document.
398

Ben Boeckel's avatar
Ben Boeckel committed
399
400
401
 2. Otherwise, please join one of the [ParaView Mailing Lists][] and ask
    about the expected and observed behaviors to determine if it is
    really a bug.
402

Ben Boeckel's avatar
Ben Boeckel committed
403
404
 3. Finally, if the issue is not resolved by the above steps, open
    an entry in the [ParaView Issue Tracker][].
405
406
407

[ParaView Issue Tracker]: http://www.paraview.org/Bug

Ben Boeckel's avatar
Ben Boeckel committed
408
# License
409

Ben Boeckel's avatar
Ben Boeckel committed
410
411
412
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][].
413
414
415
416

[Copyright.txt]: Copyright.txt
[ParaView Licenses]: http://www.paraview.org/paraview-license/

Ben Boeckel's avatar
Ben Boeckel committed
417
# Contributing
418
419
420
421

See [CONTRIBUTING.md][] for instructions to contribute.

[CONTRIBUTING.md]: CONTRIBUTING.md