Improve deprecation support for moved or renamed headers
VTK-m has a deprecation method that supports API changes in minor releases. When an API change is made, the old API is marked with the VTKM_DEPRECATED macro. If code attempts to use the old API, it still works, but the compiler issues a warning that the thing is deprecated and where to find the new API.
We have recently run into an issue when the API changes have a header file renamed or moved. We still keep the old header file with the old API, so code including that file will still work. However, sometimes code expected the contents of that header file without directly including that header file. In these cases, the code could get an error about missing classes.
As an example, consider the change from DynamicCellSet
to
UnknownCellSet
/UncertainCellSet
. The deprecated DynamicCellSet
is
still around. But there is a lot of code that did not directly include
DynamicCellSet.h. This header file was necessarily included by
DataSet.h. Now, when this code uses vtkm::cont::DynamicCellSet
, you
get a confusing error that the class does not exist. Backward
compatibility broken.
In response to this, we should be more careful about where we put the
deprecated API. Instead of containing the deprecated API, moved headers
should be empty except for a warning and an inclusion of the new header
file. The deprecated API should be moved to the new header file. For
example, in the case of DynamicCellSet
, the implementation for the
deprecated DynamicCellSet
is moved to UnknownCellSet.h, which is
included by anything that was including DynamicCellSet.h before.