Compiling VTK requires a complete VTK source tree. Running VTK tests requires a complete VTK data tree. Now is the time to extract the source and data archives if one has not done so already. These instructions assume there is a directory "VTK" containing the source code and optionally a sibling directory "VTKData" containing the data.

Building with CMake

CMake must be run to generate a build system for VTK. The build system may be placed either in the VTK source tree (an in-source build) or in a separate binary tree (an out-of-source build). We strongly encourage use of out-of-source builds because they make it easy to have multiple builds with different configurations sharing the same source tree. Once a single in-source build has been created it is the only build tree that can be associated with that source tree. A source tree may not be used both for an in-source build and an out-of-source build, but any number of out-of-source builds may share a source tree that does not have an in-source build. Having multiple out-of-source builds is particularly useful for installing VTK on multiple architectures using a single source tree on a shared disk.

CMake provides both a command-line tool and interactive interfaces. Advanced users may wish to use the command-line tool but here we document the CMake interactive interface for each platform:

• Windows
  

    Run the CMakeSetup dialog to get started.  It must be executed
    from an environment configured to run the compiler to be used.
    In the case of the Visual Studio IDE no special environment is
    needed and CMakeSetup can be started from its icon.  In the case
    of a Visual Studio NMake, Borland C++, or MinGW build the
    CMakeSetup dialog should be executed from a command prompt with
    the appropriate environment set.
    <p>
    The dialog prompts for the location of the source and binary
    trees.  There may also be prompt for the build system generator
    to be used ("Build For:").  Once these are set then CMake is
    ready for a first pass at configuring the VTK build system.  Use
    the "Configure" button to initiate this process.  If there was
    no earlier prompt for the build system generator a separate
    dialog will appear during the first configuration step to prompt
    for generator selection.  After a while the dialog will present
    a set of configuration options.  
    See <a href="#Configuration">below</a> for details on the meaning of
    each of these options.  After setting the options as desired
    press "Configure" again to make another pass at configuring VTK.
    New options may appear when earlier options are adjusted.  Keep
    adjusting options and pressing "Configure" until the desired
    configuration is reached.  Finally press the "Generate" button
    to actually generate the build system.
    <p>
    Now that the build system has been generated the corresponding
    native tools can be used to build VTK.  In the case of the
    Visual Studio IDE simply run it and load the VTK workspace or
    solution file from the binary tree specified in the CMakeSetup
    dialog.  Select and build the <code>ALL_BUILD</code> target.  In
    the case of a Visual Studio NMake, Borland C++, or MinGW build
    use the corresponding make tool (<code>nmake</code>,
    <code>make</code>, and <code>make</code>, respectively) from the
    command line.

• UNIX / Cygwin / Mac OSX
  

    CMake should be run from the command line on these platforms.
    The current working directory should be set to the desired
    binary tree location in which the build system should be
    generated.  One command-line argument is used to specify the
    location of the source tree.  CMake will usually choose the
    system C and C++ compilers automatically but it can be told to
    use specific compilers through the "<code>CC</code>" and
    "<code>CXX</code>" environment variables.
    <p>
    A typical in-source build for VTK might look like this:
    <blockquote>
      <code>
       $ ls -d VTK<br>
       VTK/<br>
       $ cd VTK<br>
       $ ccmake .<br>
       $ make<br>
      </code>
    </blockquote>
    A typical out-of-source build for VTK might look like this:
    <blockquote>
      <code>
       $ ls -d VTK<br>
       VTK/<br>
       $ mkdir VTK-build<br>
       $ cd VTK-build<br>
       $ ccmake ../VTK<br>
       $ make<br>
      </code>
    </blockquote>
    In the above examples the call to <code>ccmake</code> may be
    replaced by
    <blockquote>
      <code>
       $ env CC=/your/c/compiler CXX=/your/C++/compiler ccmake /path/to/VTK<br>
      </code>
    </blockquote>
    in order to tell CMake to use specific C and C++ compilers.
    Setting the environment in this way will only change the
    compilers the <i>first</i> time CMake is run for a specific
    build tree.  Do not attempt to change the compiler of an
    existing build tree.  Instead one should create a separate build
    tree for each desired compiler.
    <p>
    The <code>ccmake</code> tool is a curses-based dialog that may
    be used to interactively configure VTK.  When it appears press
    'c' on the keyboard to run the initial configuration of the VTK
    build system.  Eventually a set of configuration options will
    appear.  These may be edited using the arrow-keys and the ENTER
    key for navigation.  See <a href="#Configuration">below</a> for
    details on the meaning of each of these options.
    <p>
    Once the options have been set as desired press 'c' again to
    reconfigure.  New options may appear when earlier options are
    adjusted.  Keep adjusting options and pressing 'c' until the
    desired configuration is reached.  Finally press 'g' to actually
    generate the build system.  Now that the build system has been
    generated just run <code>make</code> or <code>gmake</code> to
    build VTK.
    <p>
    NOTE: The <code>ccmake</code> curses dialog is the most commonly
    used interactive interface for CMake on UNIX-like platforms, so
    these instructions assume it is available.  Some system
    administrators may not have installed curses in which case
    <code>ccmake</code> will not be available.  On these platforms
    one may use the command "<code>cmake -i</code>" in place of
    <code>ccmake</code> and follow the on-screen instructions to
    configure VTK.  A last resort is to use the command-line
    interface to <code>cmake</code>, but that is beyond the scope of
    this document.  See CMake documentation for further details.

The interactive CMake interface provides brief documentation for every option. Some options have more meaning than can be described in one sentence, so additional documentation is provided here:

• BUILD_SHARED_LIBS
  

  Sets whether the compiled VTK libraries will be shared libraries or static libraries. When linking executables against static libraries the needed symbols will be copied from the libraries into the executables enabling them to run without access to the original libraries. When linking executables against shared libraries references to the symbols are placed into the executables. This has the advantage that many executables can share a large library without producing many copies of its code.

  Shared libraries have the disadvantage that they must be found at runtime in order for an executable to run. Each operating system supporting shared libraries has a component known as the dynamic loader. This component is responsible for finding the shared libraries needed by an executable when it is run. In order to run VTK executables from the build tree when using shared libraries one may need to help the dynamic loader find the libraries (usually the bin subdirectory of the build tree).

  On Windows, the dynamic loader will look for shared libraries in the directory containing the executable, in directories listed in the PATH environment variable, and in some system directories. Since VTK places all of its executables and libraries in the same directory nothing needs to be set to get them to run. However, when one builds outside projects against VTK the PATH environment variable must be set to point at the directory containing the VTK shared libraries.

  On UNIX-style platforms, the dynamic loader will use an environment variable such as LD_LIBRARY_PATH (Linux and many UNIX systems) or DYLD_LIBRARY_PATH (Mac OSX) to look for shared libraries. In order to run VTK executables from the build tree one must set the appropriate environment variable to point at the directory containing the VTK shared libraries. The same environment setting must be used for running outside projects build against the shared VTK libraries.

• VTK_WRAP_TCL
  

  <p>
  Enable/Disable automatic generation of VTK bindings in the Tcl
  language.  In order to build the Tcl-based VTK interpreter one
  will need to have Tcl and Tk version 8.2 or newer. Look to
  
    <a href="http://www.tcl.tk">http://www.tcl.tk</a>
  
  for information about getting Tcl and Tk. To turn on Tcl wrapping,
  set VTK_WRAP_TCL to ON during the configuration process.  One may
  then have to set the values for Tcl/Tk include directories and
  libraries during the next CMake configure iteration.  If there is
  more than one version of Tcl installed on the computer, make sure
  all the TCL_* and TK_* configuration options are set consistently
  to use the proper version.  This is especially important when
  Cygwin is installed because the Cygwin Tcl will not work for a
  native Windows VTK build and a Windows Tcl will not work for a
  Cygwin VTK build.  When building the Tcl/Tk wrappers on Cygwin one
  must also install the Cygwin sources for Tcl/Tk and set
  TK_XLIB_PATH to "/usr/src/tcltk-20030901-1/tk/xlib" or the
  corresponding directory for one's Cygwin Tcl version.  See
  
    <a href="Wrapping/Tcl/README">Wrapping/Tcl/README</a>
  
  for details on using the Tcl wrappers once they are built.
  </p>

• VTK_WRAP_PYTHON
  

  <p>
  Enable/Disable automatic generation of VTK bindings in the Python
  language.  In order to build the Python-based VTK interpreter one
  will need to have Python installed. Look to
  
    <a href="http://www.python.org">http://www.python.org</a>
  
  for information about getting Python.  To turn on Python wrapping,
  set VTK_WRAP_PYTHON and BUILD_SHARED_LIBS to ON during the
  configuration process.  One may then have to set the values for
  Python include directories and libraries during the next CMake
  configure iteration.  If there is more than one version of Python
  installed on the computer, make sure all the PYTHON_*
  configuration options are set consistently to use the proper
  version.  This is especially important when Cygwin is installed
  because the Cygwin Python will not work for a native Windows VTK
  build and a Windows Python will not work for a Cygwin VTK build.
  In order to use Tkinter with VTK-Python make sure that the Tcl/Tk
  libraries that are set correspond to the same version used by
  Tkinter.
  </p>
  <p>
  Note that the VTK-Python modules are now installed by default via
  'make install', which is a change from previous VTK versions.  The
  automatic python module installation is highly configurable. The
  <a href="Wrapping/Python/README.txt">Wrapping/Python/README.txt</a>
  file documents the installation procedure and the VTK-Python
  modules.
  </p>

• CMAKE_INSTALL_PREFIX
  

  When VTK is installed all files are placed in a directory structure rooted at the directory specified by CMAKE_INSTALL_PREFIX.

Installation

Installing VTK from a source distribution requires first that it be compiled in a build tree. See the <a href="#Compilation">compilation section above for details. Once VTK has been compiled in a build tree one may build the install target to actually put VTK in an installation tree. If VTK was built using a CMake Makefile generator then this is done by running "make install" from the top of the build tree. If VTK was built using a CMake project file generator (such as Visual Studio), then building the INSTALL project from inside the IDE will install VTK. The installation process will install all files in a directory structure rooted at the directory specified by CMAKE_INSTALL_PREFIX.