Installing Database Plugins

Using the visit_plugin tool

To install...

   % visit_plugin -install <plugin-name>

To UNinstall...

   % visit_plugin -uninstall <plugin-name>

where <plugin-name> is something like 'VTK' or 'Tecplot.' Although the plugin file you were sent may have a '.tar.gz', you do not include the '.tar.gz' in the plugin's name in these commands.

If you would like VisIt to test the plugin and automatically uninstall it if the test fails and the visit_plugin tool is available in your installation, give the command...

   % visit_plugin -install . -testrun <Filename>:<PlotType>:<Varname>

Where <Filename> is an absolute or relative path to a file for VisIt to attempt to open and plot, <PlotType> is the name of a VisIt plot such as 'Mesh' or 'Pseudocolor' and <Varname> is the name of a variable in the file. VisIt will build the plugin, install it and then attempt to open the specified file and display the specified plot with the specified variable. If this test fails, VisIt will automatically uninstall the plugin and inform you of the failure. If the tarball we've sent you was test-run'd before we emailed it to you, installing it will automatically behave as described above. That is, it will automatically attempt to run the plugin and, if it cannot, UNinstall it.

Using the manual approach

If the visit_plugin tool is not available, or fails for some reason, you may need to use this appraoch. Untar the plugin tarball...

   % gunzip < <plugin-name>.tar.gz | tar xvf -

To install...

   % cd <plugin-name>
   % xml2makefile -clobber <plugin-name>.xml
   % make

To UNinstall...

   % cd <plugin-name>
   % make clean

Alternatively, you can UNinstall by explicitly removing ALL of the relevant .so's from your .visit directory in your home directory. VisIt installs your database plugins to ~/.visit/<arch>/plugins/databases. So, the following command will remove all instances of the plugin for a given architecture...

   % cd ~/.visit/<arch>/plugins/databases
   % find . -name '*<plugin-name>*.so' -exec rm {} \; -print

For example, to remove all instances of the VTK database plugin for the linux-intel architecture...

   % cd ~/.visit/linux-intel/plugins/databases
   % find . -name '*VTK*.so' -exec rm {} \; -print

Other issues to be aware of

If you are running a version of VisIt that is older than the most current release, be aware there is always a chance the plugin will not install or, once installed, not run correctly. You may be required to update either VisIt and/or the third party I/O library(s) this plugin may require. In general, the VisIt team trys to avoid this situation but depending on where we are in a release cycle, it can crop up and is something to be aware of.

The commands to install and uninstall a plugin create and remove shared libraries in ~/.visit/<arch>/plugins/databases. When VisIt starts up, it looks in ~/.visit/<arch>/plugins/databases for any plugins you have installed in your home directory. We call these 'private' plugins. Then it looks in the public installation directory. In this way, plugins in your home directory override plugins in the public directory. You can disable this behavior by adding '-publicpluginsonly' on the command line to launch VisIt.

Over time, as you install private plugins and/or VisIt, you can wind up having private plugins that are not compatibile with the version of VisIt you are running. VisIt will warn you of this occurance during startup and ignore your private plugin in favor of the public one. To correct this situation, simply uninstall your private plugin following the instructions here.

Installing a database plugin from a binary distribution of VisIt

If you are working with a binary distribution of VisIt (that is, you did not build and install it from sources) or if VisIt was installed on your system without this database plugin and/or the third party libraries it requires, then you will most likely have to use the Manual approach for installing and UNinstalling the plugin. Also, if you know the plugin you are using requires special purpose libraries to read the files, you will have to modify the Makefile that gets created by xml2makefile to specify the location(s) of these libraries. For example, if the name(s) of the required third party libraries were 'foo' and 'bar,' you might do this by editing Makefile and defining something like...

   FOO_INCLUDE="-I/usr/local/foo/include -I/usr/local/bar/include"
   FOO_LIB="-L/usr/local/foo/lib -lfoo -L/usr/local/bar/lib -lbar"

In other words, introduce explicit definitions for the appropriate make variables to point to your local installation of any applicable third party include and library files. A commone example is the HDF5 library where you would need to define HDF5_INCLUDE and HDF5_LIB to get the plugin to link properly.

You would place these lines AFTER the include directive that includes 'make-variables' near the top of the Makefile. Alternatively, you may need to statically link to third party libraries by specifing the complete path to the .a files in FOO_LIB like so...

   FOO_LIB="/usr/local/foo/lib/libfoo.a /usr/local/bar/lib/libbar.a"

If you are unsure as to the necessary make variable names to override, look in 'make-variables' file referenced by the first include directive near the top of the Makefile. There you will find all the make variable names that are used to define locations of third party libraries.

Finally, be aware that sometimes you may need to remove dependency files (named something like .depend or .pardepend or <C++file>.d) in the directory where you are building the plugin to get things to build correctly. This is so becuase the dependency file(s) are generated only when it does not exist, after that, make assumes the dependencies are correct. If you get error messages that look like...

   gmake: *** No rule to make target 'foo.h', needed by
   'somefile.o'.  Stop.

it can never hurt to remove the dependency files(s) and try remaking.