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 wrapper-generators at compile time.

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 some classes that 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 hierarchy file for each class header file (depends only on the header file)
3. vtkBuildHierarchy reads vtkKitHierachy.data (and the files from kit dependencies) and builds a hierarchy file in memory but does not write it
4. vtkBuildHierarchy checks against the existing vtkKitHierarchy.txt file, replaces it only 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
• vtkBuildHierarchy will be a custom executable that can read the stubs, weed out duplicates, read the output file, and only write the output file if it will change
• vtkParseHierarchy.c will be a module that can be linked to wrapper-generators, it will have code for reading the hierarchy file
• vtkParse.y will have a new --hierarchy option so that the hierarchy file can be given on the command-line

The Execution

The tools described above are now part of WrapVTK. There are some tricky dependency issues that I have to work out before they are merged into VTK. Here are the features:

• the hierarchy file for each kit includes all classes of dependency kits, i.e. Filtering also includes Common classes
• the hierarchy file is only re-written when the hierarchy changes, which eliminates needless re-builds of the wrappers
• vtkParseHierarchy has the following methods:
  • HierarchyInfo *readHierarchyFile(const char *filename); // read a hierarchy file and return a data structure
  • void freeHierarchyInfo(HierarchyInfo *info); // free a hierarchy data structure
  • int isHierarchySuperClass(HierarchyInfo *info, const char *subclass, const char *superclass);
  • const char *getHierarchyClassHeader(HierarchyInfo *info, const char *classname);

The method names might change. I'm considering vtkParseHierarchy_ReadFile(), vtkParseHeirarchy_Free(), vtkParseHierarchy_IsSubClass(), vtkParseHierarchy_ClassHeader(). This naming scheme would make it obvious that the functions are defined in the vtkParseHierarchy module.