Building plugins using CMake

The procedure for building a plugin against an installed version of VisIt is slightly different than in the old build system. You must run xml2cmake to generate CMake input for your plugin before you can run cmake to generate Makefiles, etc.

The examples shown below are for database plugins. You could generate plot or operator plugins using the same basic procedure. Be sure to substitute plots for the directory name when building a plot and use operators for the directory name when you build an operator plugin.

Building within the VisIt src tree

This is the method you would use if you are compiling a plugin against a version of VisIt that you have just built from sources and have not installed. Since you have not installed VisIt, you will need to locate your plugin directory in the src/databases (or src/plots or src/operators) directory with the rest of VisIt's plugin sources. This will ensure that you can successfully tie the build of your plugin into VisIt's build process. If you don't want to do this then you'll need to install VisIt and follow the instructions for building against an installed version of VisIt since the procedure is different.

Note that the MyPlugin directory name is just a stand-in for the name you will really use. Also note that you will need to place your plugin into the appropriate parent directory (databases, plots, operators), depending on its type.

# Change directories into the plugin directory that you've created. You will need to
# have copied your plugin sources to this directory as well.
cd databases/MyPlugin

# Generate the CMakeLists.txt file
../../bin/xml2cmake -clobber MyPlugin.xml

# Add the file to SVN if it has not been added already
svn add CMakeLists.txt

Use your favorite text editor to edit src/databases/CMakeLists.txt and add MyPlugin to the 
REQUIRED_XXX_PLUGINS variable (where XXX is DATABASE, PLOT, OPERATOR). This makes your plugin
part of the VisIt build process. Save your changes.

# Build VisIt and it will build your plugin
cd ../..
cmake .
make

IMPORTANT: be sure to use ../../bin/xml2cmake only and not the installed version of xml2cmake or your CMakeLists.txt file will contain unwanted lines of code that are only to be used when building a plugin against an installed version of VisIt. Don't mess up and check in the wrong type of CMakeLists.txt into SVN.

Building against an installed version of VisIt

This method assumes you have installed VisIt from a binary distribution or using "make install" after building from sources. If you are building against installed versions of VisIt that you did not build then you must use the same compilers as were used to build the VisIt against which you are linking.

For Mac:

  • 10.5 uses gcc 4.0.1
  • 10.6 uses gcc 4.2.1
  • There are not Mac binaries for other versions of VisIt so you can't build against the installed version of VisIt
  • If you downloaded the Mac bundle, then the path to xml2cmake is VisIt.app/Contents/Resources/bin/xml2cmake, rooted wherever your VisIt.app bundle is installed.

It is important that VisIt is installed for this method since it will provide crucial files necessary for your generated CMakeLists.txt to be able to build stand-alone. These examples assume VisIt and xml2cmake were installed and are in your path.

  • Build your plugin and store it as a user-only plugin in your ~/.visit/plugins directory
cd MyPlugin
# Generate the CMakeLists.txt file
xml2cmake -clobber MyPlugin.xml
# Build your plugin against the installed VisIt
cmake .
make VERBOSE=1
  • Or, build your plugin and store it as a public plugin which installs into the directory where VisIt was installed. You will need write access to VisIt's plugin directories for this operation. Note that the only difference is that you pass a -public flag when you run xml2cmake.
cd MyPlugin
# Generate the CMakeLists.txt file
xml2cmake -clobber -public MyPlugin.xml
# Build your plugin against the installed VisIt
cmake .
make VERBOSE=1

Windows

  • On Windows, you must open a command prompt to the directory where your plugin is stored. Then tell CMake to use the same generator that was used to build VisIt (Visual Studio + version). There are two options: directly using the VisIt.cmake file installed with VisIt; or reading that file to get the correct version of Visual Studio.
# Generate the CMakeLists.txt file
xml2cmake.exe -clobber MyPlugin.xml

# Generate project files using one of the two options:
# option 1 (make sure you specify the appropriate path to where VisIt is installed)
cmake.exe -C "C:\Program Files\LLNL\VisIt 2.5.0\include\VisItGenerator.cmake" .

# option 2 (having read the value in VisItGenerator.cmake)
cmake.exe -G "Visual Studio 10 Win64" .

# Build:  either open MyPlugin.sln with the Visual Studio IDE or use the command line:
devenv.exe /BUILD Release MyPlugin.sln

Building a newer version of a plugin

Sometimes fixes have been made to plugins on the VisIt trunk but the code won't appear in a VisIt release for some time and you can't wait to use the fix. In this situation, it is usually possible to build the fixed plugin yourself if you have the right development tools.

This example shows how to check out the current svn trunk version of an operator, in this case PersistentParticles, and build it yourself against your installed version of VisIt. Since the newly compiled operator will be put into a plugin directory in your ~/.visit directory, you can have a custom version of the operator plugin without disturbing the VisIt installation. This pattern applies to any operator, plot, or database plugin.

svn co http://portal.nersc.gov/svn/visit/trunk/src/operators/PersistentParticles
cd PersistentParticles/
xml2cmake -clobber PersistentParticles.xml
xml2info -clobber PersistentParticles.xml
cmake -DCMAKE_BUILD_TYPE:STRING=Release .
make

Building a plugin against a new version of a third party library (TPL)

Note, this may introduce issues for other plugins that use the same TPL (e.g. HDF5 library is used by ~15 plugins).

Sometimes, you want to build the same plugin but use a newer version of the associated TPL. To do this, follow all the steps above but, then search for relevant TPL variables in the PluginVsInstall.cmake file in the VisIt installation you are building the plugin against. That file is usually found at <prefix>/X.Y.Z/<arch>include/PluginVsInstall.cmake. Then, manually edit the CMakeLists.txt file for the plugin that was produced by xml2cmake and include SET() commands after the INCLUDE() command that includes PluginVsInstall.cmake to specify the (new) paths to find the newer version of the TPL you want to use.

For example, to do a recent re-build of the Mili plugin against a newer version of the Mili library, I edited the CMakeLists.txt for the Mili plugin like so...

original CMakeLists.txt

SET(VISIT_INCLUDE_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include")
SET(VISIT_LIBRARY_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/lib")
SET(VISIT_BINARY_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/bin")
SET(VISIT_ARCHIVE_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/archives")
SET(VISIT_PLUGIN_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/plugins")
INCLUDE("/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include/PluginVsInstall.cmake")
INCLUDE("/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include/VisItLibraryDependencies.cmake")

modified CMakeLists.txt

SET(VISIT_INCLUDE_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include")
SET(VISIT_LIBRARY_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/lib")
SET(VISIT_BINARY_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/bin")
SET(VISIT_ARCHIVE_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/archives")
SET(VISIT_PLUGIN_DIR "/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/plugins")
INCLUDE("/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include/PluginVsInstall.cmake")
INCLUDE("/usr/gapps/visit/2.6.3/linux_x86_64-gcc-4.4/include/VisItLibraryDependencies.cmake")

SET(MILI_INCLUDE_DIR /usr/gapps/visit/thirdparty_shared_2_6_0/mili/13.1/linux_x86_64-gcc-4.4/include)
SET(MILI_LIBRARY_DIR /usr/gapps/visit/thirdparty_shared_2_6_0/mili/13.1/linux_x86_64-gcc-4.4/lib)

Then, re-run the cmake command to produce updated Makefiles.