VTK/WrapHierarchy

WrapHierarchy is a proposed tool for generating a text file (or multiple files) that describe the VTK class hierarchy. The goal is to make the full VTK class hierarchy available to the wrappers at compile time, so that they can do special wrapping of classes depending on their superclasses (or absence of superclasses), even if the superclass in question is several generations from the class that is being wrapped.

Why is this tool useful?

• vtkObjectBase-derived parameters and parameters of vtk "special" types can be handled differently
• certain categories of classes, e.g. array classes, can be given specific features

File Format

The hierarchy file will have the following format:

 vtkObjectBase ; vtkObjectBase.h
 vtkObject : vtkObjectBase ; vtkObject.h
 vtkSimpleMutexLock ; vtkMutexLock.h
 vtkMutexLock : vtkObject ; vtkMutexLock.h
 vtkVariant ; vtkVariant.h

There may be classes are sublassed from STL classes or other third-party classes. There is no problem with this, the superclass will still be listed but the hierarchy above that point will not be available in the file. In the case of multiple inheritance (which will hopefully be very rare) there will be entries like this:

 vtkCrazyClass : vtkObjectBase , boof::baz ; vtkMisnamedHeader.h

How can this be done?

Three pieces are needed:

• a vtkWrapHierarchy executable to read header files and output all classes, superclasses for the file
• a CMake macro to call vtkWrapHierarchy on all VTK classes
• a utility function to read hierarchy files so that the wrappers can use them

A big issue is how to handle dependencies. Having one big hierarchy file could be a problem because a change to any VTK header file would mean that all the wrappers would have to be regenerated. Having a small stub hierarchy file for each class header file means that the wrappers would have to read many small files. A good solution might be to have CMake generate a "temporary" hierarchy file, compare it to the existing file (if one exists), and only replace the existing file if the new file is different. That way, the wrappers will only have to be completely re-generated if the hierarchy changes.

If this is done, then there can be one "hierarchy" file per kit. Even better, the hierarchy file for each kit can be a merger of the kit's classes those of all the dependency kits. That way, the wrappers only have to take in a single file, more-or-less a second "hints" file of sorts called "hierarchy".

Difficulties

Issue 1

Assuming that everything is done according to the scheme outlined above, then some fancy CMake work is needed:

1. the kit wrappers will depend on the "hierarchy" file for the kit
2. the "hierarchy" file will depend on all header files in the kit, and on the "hierarchy" files for all dependency kits

However, we don't want the kit wrappers to depend on all header files. There has to be a break of sorts between 1) and 2), so that the dependency 1) is only triggered if dependency 2) resulted in changes to the hierarchy file.

Issue 2

Merging the hierarchy files. Can CMake do this, or will a separate utility executable be required? The files just have to be concatenated, and then all duplicates have to be removed.

The Plan

The generation of the hierarchy files can be done according to the following scheme:

1. CMake generates a vtkKITHierarchy.data file with all the class names in the kit
2. vtkWrapHierarchy generates a tiny stub .hfc file for each class header file (depends only on the header file)
3. vtkBuildHierarchy takes vtkKITHierachy.data (and the files from kit dependencies) and makes a temporary concatenation of all .hfc files
4. vtkBuildHierarchy checks against the existing vtkKITHierarchy.txt file, replaces it if necessary
5. wrappers that need hierarchy info depend on the vtkKITHeirarchy file, and take it as a --heirarchy argument.

Notes:

• vtkWrapHierarchy will be just like vtkWrapPython or the other wrapper generators
• vtkBuildHeirarchy will be a custom executable that can read the stubs, weed out duplicate entries, check against an pre-existing file, and overwrite the output file if necessary