Create views of OpenCASCADE objects in the Debugger
eryar@163.com
Abstract. The Visual Studio Natvis framework lets you customize the way Visual Studio displays native types in debugger variable windows such as the Watch, Locals and Data Tips windows. It supersedes the autoexp.dat file that has been used in earlier versions of Visual Studio and offers XML syntax, better diagnostics, versioning, and multiple file support. The container in OpenCASCADE is difficult for debugging, such as TColStd_Array1OfInteger in the TColStd package, .etc. Use the natvis framework to create views of these objects will make it easy for developers to inspect them during debugging and so accelerate the debug process.
Key Words. Visual Studio Natvis, OpenCASCADE
1. Introduction
因為OpenCASCADE早期使用C開發(fā)，所以自定義了一些容器類，如包TColStd中的類，TColGeom包及包TopTools中的類等，這些類在C++中都可以使用STL來替代了。這些類在Debug過程中，很難查看其中的值，如TColStd_Array1OfInteger，這個類相當(dāng)于std::vector<int>，但是Debug時只能看到數(shù)據(jù)的指針，不容易查看容器中每個元素的值，如下圖1.1所示：
Figure 1.1 View of TColStd_Array1OfInteger in Locals Window
由上圖1.1可知，對于這個類的對象，Debug時只能看到數(shù)據(jù)的起始指針。為了方便自定義類型調(diào)試，Visual Studio在2012版本以后，引入了Natvis框架，用來替代原來的autoexp.dat來為自定義類型定義調(diào)試時的數(shù)據(jù)顯示。Natvis使用了XML文件，可讀性更好，易于實現(xiàn)。
本文使用Visual Studio的Natvis框架，來對OpenCASCADE中的一些容器類數(shù)據(jù)進(jìn)行可視化，方便開發(fā)者對OpenCASCADE的調(diào)試。
2.For Array Container
對于OpenCASCADE的包TColStd中的數(shù)組類，定義其natvis如下所示：
<Type Name="TColStd_Array1OfInteger">
<DisplayString Condition="isAllocated != 1">empty</DisplayString>
<DisplayString>{{size = {myUpperBound - myLowerBound + 1}}}</DisplayString>
<Expand>
<Item Condition="isAllocated == 1" Name="[size]">myUpperBound - myLowerBound + 1</Item>
<ArrayItems Condition="isAllocated == 1">
<Size>myUpperBound - myLowerBound + 1</Size>
<ValuePointer>(Standard_Integer*)(myStart) + myLowerBound</ValuePointer>
</ArrayItems>
</Expand>
</Type>
調(diào)試時數(shù)據(jù)顯示如下圖2.1所示：
Figure 2.1 OpenCASCADE array in Locals Windows
同理，可對此包中其他一維數(shù)組使用同樣的規(guī)則，即可對其中的數(shù)據(jù)可視化，與std::vector顯示的效果一樣，方便調(diào)試。
3.For List Container
對于OpenCASCADE的包TColStd中的鏈表類，定義其natvis如下所示：
<Type Name="TColStd_ListNodeOfListOfInteger">
<DisplayString>{{current = {myValue}}}</DisplayString>
<Expand>
<LinkedListItems>
<HeadPointer>this</HeadPointer>
<NextPointer>(TColStd_ListNodeOfListOfInteger*)myNext</NextPointer>
<ValueNode>this->myValue</ValueNode>
</LinkedListItems>
</Expand>
</Type>
<Type Name="TColStd_ListOfInteger">
<DisplayString Condition="myFirst == 0">empty</DisplayString>
<Expand>
<Item Name="first">(TColStd_ListNodeOfListOfInteger*)myFirst</Item>
</Expand>
</Type>
調(diào)試時對于類TColStd_ListOfInteger，natvis診斷說找不到類TColStd_ListNodeOfListOfInteger定義，當(dāng)跟蹤到此類一個具體函數(shù)時，就可以看到具體的值了：
Figure 3.1 Natvis gives a Error info
跟蹤到TColStd_ListOfInteger內(nèi)部后，就可以看到類TColStd_ListNodeOfListOfInteger中的數(shù)據(jù)了，但是從TColStd_ListOfInteger的函數(shù)中出來后，就看不到了。
如果這個問題解決了，對于類TopoDS_ListOfShape中的數(shù)據(jù)也可以用同樣的方式來顯示，極大地方便了開發(fā)者對其調(diào)試。如果你對此有解決辦法，歡迎不吝賜教。
Figure 3.2 Data view for TColStd_ListNodeOfListOfInteger
先從簡單的容器類著手，解決后可將TopoDS_ListOfShape中的數(shù)據(jù)顯示出來，為OpenCASCADE程序的調(diào)試提供方便。
4.Conclusion
Visual Studio 2012版本以后引入了Natvis框架來對自定義的類進(jìn)行可視化，方便調(diào)試。OpenCASCADE中有很多容器類直接使用了指針，調(diào)試程序時數(shù)據(jù)很不直觀。應(yīng)用Natvis來對一些類在調(diào)試時的視圖進(jìn)行配置，可以方便查看其中數(shù)據(jù)，使OpenCASCADE的調(diào)試更輕松。
對于一維數(shù)組的natvis定義還是很簡單的，但是對于List出現(xiàn)了問題。如果這個問題解決了，對TopoDS_ListOfShape的可視化也可做同樣的處理，方便造型算法調(diào)試。若您有解決方案，望不吝賜教。
5. References
1. Create custom views of native objects in the debugger.
https://msdn.microsoft.com/en-us/library/vstudio/jj620914.aspx
2. Writing debugger type visualizers for C++ using .natvis files
https://code.msdn.microsoft.com/Writing-type-visualizers-2eae77a2#content
3. vczh. C++實用技巧之配置Visual C++的調(diào)試器顯示數(shù)據(jù)結(jié)構(gòu)的格式.
http://m.shnenglu.com/vczh/archive/2013/03/21/198665.html
4. stl.natvis in %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers
5. qt5.natvis in %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers