Adding a new IO library

This page lists the steps required to add a new I/O library to VisIt, though it is all applicable to 3rd party libraries in general except for where database plugins are mentioned.

Adding a new I/O library consists of several steps:

  1. Check the library's source tarball into trunk/third_party
  2. Modifying build_visit to build the new library
  3. Modifying VisIt's build system to be aware of the new library

build_visit

Modifying build_visit to be a new I/O library entails:

  1. Setting up environment variables to be accessed by various routines
  2. Tests to see if the source code is available
  3. A routine to build from the source code
  4. Modifying the code that creates a config-site file.
  5. Modifying the user interface (both graphical and text) to be aware of your new library. This includes adding a new command line argument so your new library can be selected when building from the console.
  6. And instructing the main code to do the build.

If you issue:

tkdiff -r 3208 3210 /src/svn_bin/build_visit

... you can see an example of this change for the FastBit library.

Make sure you also test build_visit on

  • Linux
  • MacOS X

Windows

You will need to build your library using Visual Studio and check in the DLL files and header files into VisIt's trunk/windowsbuild directory so other users can continue to easily build VisIt on Windows. If you do not do this step then you had better be adding an optional library or else you will break Windows builds.

Adding a new library to the build system

Enhancing VisIt's build system so that it is aware of a new library consists of a few easy steps. The steps to add a hypothetical library called libIO will be covered here.

Writing a Find routine

In order for VisIt to locate a 3rd party library, you must add a Find module for it. Find modules are located in VisIt's source code tree in the src/CMake directory. Most Find modules are very simple and leverage existing macros that VisIt provides in order to locate modules and ensure that they get installed as part of build targets such as make package.

To create a Find module for a hypothetical libIO you would create a new file called src/CMake/FindIO.cmake. The file's contents would look like the following:

INCLUDE(${VISIT_SOURCE_DIR}/CMake/SetUpThirdParty.cmake)
SET_UP_THIRD_PARTY(IO lib include IO)
  • All references to IO would use your library name (e.g. HDF5, CGNS, and so on)

The SET_UP_THIRD_PARTY macro is used to generate more complex CMake code that can locate the IO library and make sure it gets installed when VisIt is installed, etc. The arguments to SET_UP_THIRD_PARTY are as follows:

Argument Description
IO This is the name of the library and it will be used to create variables such as IO_FOUND, IO_INCLUDE_DIR, IO_LIBRARY_DIR, IO_LIB that can be used later in your plugin's XML file.
lib This is the name of the directory containing libIO.a (or libIO.so, libIO.dylib, ...) within an installation of the libIO library.
include This is the name of the include directory containing the libIO header files within an installation of the libIO library.
IO This is the base name of the library file and is used to construct the filename in which the library is located ("lib" + "IO" + ".so")

Once you have created your Find module, you might want to make it be an svn element and check it into the VisIt source code so other developers can use it.

Adding to top-level CMakeLists.txt

Now that you have added your Find routine for the IO library, you will want to make some changes to the top-level CMake file that enable it to use your Find routine. In addition, you will also add an option for CMake so you will be able to set the location of the IO library via the cmake command line.

In order to make VisIt's build include your find routine, add the following lines to the top-level CMakeLists.txt file (src/CMakeLists.txt). Look for similar lines in the file around line 1000.

# Configure IO support.
INCLUDE(${VISIT_SOURCE_DIR}/CMake/FindIO.cmake)
IF(IO_FOUND)
    SET(HAVE_LIBIO 1)
ENDIF(IO_FOUND)

In order to add an option to cmake, add lines like this to the top-level CMakeLists.txt file (src/CMakeLists.txt) around line 610.

VISIT_3RDPARTY_VAR(IO_DIR      "Path containing the IO library's include and lib")
VISIT_3RDPARTY_DEP(IO_LIBDEP   "IO library dependencies")

The VISIT_3RDPARTY_VAR macro adds an option to cmake that lets you specify the location of your IO library on the cmake command line.

cmake -DIO_DIR=/path/to/my/libio/directory .

The VISIT_3RDPARTY_DEP macro specifes any 3rd party library dependencies for libIO.

Edit databases/CMakeLists.txt

Once you have created a Find routine and added it to the top-level CMakeLists.txt file, you can now edit the database CMakeLists.txt file to add new plugins that depend on libIO. Since your libIO library is now a full-fledge 3rd party library, you can use the THIRDPARTY_DEPENDENT_PLUGINS macro in the databases/CMakeLists.txt file to add plugins that depend on libIO. Add a line like this to the file:

THIRDPARTY_DEPENDENT_PLUGINS(IO myplugin)

The above macro uses means that if library "IO" is found during VisIt's cmake step, then add "myplugin" to the build. If you have more than one plugin that needs to link to libIO, simply write a space-separated list of plugin names instead of "myplugin".

Use CMake variables in your plugin XML file

Now that the VisIt build system has been enhanced to support libIO, you may now create plugins that use libIO. Remember that plugins in VisIt use an XML-based system to contain information about the plugin. This information is used to generate the CMakeLists.txt file that your plugin uses. In order to make your plugin use the libIO library, you'll need reference the libIO library within the XML file (since that ultimately allows CMakeLists.txt to be autogenerated).

Remember also that your find routine caused several libIO-related variables to be created: IO_FOUND, IO_INCLUDE_DIR, IO_LIBRARY_DIR, IO_LIB. Use these cmake variables within your XML file instead of hard-coding any libIO-related values.

This snippet of XML can be inserted into your plugin's XML file before you run xml2cmake to generate the final CMakeLists.txt file:

   <CXXFLAGS> 
     ${IO_INCLUDE_DIR} 
   </CXXFLAGS>
   <LDFLAGS>  
     ${IO_LIBRARY_DIR} 
   </LDFLAGS>
   <LIBS>     
     ${IO_LIB} 
   </LIBS>