Procedures

User Contributions

Users can contribute patches through the gerrit code review system: http://review.source.kitware.com/#q,SimpleITK,n,z

General information about Gerrit can be found here: http://gerrit.googlecode.com/svn/documentation/2.2.1/user-upload.html

For those already familiar with git, gerrit, ITK and building SimpelITK, here is a quick overview of the process:

The first thing which should be done before any code is commited locally is running the script to setup your local git repository for development.

$ Utilities/SetupForDevelopment.sh

This will guide you through the processes of adding several repositories and local configuration options.

The following is an overview of how to add commits locally, and push the changes to gerrit:

$ git checkout master
$ git pull
$ git checkout -b $MyTopic$
hack and edit
compile and test
$ git add $MyHackedFiles$
$ git commit
$ git prepush
$ git gerrit-push

The goal of this workflow here is just have one or two commits in the topic, so that it will be easy to review. If longer topics are needed, that is OK to, but please try to reach out to the SimpleITK development community first. Please upload any new testing data as described below.

If you are not too familiar with these tools, this aspect of submitting patch to gerrit is the same as for ITK development. So the overview of ITK development process may be a better starting point: https://www.itk.org/Wiki/ITK/Git/Develop

Binary Data to a Commit

Since every local Git repository contains a copy of the entire project history, it is important to avoid adding large binary files directly to the repository. Large binary files added and removed through the history of a project will cause the repository to become bloated, take up too much disk space, require excessive time and bandwidth to download, etc.

The solution to this problem adopted by this project is to store binary files, such as images, in a separate location outside the repository, then download the files at build time with CMake.

A content link file containing an identifying MD5 checksum is stored in the Git repository at the path where the file would exist with the .md5 extension added to the file. CMake will find these content link files at build time, download them from a list of server resources, and create symlinks or copies of the original files at the corresponding location in the build tree.

The Midas server is an ITK community resource where any community member can upload binary data files. This script automates the upload of data to the server and generation of the content link file. Before using this script, please go to the Midas website, register, and join the ITK community.

This script requires the Python module pydas: which can be installed with:

$ pip install pydas

Please use the content link system for all new test images and other binary data. An example:

cd ~/src/SimpleITK
cp /path/to/NewInput.png ./Testing/Input/
python ./Utilities/UploadBinaryData.py ./Testing/Input/NewInput.png
git add -- ./Testing/Input/NewInput.png.md5

Setup a Dashboard

The SimpleITK Dashboard is a central location where systems report on continuous or nightly compilation and testing results. It is a invaluable tool in the extreme programing or agile development process. The SimpleITK dashboard is now a standalone dashboard.

The following is a brief overview on how to contribute a nightly build to SimpleITK. Additional relevant information can be found on the CTest documentation page along with simular information on how to setup a dashboard for ITK.

SimpleITK uses CTest to run the nightly dashboards. There are 3 things which are needed to setup a nightly dashboard. The first is the common CTest scripts. Second, is a custom script to configure SimpleITK for your system, and third is the configuration of a system tool to run the CTest script each night.

The common script(s) are contained in the dashboards branch. Essentially, this branch contains the "simpleitk_common.cmake" file which will be included in the next step. It can be retrieved as follows:
$ mkdir -p ~/Dashboards/SimpleITKScripts

$ cd ~/Dashboards/SimpleITKScripts

$ git init

$ git remote add -t dashboard origin git://itk.org/SimpleITK.git

$ git pull origin
Next, we need to create a custom CTest script for our system. More information on the varaible are describe in the header of "simpleitk_common.cmake". Here is a sample which can be place in "~/Dashboards/SimpleITKScripts/simpleitk_nightly.cmake":
#

# Maintainer: blowekamp@mail.nih.gov

#

# Set names

set( CTEST_SITE "mini5.nlm" )

set( CTEST_BUILD_NAME "MacOSX-SimpleITK-super-next" )

# Set how and where to build

set( CTEST_BUILD_CONFIGURATION "Release" )

set( CTEST_CMAKE_GENERATOR "Unix Makefiles" )

set ( CTEST_DASHBOARD_ROOT "$ENV{PLAYPEN}/${CTEST_BUILD_NAME}" )

set( dashboard_model Nightly )

set ( dashboard_git_branch "next" )

# Enable usage of multi-processors

set ( CTEST_BUILD_FLAGS -j2 )

set ( CTEST_TEST_ARGS PARALLEL_LEVEL 2 )

# Set initial values for the CMakeCache

set ( dashboard_cache "

CMAKE_CXX_COMPILER:STRING=$ENV{HOME}/local/bin/ccache-c++

CMAKE_CXX_FLAGS:STRING=-Wall

CMAKE_C_COMPILER:STRING=$ENV{HOME}/local/bin/ccache-cc

CMAKE_C_FLAGS:STRING=-Wall

")

# Include common ctest script

include(${CTEST_SCRIPT_DIRECTORY}/simpleitk_common.cmake)
Lastly, the following needs to be executed each night:
$ ctest -S ~/Dashboards/SimpleITKScripts/simpleitk_nightly.cmake

Depending on your system the tool needed is different. For Unix and Mac OSX operating system it's the cron daemon, while on windows it is Schedualer. More information can be found on the general CMake Scripting Of CTest wiki page.

Tips and Tricks

Working with JSON file.

SimpleITK uses a large number of JSON files as input for generated code. Adding support for your text editor to understand the syntax is advantageous.

-Emacs

The following can be added to your ".emacs" file.

; Add JSON files to automode list, use javascript mode
(add-to-list 'auto-mode-alist '("\\.json\\'" . js-mode) )
(add-hook 'js-mode-hook (function (lambda ()
  (setq tab-width 2
        c-basic-offset 2
        show-trailing-whitespace 1) ) ) )

Using ccache to accelerate re-compilation.

SimpleITK has a complicated set of dependency that is handled the best it can be with CMake and the code generation tools implemented. However, when switching between branches and making changes to certain files, such as the "Expand" templates a large number of files will have to be re-compiled. Even though the generated code may not have changed, it's impossible for CMake or your make-file tool to determine this.

Fortunately, there is a tool which can cache results of compilation and reduce recompilation. Using ccache can greatly accelerate the development time when rebuilding SimpleITK frequently. Usage is quite simple, download and install. However, getting CMake to work with the compiler requires setting a few enviromental variables:

CXX=/usr/local/bin/ccache /usr/bin/g++-4.2
CC=/usr/local/bin/ccache /usr/bin/gcc-4.2

These variables need to be set bfore CMake is run, so that it will correctly detect the compiler and configure SimpleITK. Now enjoy the faster re-compilation times.