VTK/Developers Corner

Dashboard submissions

Turn on warnings

Be sure to set CMAKE_CXX_FLAGS to <source lang="text"> -Wunused -Wshadow -Wformat </source>

Running tests locally

To run all of the tests on your modified source tree, simply type <source lang="text"> ctest </source> in your build directory. This will not submit anything to the dashboard, but it is a good "first test" to simply see, locally, if everything works.

Submitting an experimental build to the dashboard

The idea of this type of submission is simply to have a nice way to view the output of all the tests, and to leave "proof" that you indeed tested the code. This is useful if you then commit your code and it breaks someone else's build - you can then claim you did everything you could :). To run this type of submission, simply type <source lang="text"> make Experimental </source> from your build directory.

Creating a 'Nightly' dashboard submission

It is impossible for developers to test code on every operating system, compiler, and configuration. By creating a dashboard submission, you can help them find bugs that could be affecting many users but are transparent to some developers. The idea is to get the latest source code, compile it, and run a battery of tests - reporting any compile, build, and test errors to a system which very neatly arranges the results (http://www.cdash.org/CDash/index.php?project=VTK).

It is recommended to not use the same build you work with daily for you dashboard submission. If there is a problem with the nightly cvs, your code may not compile the next day!

To get started, create a new directory called /home/username/Dashboards/VTK. It does not actually have to be in this exactly directory, but this path will be used throughout this example to make the ideas concrete. cd to your new directory and run these commands to check out an initial version of VTK and data sets used for testing.

Here is an example cmake dashboard file.

You will probably want to submit a dashboard every night, so you can add a cronjob. Run 'crontab -e' and enter the following command <source lang="text"> 0 1 * * * export DISPLAY=:0.0 ; ctest -S /home/username/Dashboards/VTK/dashboard.cmake -V > /home/username/Dashboards/VTK/dashboard.log 2>&1 </source>

This says "at 1:00 AM, every day, every month, run the dashboard tests and log verbose output to dashboard.log". The DISPLAY variable is set to allow the tests that need an X server to complete successfully.

Developers Corner

• Documentation Rules
• TestingGuidelines

General Tips

• If you work with Paraview and VTK, the recommended procedure is to use the same source tree for both projects. That is, build Paraview from .../src/Paraview and VTK from .../src/Paraview/VTK.

• You should use vtkGetObjectMacro and vtkCxxSetObjectMacro to set and get member variables that are custom types. This allows VTK's mechanisms to keep the reference count correct by automatically registering and unregistering your objects. An example using a custom class member variable is here.

Pitfalls

• When using the Set*Macro's, you must initialize the variable that is being set in the constructor. The Set*Macro does a check to see if the value has changed before changing it (so that it can update the Modified variable), so if the value is uninitialized, this will cause an error in some memory checking tools (such as valgrind).
• When trying to use an abstract class, such as

<source lang="cpp"> vtkSmartPointer<vtkPointSet> PointSet = vtkSmartPointer<vtkPointSet>::New(); </source> you will see

error: invalid conversion from 'vtkDataObject*' to 'vtkPointSet*'

To fix this, use a subclass instead.

• You are getting

Generic Warning: In /home/doriad/src/ParaView3/VTK/Common/vtkDebugLeaks.cxx, line 296
Deleting unknown object: vtkObject

and

vtkDebugLeaks has detected LEAKS!
Class "vtkYourClass" has N instances still around.

This could mean one of two things. Either 1) you are actually doing something wrong by trying to manually delete a smart pointer or the equivalent or 2) You have forgotten to add:

<source lang="cpp"> vtkTypeMacro(vtkYourClass,vtkObject); </source> to your .h file.

You must do this because vtkDebugLeaks uses the VTK factory mechanism to keep track of references.

• Simple object class

• Accidentally using the old vtkTypeRevisionMacro instead of vtkTypeMacro will result in extremely confusing vtable errors!

Setting Up A Development Environment

First things, get on the vtk and or paraview mailing lists.

 http://www.vtk.org/mailman/listinfo/vtkusers
 http://www.vtk.org/mailman/listinfo/paraview

That is the best place to ask questions since you get many eyes on the problem. The best way to search said lists is via markmail.org (of course you can do it via google too but I can't remember the exact expression to ask google to do it well).

Second, I recommend working at the VTK level if possible. That simplifies the learning curve a bit, makes the work reusable by a larger group of people, and also because there is a fairly standard way to expose VTK code in ParaView. (See http://paraview.org/Wiki/Plugin_HowTo and http://pluginwizard.mirarco.org/)

As for setting up a development environment:

1) installing cmake (http://www.cmake.org/cmake/resources/software.html)

2) either downloading a source tarball (http://www.vtk.org/VTK/resources/software.html) or clone the repository directly from git.

 $ git clone git://vtk.org/VTK.git VTK
 $ cd VTK
 $ ./Utilities/SetupForDevelopment.sh

I recommend using git since, although it takes longer to learn it makes it easier to keep track of your changes and makes it easier to eventually contribute the code back in.

3) use cmake to configure a build environment in some other directory and then run make or visual studio to do the actual compilation. I suggest turning on the extra warnings and VTK_DEBUG_LEAKS flags to help catch problems early on.

4) I recommend building a test stub for your code starting from one of the existing tests. Turning on python wrappings and writing the test in python can make for very quick development.

Notes: After you create your class somewhere in VTK, to get your code to compile, edit CMakeLists.txt and add your cxx class filename to the file. Start by changing another class that uses the same data you are interested in.

Creating a New VTK Class

You can start by renaming an existing class, than changing it to do what you would like. For example, I want to make a new class named vtkReynoldsGlyph, which is similar to vtkTensorGlyph.

Creating and Compiling Steps:

1. Copy vtkTensorGlyph.h to vtkReynoldsGlyph.h and modify the class name within the new header file.
2. Copy vtkTensorGlyph.cxx to vtkReynoldsGlyph.cxx and modify the new class's scoping name for each method, e.g. vtkReynoldsGlyph::vtkReynoldsGlyph() for the constructor and so on.
3. Edit CMakeLists.txt in that directory; add your class's name.
4. Rerun

 $ ccmake /path/to/source 

(Running ccmake will create a new make file that includes your new class).

1. Then run

 $ make

The make process will create tcl wrappers for you.

Testing Your new class

If there is an existing test for the class you modified to make your class, you can just edit it to create your an instance of your new class instead of the old one. Or you can write your own test in tcl.