ITK/Examples/Instructions/ForAdministrators

From KitwarePublic
Jump to navigationJump to search

Wiki Example Administrators have write access to the git repository. Wiki Example Developers do not need write access to the repository since the definitive copy of the source code resides on the Wiki. If you are a Wiki Example User go here or a Wiki Example Developer go here.

Wiki Example Administrators maintain the CMakeLists.txt files, example input files, example regression baseline files and synchronization scripts.

Organization of the Example Repository

The wiki examples are stored in a git repository hosted at github. The repository contains several types of files:

This cmake file locates and includes the ITK_USE_FILE and adds directories for each of the topics
mwclient is a python framework to access MediaWiki's API. The ScrapeWiki script uses it to pull pages from the wiki and create example source files.
This is a python script that uses mwclient to access the pages of the wiki. It looks for pages in ITK/Examples. For each page, it looks for second level headings and stores the code that lies between 
<source> and </source>
into a file in the proper topic subdirectory. Anyone, including users, can run this script. It updates the current directory with changes or new examples. If you run this script, be sure to re-run cmake.
This is a python script that uses mwclient to upload example baselines to the Wiki. The baselines are located in the Wiki git repository in [1]. The script walks through the git baselines and checks to see if the baselines exist on the Wiki. If the baseline does not exist on the Wiki, the script uploads it. If the baseline does exist on the Wiki the md5 hash is checked to see if the image has changed.
This is a python script that uses mwclient to check each example to see if it should have a reference to a baseline image. If a baseline image exists for an example, the script looks for a ''<div></div>'' tag. This tag contains a reference for the baseline image for the example. If the tag is not found, the script generates a cut/paste line to edit the page as well as a cut/paste line that has the proper ''<div></div>'' for the baseline image.
This shell script runs ScrapeWiki to create source files for all wiki examples. Then it uses git to add, remove or modify the source code. The resulting repository is pushed to the github repository. The script is run nightly by a cronjob on a designated host (currently BillsBasement). NOTE: this script should only be run by one individual (currently Lorensen).
Some examples require input data. A small number of datasets are distributed with the examples and are used by the regression tests. All administrators can add input data.
Examples that produce images are regression tested. ctest runs the examples and when appropriate, compares the output of the example to a baseline image. Each topic has a directory in Testing/Baseline. All administrators can add and modify baseline images.
  • Topic Directories
Examples for each topic reside in a directory with the topic name. If the examples in a topic directory should be compiled and run, the topic directory has a CMakeLists.txt file. All administrators can create topic directories and CMakeLists.txt files.

Administrator Tasks

Clone repository with write access

(Note the git@ instead of https:// as is listed on the Users instructions page) 

git clone git@github.com:InsightSoftwareConsortium/ITKWikiExamples.git

Add a new topic

  • Create a topic subdirectoy
mkdir MyTopic
cd MyTopic
  • Create a CMakeLists.txt file

<source lang='cmake'> PROJECT (MyTopic)

SET(KIT MyTopic) SET(KIT_LIBS itkHybrid)

IF(NOT WikiExamples_BINARY_DIR) 

 FIND_PACKAGE(ITK REQUIRED)
 INCLUDE(${ITK_USE_FILE})

ENDIF(NOT WikiExamples_BINARY_DIR)

  2. Build all .cxx files in the directory

FILE(GLOB ALL_FILES *.cxx) foreach(SOURCE_FILE ${ALL_FILES}) 

 STRING(REPLACE ".cxx" "" TMP ${SOURCE_FILE})
 STRING(REPLACE ${CMAKE_CURRENT_SOURCE_DIR}/ "" EXAMPLE ${TMP})
 ADD_EXECUTABLE(${EXAMPLE} ${EXAMPLE}.cxx)
 TARGET_LINK_LIBRARIES(${EXAMPLE} ${KIT_LIBS})

endforeach(SOURCE_FILE)

  1. Testing

INCLUDE(${WikiExamples_SOURCE_DIR}/CMake/ExamplesTesting.cmake) </source>

  • Add the directory to the main CMakeLists.txt file
ADD_SUBDIRECTORY(MyTopic)
  • Add and commit the new topic directory and CMakeLists.txt file's to the local repository
cd ..
git add MyTopic
git add MyTopic/CMakeLists.txt
git commit -m "ENH: Added topic MyTopic and CMakeLists.txt file." CMakeLists.txt MyTopic/CMakeLists.txt
  • Push to the master repository
git push

If you get an error, you should make sure your rsa key is uploaded to github and that you have done: 

git config remote.origin.pushurl git@github.com:InsightSoftwareConsortium/ITKWikiExamples.git

Add a test that requires arguments

By default, the CMakeLists.txt in a topic directory creates a small test driver for each .cxx file it finds. Then it creates an ADD_TEST command. The default ADD_TEST command assumes that the test has no arguments.

Some tests require arguments. To prevent the ADD_TEST from being generated, add any examples that require arguments to the list NEEDS_ARGS:

<source lang="cmake"> 

 SET(NEEDS_ARGS 
   Example1
   Example2
 )
 INCLUDE(${WikiExamples_SOURCE_DIR}/CMake/ExamplesTesting.cmake)

</source>

Then, provide an ADD_TEST for each:

<source lang="cmake"> 

 ADD_TEST(${KIT}-Example1 ${EXECUTABLE_OUTPUT_PATH}/${KIT}CxxTests
   TestExample1  arg1 arg2)
 ADD_TEST(${KIT}-Example2 ${EXECUTABLE_OUTPUT_PATH}/${KIT}CxxTests
   TestExample2  arg1 arg2 arg3)

</source>

Add a regression baseline image

Any example that uses a render window interactor will expect to find a baseline image for regression testing. The first time the test for the example is run, using ctest, the test will fail and report that a baseline image could not be found.

  • The test for the example will produce a test output image in WikiExamples-build/Testing/Temporary. The name of the image will be TestExampleName.png
  • With an image viewer, verify that the image is correct.
  • Copy the image from Testing/Temporary into WikiExamples/Testing/Baseline/Topic/TestExampleName.png
  • If there is more than one possible output image, name the image WikiExamples/Testing/Baseline/Topic/TestExampleName_1.png instead
  • Rerun ctest -V -R TestExampleName
The test should now pass
  • Add the baseline to the repository
git add Testing/Baseline/Topic/TestExampleName.png
git commit -m "ENH: Added baseline for TestExampleName regression test
git push
  • Overnight, a script automatically produces and uploads a file with the name
ITK_Examples_Baseline_'Folder'_Test'TestName'.png

You must add this tag to the top of the example page:

<div class="floatright">[[File:ITK_Examples_Baseline_'Folder'_Test'TestName'.png]]</div>

An example is: <div class="floatright">[[File:ITK_Examples_Baseline_Filtering_TestLandmarkTransform.png]]</div>

Add example input data

We like to keep the example data to a small number of small files. If you must add input data for the tests: 

git add Testing/Data/MyData.whatever
git commit -m "ENH: Added new example input data." Testing/Data/Mydata.whatever
git push

Add a testing machine to the dashboard

  • The simplest way is to add an Experimental build
make Experimental
  • Or a Nightly build
make Nightly
  • Or create a ctest script. A starting ctest script (SampleBuildTest.cmake) is created when you run cmake. You should edit this line so we know where the submissions is coming from:

<source lang="cmake"> set(CTEST_SITE "BillsBasement") </source>

Then you should comment one of these, depending on which type of build you would like to submit.

<source lang="cmake"> set(DASHBOARD Nightly) set(DASHBOARD Experimental) </source>

Copy the edited SampleBuildTest.cmake to /home/foo/WikiExamples.ctest. This can be run nightly from a cronjob (crontab -e)
0 23 * * * ctest -S /home/foo/WikiExamples.ctest -V  &> /home/foo/WikiExamplesNightly.log

Check the dashboard frequently!

http://www.cdash.org/CDash/index.php?project=ITKWikiExamples

Updating the links in the ITK Doxygen

To create a patch with the latest example links added in the ITK header files (which turn into links in the Doxygen), use 

./InsertDoxygenLink massive-set ../../ITK
Retrieved from "https://public.kitware.com/Wiki/index.php?title=ITK/Examples/Instructions/ForAdministrators&oldid=53484"