Build visit overview


Jump to: navigation, search

VisIt can now be built automatically using the build_visit script on many Linux, MacOS X, and AIX platforms (more to come). The build_visit script takes care of downloading relevant VisIt and 3rd party source code, configuring, and building it all using your C++ compiler. We encourage users to build VisIt using the build_visit script when our binary distributions have trouble running on some systems. We also recommend using the build_visit script on your system if you plan to:

  • Modify the VisIt source code.
  • Run a parallel compute engine. Building a parallel version of VisIt on your system allows you to configure VisIt so it uses your MPI library, avoiding incompatibilities.
  • Create your own VisIt plugins. Building VisIt on your system ensures that it is built with the same C++ compiler that you will use to develop your plugin, minimizing the chance for runtime library incompatibilities.
  • Use Libsim for in situ computations


[edit] Running build_visit

Build_visit has both a Command-Line Interface (CLI) and a Graphical User Interface (GUI). That's also some environment variables that can influence the default behavior of build_visit.

[edit] Background

The VisIt build process is quite complex, there are several very large external libraries with are required before the VisIt build can even be attempted. In addition there are over a dozen optional external libraries needed to support additional database readers. Each of these libraries introduces its own unique build procedure. The build_visit script attempts to mediate these differences for the user and build the user desired combination of VisIt features entirely under-the-covers. With maybe the exception of VTK version 5.0 library, which required a substantial number of changed to the Kitware source in order to function correctly, the third party libraries are unchanged from their distributed sources. Note that the Mesa library is still using a mangled version 5.0 for Linux only, because it seems to reduces the number of device driver compatibility problems experienced by Linux systems. Note also that Mili hasn't been released as open source, so is only available in the VisIt binary distributions. The specific versions of the the external libraries used have been conveniently copied into the VisIt web site as well as the SVN site svn+ssh:// Note as of this writing the SVN site has not enabled for anonymous access. The default versions of the external libraries have been tested, and known to work with VisIt, however newer versions of the libraries should work equally well.

[edit] Required 3rd-party libraries

The following table contains the required external libraries and the approximate version version number used by build_visit.

  • The version numbers used may be more recent than those listed here.

  Library  Version   Description            For More Information
  =======  =======   ===========            ====================
   Mesa     7.10.2    3-D Graphics Library
   Qt       4.8.3     GUI Toolkit 
   CMake    3.0.2     Make file generation
   VTK      6.1.0     Visualization Toolkit
   Python   2.7.6     Scripting Language
   Silo     4.10.1    File I/O library

[edit] Optional 3rd-party libraries

The following is a table of optional external libraries, and the default version number used by build_visit:

   Library  Version  Description           For More Information
   ======== =======  ===========           ====================
   Boxlib   1.0.7    An AMR I/O library / 
   CCMIO    2.6.1    File I/O library
   CFITSIO  3006     File I/O library
   CGNS     3.2.1    File I/O library    
   GDAL     1.10.0   GIS reader library
   H5Part   1.6.6    I/O library 
   HDF4     4.2.5    I/O library 
   HDF5     1.8.7    I/O library 
   Mili     1.09     I/O library           NOT RELEASED
   netCDF   4.1.1    File I/O library
   szip     2.1      szip-2.1.tar.gz

[edit] The build process

The build_visit script will use the above tables' versions of external libraries. By default, build_visit will download the required and optional tarballs from the VisIt web site. Assuming (for simplicity sake) that build_visit exists in the current working directory, all the library tarballs will be downloaded to the current working directory. The user can either manually copy (download) the external libraries into current working directory, or let build_visit automatically download them from the VisIt web site or from the SVN site (see note above). During the build_visit process, an intermediate install directory is created in the current working directory called visit. Each of the external packages get compiled and installed into a directory prefix of visit/PACKAGE/VERSION/ARCH/, where PACKAGE is one of the possible values (in lower case) from the Library column in the above tables. VERSION is replaced by the Version value from the table, and ARCH is information specific to the system architecture which did the compile. The build of VisIt begins after all of the external libraries have successfully built. The first step in that process will be the creation of a host.conf file, which contains the location of the libraries that were built above. This host.conf file significantly reduces the number of arguments needed by VisIt's configure script. It can also save time in subsequent VisIt builds, obviating the need to build the external 3rd-party libraries altogether.

[edit] Graphical User interface

Some users are more comfortable with a GUI interface. The build_visit script optionally uses dialog, a script-interpreter which providing a set of curses widgets, similar to the what is used in Linux kernel configuration. Dialog will present variety of build options and display build progress messages using dialog boxes. Because dialog uses curses it can be run from most ascii terminals (e.g. xterm) and terminal emulators. You'll need a terminal size of at least 24 rows (even that few has been known to cause problems on older version of dialog, so the more rows the better), and 80 columns. Dialog is included in most Linux distributions, however it is not included on MacOS X. A source distribution of dialog is available from, and a pre-built Universal binary can be downloaded by entering
curl -k -O
Note: you may need to restore the execute permissions after downloading with chmod +x dialog.

When a dialog executable is in the users PATH, then simply entering ./build_visit, will present the user with the initial VisIt build options menu (Main) containing checklist, and 2 buttons. Menu Navigation

  • Use the Up-arrow and Down-arrow to move the cursor up or down through the checklist.
  • Pressing an alphanumeric key that corresponding with the high-lighted letter in a checklist label will move the cursor to that line.
  • Use the Space bar to toggle the state of a checklist.
  • Use the Tab key to select between the OK and Cancel button.
  • Return will execute which ever button is high-lighted (OK, or Cancel).
  • Cancel will exit the menu, quiting the build-visit.

[edit] GUI Menu Examples

The build_visit GUI menus.

[edit] Build Options Menu (Main, startup checklist)


The Build options menu contains a checklist for the following build option titles: Optional, SVN, Tarball, Parallel, Python, Java, SLIVR, Variables, and More.

[edit] Select 3rd party libraries checklist (Main->Optional)


Checking Optional (pre-checked by default) in the Build Options checklist will bring up the Select 3rd party libraries menu. From this menu you can select which optional 3rd-party libraries to download, build, and install. This menu contains a checklist with the following options: Boxlib, CCMIO, CFITSIO, CGNS, ExodusII, GDAL, H5Part, HDF4, HDF5, Mili, and NetCDF.

[edit] More build options checklist (Main->More)


Checking the More option in the Build Options checklist will bring up the More build options menu which contains: Version, Build, Required, Logging, Symbol, Group, Path, Absolute, Trace. Checking the Version, Group, or Path options brings up another menu containing a text input box (see below).


Example of text entry box for changing the visit version to download.

[edit] Parallel compiling menus (Main->Parallel)


Checking the Parallel build option in the Build Options checklist will bring up menus that allow setting of the of CPPFLAGS and LDFLAGS with the necessary information for MPI. Selecting the No button will produce a another menu containing a text input box (see below).


After entering changes and hitting the OK button, you'll be returned to the previous menu (The CPPFLAGS for MPI are). Hitting the Yes button in that menu will display the LDFLAGS menu (see below).


The LDFLAGS menu behaves the same as the CPPFLAGS menu.

[edit] Variable settings checklist (Main->Variables)


Checking the Variables option brings up the Variable settings checklist containing various system dependent defaults and environmental variables including: OPSYS, ARCH, C_COMPILER, CXX_COMPILER, C_OPT_FLAGS, CXX_OPT_FLAGS, VISITARCH, and REVISION. Checking any option will bring up another menu containing a text input box to change the value.

[edit] Qt license acknowledgment menu (The last interactive menu)


If Qt is being built, a Yes-No menu is displayed for acknowledgment the conditions of Troll Tech's licensing.

After acknowledging, the build process commences, which starts with downloading of the requested tarballs, then building the required libraries, followed by optional 3rd party libraries. Each library build will display an information dialog box as to the progress of the build (usually something like; downloading, configuring, building, installing). Note: the estimated build times can be very, very, very, optimistic. Upon completetion of the install of the last external library, the host.conf file is generated followed by the building of VisIt. When the VisIt build completes the build_visit script exits. You can either run VisIt from the build directory or run visit-bin-dist to create a binary distribution tarball, followed by running visit-install to install VisIt into a another location.

[edit] GUI Menu Build Options

Detailed explanation of menu options.

[edit] Build Options Menu (Main)

The options on the Build Options Menu.

[edit] Optional

Brings up the Select 3rd party libraries checklist menu.

[edit] SVN (-s CLI option)

Use the SVN server to get the VisIt distribution and well as any needed 3rd party libraries. Use the environment variable SVN_NERSC_NAME for the user name to login to the SVN server if the name is different from the local systems.

[edit] Tarball (-t CLI option, VISIT_FILE env variable)

Brings up the More Variable setting menu. Override the default the VisIt tarball, the user will have to provide the name of the VisIt tarball to build. Usually, the tarball will be in the current directory. If a previous release is desired VISIT_VERSION environment variable or Version option on the More Variable setting menu.

[edit] Parallel (-p CLI option, PAR_INCLUDE and PAR_LIBS env variables)

Checking the Parallel option on the checklist will bring up a series of Parallel compiling menus for setting the CPPFLAGS, and LDFLAGS for inclusion of MPI. The environment variables PAR_INCLUDE and PAR_LIBS can be used to pre-define or help set the CPPFLAGS, and LDFLAGS values.

[edit] Python (-w CLI option)

Enables the building of VisIt's Python module.

[edit] Java (-y CLI option)

Enables the building of the Java client library.

[edit] SLIVR (-S CLI option)

Enables building of the SLIVR hardware-accelerated volume rendering library from SCI, University of Utah.

[edit] Variables

Brings up the Variable settings checklist menu.

[edit] More

Brings up the More build options checklist menu.

[edit] Select 3rd party libraries checklist menu

Detailed explanation of the Select 3rd party libraries checklist menu options.

[edit] Boxlib (--boxlib CLI option, BOXLIB_FILE, BOXLIB_VERSION, and BOXLIB_DIR env variables)

Download, build, and install the [Boxlib] library, an adaptive mesh refinement (AMR) framework. VisIt reads both 2D and 3D versions of the data file format.

[edit] CCMIO (--ccmio CLI option, CCMIO_FILE, CCMIO_VERSION, and CCMIO_DIR env variables)

Download, build, and install the CD-adapco CCM file I/O library.

[edit] CFITSIO (--cfitsio CLI option, CFITSIO_FILE, CFITSIO_VERSION, and CFITSIO_DIR env variables)

Download, build, and install [FITS] (Flexible Image Transport System), the standard astronomical data format endorsed by both NASA and the IAU. FITS is much more than an image format (such as JPG or GIF) and is primarily designed to store scientific data sets consisting of multi-dimensional arrays (1-D spectra, 2-D images or 3-D data cubes) and 2-dimensional tables containing rows and columns of data.

[edit] CGNS (--cgns CLI option, CGNS_FILE, CGNS_VERSION, and CGNS_DIR env variables)

Download, build, and install [CGNS] (CFD General Notation System) library for the storage and retrieval of CFD (computational fluid dynamics) data.

[edit] ExodusII (--exodus CLI option, EXODUS_FILE, EXODUS_VERSION, and EXODUS_DIR env variables)

Download, build, and install [EXODUS II] is a model developed to store and retrieve transient data for finite element analyses. It is used for preprocessing, postprocessing, as well as code to code data transfer. ExodusII is based on netcdf. Includes the nemesis parallel extension.

[edit] GDAL (--gdal CLI option, GDAL_FILE, GDAL_VERSION, and GDAL_DIR env variables)

Download, build, and install [GDAL] (Geospatial Data Abstraction Library) library, a translator library for raster geospatial (Geographic Information System, GIS) data formats.

[edit] H5Part (--h5part CLI option, H5PART_FILE, H5PART_VERSION, and H5PART_DIR env variables)

Download, build, and install [H5Part] library that read HDF5 part files.

[edit] HDF4 (--hdf4 CLI option, HDF4_FILE, HDF4_VERSION, and HDF4_DIR env variables)

Download, build, and install [HDF4] library is a API for storing scientific data.

[edit] HDF5 (--hdf5 CLI option, HDF5_FILE, HDF5_VERSION, and HDF5_DIR env variables)

Download, build, and install [HDF5] library is a API for management of extremely large and complex data collections.

[edit] Mili (--mili CLI option, MILI_FILE, MILI_VERSION, and BV_MILI_DIR env variables)

Download, build, and install Mili file I/O library. Mili hasn't been released as open source, is currently only available as pre-built binaries, or the SVN server which doesn't allow anonymous access.

[edit] NetCDF (--netcdf CLI option, NETCDF_FILE, NETCDF_VERSION, and NETCDF_DIR env variables)

Download, build, and install [NetCDF] (network Common Data Form) library, an interface for array-oriented data access.

[edit] More build options checklist menu

Detailed explanation of the More build options checklist menu options.

[edit] Version (--version CLI option, VISIT_VERSION env variable)

This variable will change the default version of VisIt to build. Changing this variable has a side-effect of also changing the name of the VisIt tar-ball to use. By default the VisIt tar-ball will be named visitVISIT_VERSION.tar.gz, and try and download from Use this option to build a previous release of VisIt. Selecting this option will present a text input dialog box for setting the value.

[edit] Required (--no-thirdparty CLI option)

This option will disable the download, and building of the required 3rd party libraries. The option can be useful in generation or installing new optional libraries, or used in combination with the above Build option.

[edit] Path (--thirdparty-path CLI option, THIRD_PARTY_PATH env variable)

This variable determines the root directory for the installation of the 3rd party libraries. By default the root directory will be in a directory called visit in the current working directory (e.g., THIRD_PARTY_PATH=./visit). If build_visit finds a library has a corresponding THIRD_PARTY_PATH/PACKAGE/VERSION/ARCH/ already existing, then it is assumed that the library is already built, and build_visit proceeds to the next library. Subsequent builds of new VisIt releases can reuse these previously built external libraries. This option allows the user can override the default location of the intermediate install directory, creating a permanent install locations (such as /usr/gapps/visit/PACKAGE/VERSION/ARCH). Selecting this option will present a text input dialog box for setting the value.

[edit] Absolute (--absolute CLI option)

Macintosh specific. This option changes the behavior of the install name path for the dynamic libraries. Enabling this flag will used the THIRD_PARTY_PATH path for creating an absolute path to the dynamic libraries, instead the default relative path @executable_path/../lib.

[edit] Variable settings checklist menu

Detailed explanation of the Variable settings checklist menu options.

[edit] ARCH (ARCH env variable)

This option will construct a system description string, something like: OPSYS-uname -m or uname -p-uname -suname -r. Used to construct the VISITARCH value. Selecting this option will present a text input dialog box for setting the value.

[edit] C_COMPILER (C_COMPILER env variable)

The C compiler to used for building 3rd party libraries and VisIt. Selecting this option will present a text input dialog box for setting the value.

[edit] CXX_COMPILER (CXX_COMPILER env variable)

The C++ compiler to used for building 3rd party libraries and VisIt. Selecting this option will present a text input dialog box for setting the value.

[edit] C_OPT_FLAGS (C_OPT_FLAGS env variable)

The C compiler options to used for building 3rd party libraries and VisIt. Selecting this option will present a text input dialog box for setting the value.

[edit] CXX_OPT_FLAGS (CXX_OPT_FLAGS env variable)

The C++ compiler options to used for building 3rd party libraries and VisIt. Selecting this option will present a text input dialog box for setting the value.

[edit] VISITARCH (-a CLI option, VISITARCH env variable)

This option will over-ride the value used for the architecture information string used in constructing the 3rd party library path (usually something like: linux_gcc-3.4.6, i386-apple-darwin8, or ARCH_C_COMPILER). Selecting this option will present a text input dialog box for setting the value.

[edit] REVISION (-R CLI option, SVNREVISION env variable)

This option provides the specific SVN revision information to checkout from the SVN archive. Selecting this option will present a text input dialog box for setting the value.

[edit] Command-line interface

The command-line interface (CLI) can be used in conjunction with the GUI interface for example to pre-select checklist options, or entirely non-interactively (i.e., batch mode). The CLI determines build options by parsing a list of parameters following the build_visit command. This parameter list contains options, and option-arguments. The arguments that consist of hyphens and single letters or digits, such as --hdf5, are known as options (or, historically, flags). Certain options are followed by an option-argument, as shown with --cflags "-g". Options and option-arguments are specified as follows:

  • All options are preceded by the "--" delimiter characters.
  • Each option and option-argument combination is a separate argument (e.g., separated by white-space).
  • Option-arguments are not optional.
  • The order of different options relative to one another does not matter.
  • Options are interpreted in the order that they are specified. If an option that has option-arguments is repeated, the option and option-argument combinations will be interpreted in the order specified on the command line (e.g., the last repeated option-argument wins).

[edit] Command-line interface Help

The list of available options can be displayed by entering: ./build_visit -h

Usage: svn_bin/build_visit [options]
A download attempt will be made for all files which do not exist.

        These are used to enable or disable specific functionality.  They do not take option values.

--boxlib        Build Boxlib [no]
--ccmio         Build Star-CD support [no]
--cfitsio       Build CFITSIO [no]
--cgns          Build CGNS [no]
--cmake         Build CMake [built by default unless --no-thirdparty flag is used]
--console       Do not use dialog ('graphical') interface [!yes]
--debug         Enable debugging for this script [false]
--exodus        Build Exodus (requires NetCDF) [no]
--fastbit       Build FastBit [no]
--flags-debug   Add '-g' to C[XX]FLAGS [false]
--gdal          Build GDAL [no]
--group         Group name of installed libraries [unknown]
--h5part        Build H5Part [no]
--hdf4          Build HDF4 [no]
--hdf5          Build HDF5 [no]
-h              Display this help message. [false]
--help          Display this help message. [false]
--icet          Build Ice-T (parallel rendering lib) [no]
--itaps         Build ITAPS [no]
--java          Build with the Java client library [no]
--mesa          Build Mesa [built by default unless --no-thirdparty flag is used]
--mili          Build Mili [no]
                NOTE: not available for download from web
--netcdf        Build NetCDF [no]
--no-visit      Do not build VisIt, build 3rd party libraries only [yes]
--no-thirdparty Do not build required 3rd party libraries [on]
--no-hostconf   Do not create host.conf file. [on]
--parallel      Enable parallel build, display MPI prompt [no]
--print-vars    Display user settable environment variables [false]
--python        Build Python [built by default unless --no-thirdparty flag is used]
--python-module Build with the VisIt Python module [no]
--qt            Build Qt [built by default unless --no-thirdparty flag is used]
--silo          Build Silo support [no]
--slivr         Build with SLIVR shader support [no]
--stdout        Write build log to stdout [build_visit_log]
--szip          Build with SZIP [no]
--tcmalloc      Build tcmalloc from Google's perftools [no]
                NOTE: not available for download from web
--visus         Build ViSUS (experimental!) [no]
--vtk           Build VTK [built by default unless --no-thirdparty flag is used]
--dbio-only     Disables EVERYTHING but I/O. [no]

These values all take a special value.  If given, they require an associated value to be provided as well.

--absolute </path/to/directory> 
             Change the behavior of the install name path for
             the Darwin dynamic libraries. Enabling this flag
             will used the THIRD_PARTY_PATH path for creating
             an absolute path to the dynamic libraries and not
             use the default relative path. [@executable_path/../lib]
--arch <architecture> Set architecture [i386-apple-darwin8_gcc-4.0.1]
             This variable is used in constructing the 3rd party
             library path; usually set to something like
             'linux_gcc-3.4.6' or 'Darwin_gcc-4.0.1'
--cflags    Explicitly set CFLAGS []
--cxxflags  Explicitly set CXXFLAGS []
--makeflags <flags> Flags to 'make' []
--svn <revision> Obtain <revision> of VisIt source code from the SVN server
            [svn co svn+ssh://]
--tarball <file> tarball to extract VisIt from [visit2.0.0.tar.gz]
--thirdparty-path </path/to/directory> 
             Specify the root directory name under which the 3rd party
             libraries have been installed.  If defined, it would typically
             mean the 3rd party libraries are pre-built and are installed
             somewhere like /usr/gapps/visit. [./visit]
--version <version> The VisIt version to build [2.0.0]

[edit] Command-line interface Examples

Standard build, download from web required 3rd party libraries, and VisIt tar-ball, then build. If dialog exist, then the GUI interface will be presented.


To add the optional 3rd party libraries for HDF4, HDF5, Boxlib, CCMIO, CGNS, Exodus, CFITSIO, GDAL, NetCDF, and H5Part.

./build_visit --hdf4 --hdf5 --boxlib --ccmio --cgns --exodus \
  --cfitsio --gdal --netcdf --h5part

To not build visit, but only build and install the above libraries in to the system accessible directory /usr/gapps/visit, with group owner of visit. In addition a host.conf will be generated.

./build_visit --hdf4 --hdf5 --boxlib --ccmio --cgns --exodus \
  --cfitsio --gdal --netcdf --h5part \
  --no-visit --thirdparty-path /usr/gapps/visit --group visit

Note: Subsequent VisIt builds will by pass the 3rd party library build phase altogether.

Note: for a Macintosh you may want add the --absolute option, so that the internal [dynamic libraries install name] path uses an absolute path and not the default relative path.

To build VisIt, lots of 3rd party libraries, but not bring up the GUI interface, and to display all build status and messages to the stdout instead of the default build_visit_log file:

./build_visit --hdf4 --hdf5 --boxlib --ccmio --cgns --exodus \
  --cfitsio --gdal --netcdf --h5part --console</pre>

[edit] Environment variables

There are a variety of environment variables that can be set by the user to override the default behavior of build_visit. The use of environment variable is rather advanced feature for the casual user, but flexible operations can be performed from the command line with no code changes. A useful operation has been the overriding of the default 3rd party libraries with more recent versions. The process has been tried on a limited range of updates with varying degrees of success (usually depending to the computability of the new library release, and if the new code requires custom patches).

[edit] Environment variables display

Use ./build_visit -E to display the user settable environment variables and their default values.

The following is a list of user settable environment variables for MacOS X10.4.11

C_OPT_FLAGS=-O2 -fno-common -fexceptions
CXX_OPT_FLAGS=-O2 -fno-common -fexceptions

[edit] Environment variables Examples

To try HDF5 version 1.8 instead of the 1.6.6 used default:

env HDF5_FILE="hdf5-1.8.0.tar.gz" HDF5_VERSION="1.8.0" \
HDF5_DIR="hdf5-1.8.0" HDF5_COMPATIBILITY_VERSION="1.8" ./build_visit

In general, the tarball (or untarred directory) needs to exist in the current directory. Variables such as SILO_FILE, SILO_VERSION, SILO_COMPATIBILITY_VERSION (Macintosh specific), and SILO_DIR would need to be defined. To over-ride the default compilers and compiler flags and use the PathScale compiles:

C_OPT_FLAGS="-Ofast -fPIC" CXX_OPT_FLAGS="-Ofast -fPIC"  ./build_visit

To define compile and link flags for parallel compiling:

env PAR_INCLUDE="-I/usr/lib/mpi/include" \
PAR_LIBS="-Wl,-rpath=/usr/lib/mpi/mpi_gnu/lib \
-L/usr/lib/mpi/mpi_gnu/lib -lmpi" ./build_visit

To define compile and link flags for parallel compiling on a Macintosh which uses OpenMPI:

PAR_LIBS="-Wl,-undefined,dynamic_lookup -Wl,-u,_munmap \
-Wl,-multiply_defined,suppress -lmpi_cxx -lmpi -lopen-rte -lopen-pal" ./build_visit

[edit] Specifying compilers

The build_visit script builds many 3rd party libraries in addition to building VisIt. Compilation errors and later runtime errors are less likely if the same compiler is used to build all 3rd party libraries as well as VisIt. The build_visit script will use your default C and C++ compilers for the build. On many systems, the default compiler is gcc. If you want to override the compiler that build_visit will use (e.g. use the Intel compilers), you can do so by setting environment variables prior to running build_visit.

C_COMPILER Set the C compiler that build_visit will use. Example: setenv C_COMPILER icc
C_OPT_FLAGS Specify additional options for the C compiler.
CXX_COMPILER Set the C++ compiler that build_visit will use. Example: setenv CXX_COMPILER g++-4.0.1
CXX_OPT_FLAGS Specify additional options for the C++ compiler.

Also see the GUI interface, and environment variable example.

[edit] Faster builds

When you run build_visit, there is a handful of core libraries that must be built before VisIt is built. Many of the additional 3rd party libraries are optional and they are used only for building database reader plugins. If you do not wish to build those plugins then many of the 3rd party libraries can be omitted from the build, making build_visit complete faster. You should build Silo though since it is VisIt's default file format.

You can also pass the --makeflags option to use parallel make so your build will complete faster if you are building on a multiprocessor computer. Example:
./build_visit --makeflags '-j 4'

[edit] Skeleton for future content

[edit] How to build a parallel version with MPI

[edit] Installing after a build

Personal tools