1# Building VTK 2 3This page describes how to build and install VTK. It covers building for 4development, on both Unix-type systems (Linux, HP-UX, Solaris, macOS), and 5Windows. Note that Unix-like environments such as Cygwin and MinGW are not 6officially supported. However, patches to fix problems with these platforms 7will be considered for inclusion. It is recommended that users which require 8VTK to work on these platforms to submit nightly testing results for them. 9 10A full-featured build of VTK depends on several open source tools and libraries 11such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the VTK 12source itself (e.g., HDF5), while others are expected to be present on the 13machine on which VTK is being built (e.g., Python, Qt). 14 15## Obtaining the source 16 17To obtain VTK's sources locally, clone this repository using 18[Git][git]. 19 20```sh 21git clone --recursive https://gitlab.kitware.com/vtk/vtk.git 22``` 23 24## Building 25 26VTK supports all of the common generators supported by CMake. The Ninja, 27Makefiles, and Visual Studio generators are the most well-tested however. 28 29Note that VTK does not support in-source builds, so you must have a build tree 30that is not the source tree. 31 32### Prerequisites 33 34VTK only requires a few packages in order to build in general, however 35specific features may require additional packages to be provided to VTK's 36build configuration. 37 38Required: 39 40 * [CMake][cmake] 41 - Version 3.12 or newer, however, the latest version is always recommended 42 * Supported compiler 43 - GCC 4.8 or newer 44 - Clang 3.3 or newer 45 - Apple Clang 5.0 (from Xcode 5.0) or newer 46 - Microsoft Visual Studio 2015 or newer 47 - Intel 14.0 or newer 48 49Optional dependencies: 50 51 * [Python][python] 52 - When using Python 2, at least 2.7 is required 53 - When using Python 3, at least 3.4 is required 54 * [Qt5][qt] 55 - Version 5.9 or newer 56 57#### Installing CMake 58 59CMake is a tool that makes cross-platform building simple. On several systems 60it will probably be already installed or available through system package 61management utilities. If it is not, there are precompiled binaries available on 62[CMake's download page][cmake-download]. 63 64#### Installing Qt 65 66VTK uses Qt as its GUI library (if the relevant modules are enabled). 67Precompiled binaries are available on [Qt's website][qt-download]. 68 69Note that on Windows, the compiler used for building VTK must match the 70compiler version used to build Qt. 71 72### Optional Additions 73 74#### Download And Install ffmpeg (`.avi`) movie libraries 75 76When the ability to write `.avi` files is desired, and writing these files is 77not supported by the OS, VTK can use the ffmpeg library. This is generally 78true for Unix-like operating systems. Source code for ffmpeg can be obtained 79from [the website][ffmpeg]. 80 81#### MPI 82 83To run VTK in parallel, an [MPI][mpi] implementation is required. If an MPI 84implementation that exploits special interconnect hardware is provided on your 85system, we suggest using it for optimal performance. Otherwise, on Linux/Mac, 86we suggest either [OpenMPI][openmpi] or [MPICH][mpich]. On Windows, [Microsoft 87MPI][msmpi] is required. 88 89#### Python 90 91In order to use scripting, [Python][python] is required (versions 2.7 and 3.3). 92 93#### OSMesa 94 95Off-screen Mesa can be used as a software-renderer for running VTK on a server 96without hardware OpenGL acceleration. This is usually available in system 97packages on Linux. For example, the `libosmesa6-dev` package on Debian and 98Ubuntu. However, for older machines, building a newer version of Mesa is 99likely necessary for bug fixes and support. Its source and build instructions 100can be found on [its website][mesa]. 101 102## Creating the Build Environment 103 104### Linux (Ubuntu/Debian) 105 106 * `sudo apt install` the following packages: 107 - `build-essential` 108 - `cmake` 109 - `mesa-common-dev` 110 - `mesa-utils` 111 - `freeglut3-dev` 112 - `ninja-build` 113 - `ninja` is a speedy replacement for `make`, highly recommended. 114 115### Windows 116 117 * [Visual Studio Community Edition][visual-studio] 118 * Use "x64 Native Tools Command Prompt" for the installed Visual Studio 119 version to configure with CMake and to build with ninja. 120 * Get [ninja][ninja]. Unzip the binary and put it in `PATH`. Note that newer 121 Visual Studio releases come with a version of `ninja` already and should 122 already exist in `PATH` within the command prompt. 123 124## Building 125 126In order to build, CMake requires two steps, configure and build. VTK itself 127does not support what are known as in-source builds, so the first step is to 128create a build directory. 129 130```sh 131mkdir -p vtk/build 132cd vtk/build 133ccmake ../path/to/vtk/source # -GNinja may be added to use the Ninja generator 134``` 135 136CMake's GUI has input entries for the build directory and the generator 137already. Note that on Windows, the GUI must be launched from a "Native Tools 138Command Prompt" available with Visual Studio in the start menu. 139 140### Missing dependencies 141 142CMake may not find all dependencies automatically in all cases. The steps 143needed to find any given package depends on the package itself. For general 144assistance, please see the documentation for 145[`find_package`'s search procedure][cmake-find_package-search] and 146[the relevant Find module][cmake-modules-find] (as available). 147 148### Build Settings 149 150VTK has a number of settings available for its build. The common variables 151to modify include: 152 153 * `BUILD_SHARED_LIBS` (default `ON`): If set, shared libraries will be 154 built. This is usually what is wanted. 155 * `VTK_USE_CUDA` (default `OFF`): Whether [CUDA][cuda] support will be available or 156 not. 157 * `VTK_USE_MPI` (default `OFF`): Whether [MPI][mpi] support will be available or 158 not. 159 * `VTK_WRAP_PYTHON` (default `OFF`; requires `VTK_ENABLE_WRAPPING`): Whether 160 Python support will be available or not. 161 * `VTK_PYTHON_VERSION` (default `3`): The major version of Python to 162 support. Must be either `2` or `3`. 163 164Less common, but variables which may be of interest to some: 165 166 * `VTK_BUILD_EXAMPLES` (default `OFF`): If set, VTK's example code will be 167 added as tests to the VTK test suite. 168 * `VTK_ENABLE_LOGGING` (default `ON`): If set, enhanced logging will be 169 enabled. 170 * `VTK_BUILD_TESTING` (default `OFF`): Whether to build tests or not. Valid 171 values are `OFF` (no testing), `WANT` (enable tests as possible), and `ON` 172 (enable all tests; may error out if features otherwise disabled are 173 required by test code). 174 * `VTK_ENABLE_KITS` (default `OFF`; requires `BUILD_SHARED_LIBS`): Compile 175 VTK into a smaller set of libraries. Can be useful on platforms where VTK 176 takes a long time to launch due to expensive disk access. 177 * `VTK_ENABLE_WRAPPING` (default `ON`): Whether any wrapping support will be 178 available or not. 179 * `VTK_WRAP_JAVA` (default `OFF`; requires `VTK_ENABLE_WRAPPING`): 180 Whether Java support will be available or not. 181 * `VTK_SMP_IMPLEMENTATION_TYPE` (default `Sequential`): Set which SMPTools 182 will be implemented by default. Must be either `Sequential`, `STDThread`, 183 `OpenMP` or `TBB`. The backend can be changed at runtime if the desired 184 backend has his option `VTK_SMP_ENABLE_<backend_name>` set to `ON`. 185 186More advanced options: 187 188 * `VTK_BUILD_DOCUMENTATION` (default `OFF`): If set, VTK will build its API 189 documentation using Doxygen. 190 * `VTK_BUILD_ALL_MODULES` (default `OFF`): If set, VTK will enable all 191 modules not disabled by other features. 192 * `VTK_ENABLE_REMOTE_MODULES` (default `ON`): If set, VTK will try to build 193 remote modules (the `Remote` directory). If unset, no remote modules will 194 build. 195 * `VTK_USE_EXTERNAL` (default `OFF`): Whether to prefer external third 196 party libraries or the versions VTK's source contains. 197 * `VTK_TARGET_SPECIFIC_COMPONENTS` (default `OFF`): Whether to install 198 files into target-specific components (`<TARGET>-runtime`, 199 `<TARGET>-development`, etc.) or general components (`runtime`, 200 `development`, etc.) 201 * `VTK_VERSIONED_INSTALL` (default `ON`): Whether to add version numbers to 202 VTK's include directories and library names in the install tree. 203 * `VTK_CUSTOM_LIBRARY_SUFFIX` (default depends on `VTK_VERSIONED_INSTALL`): 204 The custom suffix for libraries built by VTK. Defaults to either an empty 205 string or `X.Y` where `X` and `Y` are VTK's major and minor version 206 components, respectively. 207 * `VTK_INSTALL_SDK` (default `ON`): If set, VTK will install its headers, 208 CMake API, etc. into its install tree for use. 209 * `VTK_RELOCATABLE_INSTALL` (default `ON`): If set, the install tree will be 210 relocatable to another path. If unset, the install tree may be tied to the 211 build machine with absolute paths, but finding dependencies in 212 non-standard locations may require work without passing extra information 213 when consuming VTK. 214 * `VTK_UNIFIED_INSTALL_TREE` (default `OFF`): If set, the install tree is 215 stipulated to be a unified install tree of VTK and all of its dependencies; 216 a unified tree usually simplifies things including, but not limited to, 217 the Python module paths, library search paths, and plugin searching. This 218 option is irrelevant if a relocatable install is requested as such setups 219 assume that dependencies are set up either via a unified tree or some other 220 mechanism such as modules). 221 * `VTK_ENABLE_SANITIZER` (default `OFF`): Whether to enable sanitization of 222 the VTK codebase or not. 223 * `VTK_SANITIZER` (default `address`; requires `VTK_ENABLE_SANITIZER`): The 224 sanitizer to use. 225 * `VTK_USE_LARGE_DATA` (default `OFF`; requires `VTK_BUILD_TESTING`): 226 Whether to enable tests which use "large" data or not (usually used to 227 reduce the amount of data downloading required for the test suite). 228 * `VTK_LEGACY_REMOVE` (default `OFF`): If set, VTK will disable legacy, 229 deprecated APIs. 230 * `VTK_LEGACY_SILENT` (default `OFF`; requires `VTK_LEGACY_REMOVE` to be 231 `OFF`): If set, usage of legacy, deprecated APIs will not cause warnings. 232 * `VTK_USE_TK` (default `OFF`; requires `VTK_WRAP_PYTHON`): If set, VTK will 233 enable Tkinter support for VTK widgets. 234 * `VTK_BUILD_COMPILE_TOOLS_ONLY` (default `OFF`): If set, VTK will compile 235 just its compile tools for use in a cross-compile build. 236 * `VTK_SERIAL_TESTS_USE_MPIEXEC` (default `OFF`): Used on HPC to run 237 serial tests on compute nodes. If set, it prefixes serial tests with 238 "${MPIEXEC_EXECUTABLE}" "${MPIEXEC_NUMPROC_FLAG}" "1" ${MPIEXEC_PREFLAGS} 239 * `VTK_WINDOWS_PYTHON_DEBUGGABLE` (default `OFF`): Set to `ON` if using a 240 debug build of Python. 241 * `VTK_DLL_PATHS` (default `""`): If set, these paths will be added via 242 Python 3.8's `os.add_dll_directory` mechanism in order to find dependent 243 DLLs when loading VTK's Python modules. 244 * `VTK_ENABLE_VR_COLLABORATION` (default `OFF`): If `ON`, includes support 245 for multi client VR collaboration. Requires libzmq and cppzmq external libraries. 246 * `VTK_SMP_ENABLE_<backend_name>` (default `OFF` if needs an external library otherwise `ON`): 247 If set, builds with the specified SMPTools backend implementation that can be 248 changed on runtime with `VTK_SMP_BACKEND_IN_USE` environment variable. 249 * `VTK_USE_VIDEO_FOR_WINDOWS` (default `OFF`; requires Windows): Enable the 250 `vtkAVIWriter` class in the `VTK::IOMovie` module. 251 * `VTK_USE_VIDEO_FOR_WINDOWS_CAPTURE` (default `OFF`; requires Windows): 252 Enable the `vtkWin32VideoSource` class in the `VTK::IOVideo` module. 253 * `VTK_USE_MICROSOFT_MEDIA_FOUNDATION` (default `OFF`; requires Windows): 254 Enable the `vtkMP4Writer` class in the `VTK::IOMovie` module. 255 * `VTK_USE_64BIT_TIMESTAMPS` (default `OFF`; forced on for 64-bit builds): 256 Build with 64-bit `vtkMTimeType`. 257 * `VTK_USE_64BIT_IDS` (default `OFF` for 32-bit builds; `ON` for 64-bit 258 builds): Whether `vtkIdType` should be 32-bit or 64-bit. 259 * `VTK_DEBUG_LEAKS` (default `OFF`): Whether VTK will report leaked 260 `vtkObject` instances at process destruction or not. 261 * `VTK_DEBUG_RANGE_ITERATORS` (default `OFF`; requires a `Debug` build): 262 Detect errors with `for-range` iterators in VTK (note that this is very 263 slow). 264 * `VTK_ALWAYS_OPTIMIZE_ARRAY_ITERATORS` (default `OFF`; requires `NOT 265 VTK_DEBUG_RANGE_ITERATORS`): Optimize `for-range` array iterators even in 266 `Debug` builds. 267 * `VTK_ALL_NEW_OBJECT_FACTORY` (default `OFF`): If `ON`, classes using 268 `vtkStandardNewMacro` will use `vtkObjectFactoryNewMacro` allowing 269 overrides to be available even when not explicitly requested through 270 `vtkObjectFactoryNewMacro` or `vtkAbstractObjectFactoryNewMacro`. 271 272The VTK module system provides a number of variables to control modules which 273are not otherwise controlled by the other options provided. 274 275 * `VTK_MODULE_USE_EXTERNAL_<name>` (default depends on `VTK_USE_EXTERNAL`): 276 Use an external source for the named third-party module rather than the 277 copy contained within the VTK source tree. 278 279 > **_WARNING:_** 280 > 281 > Activating this option within an interactive cmake configuration (i.e. ccmake, cmake-gui) 282 > could end up finding libraries in the standard locations rather than copies 283 > in non-standard locations. 284 > 285 > It is recommended to pass the variables necessary to find the intended external package to 286 > the first configure to avoid finding unintended copies of the external package. 287 > The variables which matter depend on the package being found, but those ending with 288 > `_LIBRARY` and `_INCLUDE_DIR` as well as the general CMake `find_package` variables ending 289 > with `_DIR` and `_ROOT` are likely candidates. 290 > 291 > ``` 292 > Example: 293 > ccmake -D HDF5_ROOT:PATH=/home/user/myhdf5 ../vtk/sources 294 > ``` 295 296 * `VTK_MODULE_ENABLE_<name>` (default `DEFAULT`): Change the build settings 297 for the named module. Valid values are those for the module system's build 298 settings (see below). 299 * `VTK_GROUP_ENABLE_<name>` (default `DEFAULT`): Change the default build 300 settings for modules belonging to the named group. Valid values are those 301 for the module system's build settings (see below). 302 303For variables which use the module system's build settings, the valid values are as follows: 304 305 * `YES`: Require the module to be built. 306 * `WANT`: Build the module if possible. 307 * `DEFAULT`: Use the settings by the module's groups and 308 `VTK_BUILD_ALL_MODULES`. 309 * `DONT_WANT`: Don't build the module unless required as a dependency. 310 * `NO`: Do not build the module. 311 312If any `YES` module requires a `NO` module, an error is raised. 313 314#### Mobile devices 315 316VTK supports mobile devices in its build. These are triggered by a top-level 317flag which then exposes some settings for a cross-compiled VTK that is 318controlled from the top-level build. 319 320iOS builds may be enabled by setting the `VTK_IOS_BUILD` option. The following 321settings than affect the iOS build: 322 323 * `IOS_SIMULATOR_ARCHITECTURES` 324 * `IOS_DEVICE_ARCHITECTURES` 325 * `IOS_DEPLOYMENT_TARGET` 326 * `IOS_EMBED_BITCODE` 327 328Android builds may be enabled by setting the `VTK_ANDROID_BUILD` option. The 329following settings affect the Android build: 330 331 * `ANDROID_NDK` 332 * `ANDROID_NATIVE_API_LEVEL` 333 * `ANDROID_ARCH_ABI` 334 335#### Python wheels 336 337VTK also supports creating a Python wheel containing its Python wrappers for 338Python3 (Python2 wheels are no longer supported). This is supported by setting 339the `VTK_WHEEL_BUILD` flag. This changes the build directory structure around 340to match that expected by wheels. Once configured, the build tree may be built 341as it would be normally and then the generated `setup.py` file used to create 342the wheel. 343 344```sh 345cmake -GNinja -DVTK_WHEEL_BUILD=ON -DVTK_WRAP_PYTHON=ON path/to/vtk/source 346ninja 347python3 setup.py bdist_wheel 348``` 349 350Any modules may be turned on or off as in a normal VTK build. Certain modules 351add features to the generated wheel to indicate their availability. These flags 352are not meant to be comprehensive, but any reasonable feature flags may be 353added to `CMake/vtkWheelFinalization.cmake` as needed. 354 355Note that the wheel will not include any external third party libraries in its 356wheel (e.g., X11, OpenGL, etc.) to avoid conflicts with systems or other wheels 357doing the same. 358 359## Building documentation 360 361The following targets are used to build documentation for VTK: 362 363 * `DoxygenDoc` - build the doxygen documentation from VTK's C++ source files. 364 365[cmake]: https://cmake.org 366[cmake-download]: https://cmake.org/download 367[cmake-find_package-search]: https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure 368[cmake-modules-find]: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules 369[cuda]: https://developer.nvidia.com/cuda-zone 370[ffmpeg]: https://ffmpeg.org 371[git]: https://git-scm.org 372[mesa]: https://www.mesa3d.org 373[mpi]: https://www.mcs.anl.gov/research/projects/mpi 374[ninja]: https://ninja-build.org 375[msmpi]: https://docs.microsoft.com/en-us/message-passing-interface/microsoft-mpi 376[mpich]: https://www.mpich.org 377[nvpipe]: https://github.com/NVIDIA/NvPipe 378[openmpi]: https://www.open-mpi.org 379[python]: https://python.org 380[qt]: https://qt.io 381[qt-download]: https://download.qt.io/official_releases/qt 382[visual-studio]: https://visualstudio.microsoft.com/vs 383