2.2. VTK-m Version

As the VTK‑m code evolves, changes to the interface and behavior will inevitably happen. Consequently, code that links into VTK‑m might need a specific version of VTK‑m or changes its behavior based on what version of VTK‑m it is using. To facilitate this, VTK‑m software is managed with a versioning system and advertises its version in multiple ways. As with many software products, VTK‑m has three version numbers: major, minor, and patch. The major version represents significant changes in the VTK‑m implementation and interface. Changes in the major version include backward incompatible changes. The minor version represents added functionality. Generally, changes in the minor version to not introduce changes to the API. The patch version represents fixes provided after a release occurs. Patch versions represent minimal change and do not add features.

If you are writing a software package that is managed by CMake and load VTK‑m with the find_package() command as described in Section 1.2.4 (Linking to VTK‑m), then you can query the VTK‑m version directly in the CMake configuration. When you load VTK‑m with find_package(), CMake sets the variables VTKm_VERSION_MAJOR, VTKm_VERSION_MINOR, and VTKm_VERSION_PATCH to the major, minor, and patch versions, respectively. Additionally, VTKm_VERSION is set to the “major.minor” version number and VTKm_VERSION_FULL is set to the “major.minor.patch” version number. If the current version of VTK‑m is actually a development version that is in between releases of VTK‑m, then and abbreviated SHA of the git commit is also included as part of VTKm_VERSION_FULL.

Did You Know?

If you have a specific version of VTK‑m required for your software, you can also use the version option to the find_package() CMake command. The find_package() command takes an optional version argument that causes the command to fail if the wrong version of the package is found.

It is also possible to query the VTK‑m version directly in your code through preprocessor macros. The vtkm/Version.h header file defines the following preprocessor macros to identify the VTK‑m version.

VTKM_VERSION

The version number of the loaded VTK‑m package. This is in the form “major.minor”.

VTKM_VERSION_FULL

The extended version number of the VTK‑m package including patch and in-between-release information. This is in the form “major.minor.patch[.gitsha1]” where “gitsha” is only included if the source code is in between releases.

VTKM_VERSION_MAJOR

The major VTK‑m version number.

VTKM_VERSION_MINOR

The minor VTK‑m version number.

VTKM_VERSION_PATCH

The patch VTK‑m version number.

Common Errors

Note that the CMake variables all begin with VTKm_ (lowercase “m”) whereas the preprocessor macros begin with VTKM_ (all uppercase). This follows the respective conventions of CMake variables and preprocessor macros.

Note that vtkm/Version.h does not include any other VTK‑m header files. This gives your code a chance to load, query, and react to the VTK‑m version before loading any VTK‑m code proper.