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 that lists all the header files to be wrapped for the kit
2. vtkWrapHierarchy generates hierarchy info by parsing all header files in vtkKitHierarchy.data and by reading the hierarchy files from other kits, i.e. vtkFilteringHierarchy.txt will include a copy of vtkCommonHierarchy.txt
3. vtkWrapHierarchy checks against the existing vtkKitHierarchy.txt file, replaces it only if the hierarchy has changed
4. any wrappers commands that need hierarchy info depend on the vtkKitHeirarchy file, and take it as a --heirarchy argument.

Notes:

• vtkWrapHierarchy will be like vtkWrapPython et al. except that it will read several headers and produce just a single file per kit
• vtkWrapHierarchy will only write a new output file if the hierarchy has changed (it pre-reads the output file in order to check this)
• 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.