6. What is a config-site file?

There are a number of flagship compute platforms across the HPC/CSE community upon which VisIt is routinely built. For many of these systems, VisIt developers themselves or key collaborators take responsibility for building VisIt there. We call these managed installations of VisIt. For each managed installation, we maintain a set of platform-specific CMake variables in a file in src/config-site/<hostname>.cmake. These files are called config-site files. They offer a simple, short-hand for specifying a slew of CMake variables when building VisIt.

In this section, we explain how a config-site file is organized and what various of the different types of variables used there mean. One key thing to understand is that VisIt’s CMake build logic pre-dates many of the more modern and useful features of CMake as well as the adoption of CMake support by a number of third party library (TPL) providers VisIt relies upon.

The first lines of a config-site file are a set of comments capturing some high-level information about the build the file supports.

  • The path to the cmake binary executable used to configure VisIt and the included TPLs.

  • How the config-site file was created. Often it is generated by build_visit but it can also be manually created.

  • The hostname, architecture and OS.

#/Users/miller86/visit/visit/release-hdf520/build-bar/thirdparty_shared/third_party/cmake/3.31.8/darwin-arm64/bin/cmake
##
## /Users/miller86/visit/visit/src/tools/dev/scripts/build_visit generated host.cmake
## created: Wed Mar  4 17:51:17 PST 2026
## system: Darwin sce2aux 24.6.0 Darwin Kernel Version 24.6.0: Mon Jan 19 22:00:55 PST 2026; root:xnu-11417.140.69.708.3~1/RELEASE_ARM64_T6000 arm64
## by: miller86

The next lines define CMake variables for the installation home directory and the architecture.

##
## Setup VISITHOME & VISITARCH variables.
##
SET(VISITHOME /Users/foobar/visit/release/build/thirdparty_shared/third_party)
SET(VISITARCH darwin-arm64)

The next lines capture information about the compilers and compiler flags.

##
## Compiler flags.
##
VISIT_OPTION_DEFAULT(VISIT_C_COMPILER clang TYPE FILEPATH)
VISIT_OPTION_DEFAULT(VISIT_CXX_COMPILER clang++ TYPE FILEPATH)
VISIT_OPTION_DEFAULT(VISIT_FORTRAN_COMPILER no TYPE FILEPATH)
VISIT_OPTION_DEFAULT(VISIT_C_FLAGS "-fno-common -fexceptions" TYPE STRING)
VISIT_OPTION_DEFAULT(VISIT_CXX_FLAGS "-fno-common -fexceptions" TYPE STRING)

If the config-site file supports building a parallel-enabled VisIt, the next lines capture information the MPI compiler path.

##
## Parallel Build Setup.
##
VISIT_OPTION_DEFAULT(VISIT_PARALLEL ON TYPE BOOL)
## (configured w/ mpi compiler wrapper)
VISIT_OPTION_DEFAULT(VISIT_MPI_COMPILER /Users/foobar/visit/release/build/thirdparty_shared/third_party/mpich/3.3.1/darwin-arm64/bin/mpicc TYPE FILEPATH)

The remaining lines of a config-site file capture information about each TPL used in the build. The typical way to enable support for a specific TPL involves a handfule of lines such as those below…

##
## Gorfo
##
SETUP_APP_VERSION(GORFO 1.2.3)
VISIT_OPTION_DEFAULT(VISIT_GORFO_DIR ${VISITHOME}/gorfo/${GORFO_VERSION}/${VISITARCH})
VISIT_OPTION_DEFAULT(VISIT_GORFO_LIBDEP abc xyz TYPE STRING)

##
## FooBar
##
SETUP_APP_VERSION(FOOBAR 6.7.8)
VISIT_OPTION_DEFAULT(VISIT_FOOBAR_DIR ${VISITHOME}/foobar/${FOOBAR_VERSION}/${VISITARCH})
VISIT_OPTION_DEFAULT(VISIT_FOOBAR_LIBDEP gorfo HDF5_LIB TYPE STRING)

The first line indicates the version number of the TPL. The second line indicates the location of the TPL installation. This is typically always ${VISITHOME}/<package-name>/<package-version-number>/${VISITARCH}.

The third line defines a library dependence (_LIBDEP) variable. The third line is only necessary when the TPL does not provide CMake import targets useable by VisIt. Starting with VisIt version 3.5.1, VisIt will either import a TPL’s libraries natively using their provided CMake targets, or manually create import targets from the TPL’s known libraries. Library dependencies in the third line will either be listed as their imported target name or via a place-holder CMake variable that can point to different library names based on how VisIt is being built. In the example above, Gorfo depends on two libraries: abc and xyz, which are either native or VisIt created CMake targets. FooBar depends on gorfo (a CMake target) and HDF5 which is represented by the CMake variable HDF5_LIB. HDF5_LIB will hold the imported target name for the HDF5 library, which will typically be hdf5-shared but may be hdf5-static.

If build_visit is used to build VisIt’s TPLs, then it will create the config-site file for the TPL installation once the build is completed.

7. Building Directly with CMake

If a config site file is available for the platform you wish to build on, VisIt can often be built without the use of the build_visit script, with these steps.

git clone --recursive git@github.com:visit-dav/visit.git
mkdir visit/build
cd visit/build

If build_visit was used to build VisIt on the platform in the past, it should have created a cmake file specific to your machine which we call a config site file. CMake simply needs to be told where to find it using the -DVISIT_CONFIG_SITE option. Examples of config site files for a variety of machines VisIt developers directly support can be found in the config-site directory.

/path/to/cmake -DVISIT_CONFIG_SITE="/path/to/your_computer.cmake" ../src
make -j

For cases where a config-site file will not be used, this must be explicitly indicated by passing -DVISIT_CONFIG_SITE=NONE. This is useful in cases where -C CMakeCache.txt is used, or where all the relevant CMake variables are specified on the command line to CMake itself instead of a config-site file.

/path/to/cmake -C /path/to/CMakeCache.txt -DVISIT_CONFIG_SITE=NONE ../src
make -j

7.1. CMake Variables

The following CMake vars can be modified to suit your build needs.

When specified via a command line invocation of CMake, they should be specified as: VARNAME:TYPE=value, eg “VISIT_BUILD_ALL_PLUGINS:BOOL=ON”.

The defaults listed are the settings used if the Variable has not been set in a config-site file.

7.1.1. Controlling major components being built

VISIT_DBIO_ONLYBOOLOFF

Toggles building of only visitconvert and engine plugins.

VISIT_ENGINE_ONLYBOOLOFF

Toggles building of only the compute engine and its plugins.

VISIT_SERVER_COMPONENTS_ONLYBOOLOFF

Build only vcl, mdserver, engine and their plugins.

VISIT_ENABLE_LIBSIMBOOLON

Toggles building of libsim.

7.1.2. Controlling plugins being built

VISIT_BUILD_ALL_PLUGINSBOOLOFF

Toggles the building of all plugins. When turned on the following optional plugins will be added to the build:

Database: PICS_Tester, Rect

Operator: Context ConnCompReduce, MetricThreshold, RemoveCells, SurfCompPrep

Plot: Topology

Note: the list of optional plugins is subject to change.

VISIT_BUILD_MINIMAL_PLUGINSBOOLOFF

Toggles the building of a minimal set of database, operator, and plot plugins. When turned on, only the following plugins will be built:

Database: Curve2D, RAW, VTK, PICS_Tester

Operator: Lineout, Slice, Threshold

Plot: Curve, Mesh, Pseudocolor

Note: the list of minimal plugins is subject to change.

VISIT_SELECTED_DATABASE_PLUGINSSTRING

“;” separated list of database plugins to build, eg: VTK;Silo

If not empty, will supersede the settings of VISIT_BUILD_MINIMAL_PLUGINS and VISIT_BUILD_ALL_PLUGINS for database plugins.

VISIT_SELECTED_OPERATOR_PLUGINSSTRING

“;” separated list of operator plugins to build, eg: Slice;Lineout;Transform

If not empty, will supersede the settings of VISIT_BUILD_MINIMAL_PLUGINS and VISIT_BUILD_ALL_PLUGINS for operator plugins.

VISIT_SELECTED_PLOT_PLUGINSSTRING

“;” separated list of plot plugins to build, eg: Mesh;Pseudocolor

If not empty, will supersede the settings of VISIT_BUILD_MINIMAL_PLUGINS and VISIT_BUILD_ALL_PLUGINS for plot plugins.

7.1.3. Controlling extra tools being built

VISIT_ENABLE_ANNOTATION_TOOLSBOOLON

Toggles the generation of annotation tools: text2polys, time_annotation.

VISIT_ENABLE_DATAGENBOOL: ON

Toggles the generation of sample data files.

VISIT_ENABLE_DATA_MANUAL_EXAMPLES: BOOLOFF

Toggles generation of Getting Data Into Visit examples.

VISIT_ENABLE_DIAGNOSTICSBOOLON

Toggles building of diagnostic tools: exceptiontest, mpitest, networktest, osmesatest.

VISIT_ENABLE_MANUALSBOOLON

Toggles building of manuals, requires Sphinx in Python.

VISIT_ENABLE_SILO_TOOLSBOOLON

Toggles building of Silo tools: mrgtree2dot, add_visit_searchpath.

VISIT_ENABLE_UNIT_TESTSBOOLON

Toggles building of unit tests: MRUCache, Namescheme, Utilty, StringHelpers, exprconfig, exprtest.

7.1.4. Useful for developers

VISIT_CREATE_SOCKET_RELAY_EXECUTABLE: BOOLON

Toggles creation of separate executable that forwards VisIt’s socket connection between engine and component launcher.

VISIT_CREATE_XMLTOOLS_GEN_TARGETSBOOLON

Toggles the creation of build targets to run xmltools code generation. More information can be found in the XML Tools section of the Developer Manual

Be careful on Windows, all of the codegen targets will be built unless you tell Visual Studio to build the ALL_BUILD project (instead of the Solution). This will cause a lot of source files to be regenerated and may cause problems with the build.

VISIT_RPATH_RELATIVE_TO_EXECUTABLE_PATHBOOLOFF

Install rpath relative to executable location using $ORIGIN tag.

CMAKE_SUPPRESS_REGENERATIONBOOLOFF

When on, tells CMake to suppress regeneration of project/make files when CMakeLists.txt or .cmake files have changed.

7.1.5. Miscellany

CMAKE_BUILD_TYPESTRINGRelease

Specifies the build type for single-configuration generators (like Makefiles).

CMAKE_INSTALL_PREFIXPATHdefault is system dependent

Specifies the location for files installed with make install.

IGNORE_THIRD_PARTY_LIB_PROBLEMSBOOLOFF

Ignore problems finding requested third party libraries.

VISIT_CONFIG_SITEFILEPATH${VISIT_SOURCE_DIR}/config-site/<localhost>.cmake

Location of a config-site cmake file that has settings to control the build, including locations of third party libraries. Created automatically by build_visit script.

VISIT_DDTBOOLOFF

Toggles support for the DDT debugger.

VISIT_DEFAULT_SILO_DRIVERSTRINGPDB

Designates the default Silo driver to use when generating silo data. Options: PDB, HDF5

VISIT_DISABLE_SELECTBOOLOFF

Toggles the disablement for use of the select() function.

VISIT_FORCE_SSH_TUNNELINGBOOLOFF

Toggles use of SSH tunneling for sockets.

VISIT_FORTRANBOOLOFF

Toggles building of Fortran example programs.

VISIT_INSTALL_THIRD_PARTYBOOLOFF

Install VisIt’s 3rd part I/O libraries and includes to permit plugin development.

VISIT_JAVABOOLOFF

Build VisIt’s Java client interface.

VISIT_NOLINK_MPI_WITH_LIBRARIESBOOLOFF

Do not link MPI with VisIt’s parallel shared libraries; just with executables

VISIT_PARALLELBOOLON

Build VisIt’s parallel compute engine.

VISIT_PYTHON_SCRIPTINGBOOLON

Build VisIt with Python scripting support.

VISIT_PYTHON_FILTERSBOOLON

Build VisIt with Python Engine Filter support.

VISIT_SLIVRBOOLON

Build VisIt with support for the SLIVR volume rendering library.

VISIT_STATICBOOLOFF

Build VisIt statically.

7.1.6. macOS only

VISIT_CREATE_APPBUNDLE_PACKAGEBOOLOFF

Toggles creation of DMG file with Mac App bundle with make package.

7.1.7. Windows OS only

VISIT_MAKE_NSIS_INSTALLERBOOLOFF

Toggles creation of an installer package using NSIS.

The windows.cmake config-site file turns this ON.

VISIT_MESA_REPLACE_OPENGLBOOLOFF

Toggles use of Mesa as a drop-in replacement for OpenGL when system OpenGL is insufficient.

The windows.cmake config-site file turns this ON.

VISIT_WINDOWS_APPLICATIONBOOLON

Toggles creation of Windows-style applications with no console.

VISIT_WINDOWS_DIRPATH :

Specifies the location of the prebuilt third party library binaries. See Location of windowsbuild directory for default locations.