.. _Building Directly with CMake: 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/.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. .. code:: cmake #/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. .. code:: cmake ## ## 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. .. code:: cmake ## ## 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. .. code:: cmake ## ## 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... .. code:: cmake ## ## 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 /path/to/abc/lib abc /path/to/xyz/lib 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 ${VISIT_GORFO_LIBDEP} 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}///${VISITARCH}``. The third line is only necessary when the TPL has a dependence on another TPL. This line defines a *library dependence* (``_LIBDEP``) variable. In the example above, the Gorfo depends on two libraries, abc, and xyz and FooBar depends on Gorfo and HDF5. The ``_LIBDEP`` variable can be populated with one of a few different kinds of references. The first kind is a *pair* of space separated entries as is seen in ``VISIT_GORFO_LIBDEP``. The first entry in the pair is the path to a directory holding library such as would be used in a ``-L`` linker flag. The second entry in the pair is the name of the library such as would be used in a ``-l`` linker flag. The second kind is a CMake variable representing a bona fide CMake *imported target*. For all TPLs VisIt supports, only a few (HDF5, Silo, ZLIB) are currently handled as bona fide CMake imported targets. This situation will improve to include many more TPLs as imported targets but currently (as of version 3.5.0), only a handful of TPLs are handled this way. The variable, ``HDF5_LIB`` is the variable which holds the imported target name for the HDF5 library (typically ``hdf5-shared``). A third kind is the CMake variable representing all the dependencies of another TPL. In the example above, ``VISIT_FOOBAR_LIBDEP`` indicates FooBar depends on Gorfo using the ``${VISIT_GORFO_LIBDEP}`` which is interpreted to mean that because FooBar depends on Gorfo, then FooBar depends on all the libraries that Gorfo depends on. Sometimes, there is a 4th kind of line for a TPL involving *include dependencies*. This is needed when the TPL not only has a link-time dependence on another library but also a compile-time dependence. The line will appear as ``VISIT_OPTION_DEFAULT(VISIT_GORFO_INCDEP HDF5_INCLUDE_DIR FMS_INCLUDE_DIR)``. 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. 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. .. code:: bash 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. .. code:: bash /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. .. code:: bash /path/to/cmake -C /path/to/CMakeCache.txt -DVISIT_CONFIG_SITE=NONE ../src make -j .. _CMake Variables: 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. Controlling major components being built """""""""""""""""""""""""""""""""""""""" VISIT_DBIO_ONLY : BOOL : OFF Toggles building of only visitconvert and engine plugins. VISIT_ENGINE_ONLY : BOOL : OFF Toggles building of only the compute engine and its plugins. VISIT_SERVER_COMPONENTS_ONLY : BOOL : OFF Build only vcl, mdserver, engine and their plugins. VISIT_ENABLE_LIBSIM : BOOL : ON Toggles building of libsim. Controlling plugins being built """"""""""""""""""""""""""""""" VISIT_BUILD_ALL_PLUGINS : BOOL : OFF 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_PLUGINS : BOOL : OFF 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_PLUGINS : STRING ';' 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_PLUGINS : STRING ';' 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_PLUGINS : STRING ';' 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. Controlling extra tools being built """"""""""""""""""""""""""""""""""" VISIT_ENABLE_ANNOTATION_TOOLS : BOOL : ON Toggles the generation of annotation tools: text2polys, time_annotation. VISIT_ENABLE_DATAGEN : BOOL: ON Toggles the generation of sample data files. VISIT_ENABLE_DATA_MANUAL_EXAMPLES: BOOL : OFF Toggles generation of :ref:`Getting Data Into Visit` examples. VISIT_ENABLE_DIAGNOSTICS : BOOL : ON Toggles building of diagnostic tools: exceptiontest, mpitest, networktest, osmesatest. VISIT_ENABLE_MANUALS : BOOL : ON Toggles building of manuals, requires Sphinx in Python. VISIT_ENABLE_SILO_TOOLS : BOOL : ON Toggles building of Silo tools: mrgtree2dot, add_visit_searchpath. VISIT_ENABLE_UNIT_TESTS : BOOL : ON Toggles building of unit tests: MRUCache, Namescheme, Utilty, StringHelpers, exprconfig, exprtest. Useful for developers """"""""""""""""""""" VISIT_CREATE_SOCKET_RELAY_EXECUTABLE: BOOL : ON Toggles creation of separate executable that forwards VisIt_'s socket connection between engine and component launcher. VISIT_CREATE_XMLTOOLS_GEN_TARGETS : BOOL : ON Toggles the creation of build targets to run xmltools code generation. More information can be found in the :ref:`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_PATH : BOOL : OFF Install rpath relative to executable location using \$ORIGIN tag. CMAKE_SUPPRESS_REGENERATION : BOOL : OFF When on, tells CMake to suppress regeneration of project/make files when CMakeLists.txt or .cmake files have changed. Miscellany """""""""" CMAKE_BUILD_TYPE : STRING : Release Specifies the build type for single-configuration generators (like Makefiles). CMAKE_INSTALL_PREFIX : PATH : *default is system dependent* Specifies the location for files installed with *make install.* IGNORE_THIRD_PARTY_LIB_PROBLEMS : BOOL : OFF Ignore problems finding requested third party libraries. VISIT_CONFIG_SITE : FILEPATH : ${VISIT_SOURCE_DIR}/config-site/.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_DDT : BOOL : OFF Toggles support for the DDT debugger. VISIT_DEFAULT_SILO_DRIVER : STRING : PDB Designates the default Silo driver to use when generating silo data. Options: PDB, HDF5 VISIT_DISABLE_SELECT : BOOL : OFF Toggles the disablement for use of the select() function. VISIT_FORCE_SSH_TUNNELING : BOOL : OFF Toggles use of SSH tunneling for sockets. VISIT_FORTRAN : BOOL : OFF Toggles building of Fortran example programs. VISIT_INSTALL_THIRD_PARTY : BOOL : OFF Install VisIt_'s 3rd part I/O libraries and includes to permit plugin development. VISIT_JAVA : BOOL : OFF Build VisIt_'s Java client interface. VISIT_NOLINK_MPI_WITH_LIBRARIES : BOOL : OFF Do not link MPI with VisIt_'s parallel shared libraries; just with executables VISIT_PARALLEL : BOOL : ON Build VisIt_'s parallel compute engine. VISIT_PYTHON_SCRIPTING : BOOL : ON Build VisIt_ with Python scripting support. VISIT_PYTHON_FILTERS : BOOL : ON Build VisIt_ with Python Engine Filter support. VISIT_SLIVR : BOOL : ON Build VisIt_ with support for the SLIVR volume rendering library. VISIT_STATIC : BOOL : OFF Build VisIt_ statically. macOS only """""""""" VISIT_CREATE_APPBUNDLE_PACKAGE : BOOL : OFF Toggles creation of DMG file with Mac App bundle with make package. Windows OS only """"""""""""""" VISIT_MAKE_NSIS_INSTALLER : BOOL : OFF Toggles creation of an installer package using NSIS. The windows.cmake *config-site* file turns this ON. VISIT_MESA_REPLACE_OPENGL : BOOL : OFF 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_APPLICATION : BOOL : ON Toggles creation of Windows-style applications with no console. VISIT_WINDOWS_DIR : PATH : Specifies the location of the prebuilt third party library binaries. See :ref:`Location of windowsbuild directory` for default locations.