Table of Contents generated with DocToc

• Introduction
• Configuring a test site
• Running the tests nightly
  • Linux
  • Mac OS
  • Windows

The cisst package uses CMake (http://www.cmake.org) for the build configuration. CMake comes with a nice utility called CTest which can be used to run our test programs in a portable way and optionally submit the results to a CDash Dashboard.

To run the tests locally one can use "ctest" in the build tree or the specials targets generated by CMake (e.g. with Visual Studio, build "RUN_TESTS" and with a Makefile, use "make test"). Running the test programs is always a recommended step before checking in any code but since we can not expect every user to test all the different build options, compilers and operating systems, we also maintain some nightly builds to cover the most common configurations. The results are then posted on the cisst Dart dashboard: http://unittest.lcsr.jhu.edu/CDash

The nightly tests are fairly simple to setup following these steps:

1. Create a directory for the source and the build trees
2. In the source tree, check-out the latest version of the cisst libraries from the git repository (git clone https://github.com/jhu-cisst/cisst.git)
3. In the build tree, run CMake and configure manually what needs to be compiled
4. Compile once to generate the lists of test cases

If the nightly build requires any external package, it is recommended to install them in the same tree so that the build remains fairly independant of the computer/user configuration.

If the site is using the GNU compiler, it is possible to get a coverage estimate using "gcov". To do so, one just needs to add the options -fprofile-arcs -ftest-coverage to the CMake flags CMAKE_C_FLAGS, CMAKE_CXX_FLAGS, CMAKE_EXE_LINKER_FLAGS and CMAKE_SHARED_LINKER_FLAGS.

To activate the nightly builds automatically, it is possible to use crontab on Unix based systems (Linux, Mac OS X, ...). Here are two examples of crontabs, one for Linux and one for Mac OS (replace the path to your build directory as well as the absolute path to ctest if needed):

  # m h  dom mon dow   command
  00  01 * * * cd /users/anton/dart-builds/gcc-4.0/cisst-debug/build && . cisstvars.sh && make clean && /home/erc/bin/ctest -D Nightly -V > ctest.log 2>&1
  00  02 * * * cd /users/anton/dart-builds/gcc-4.0/cisst-release/build && . cisstvars.sh && make clean && /home/erc/bin/ctest -D Nightly -V > ctest.log 2>&1
  00  03 * * * cd /users/anton/dart-builds/gcc-4.0/cisst-coverage/build && . cisstvars.sh && make clean && /home/erc/bin/ctest -D Nightly -V > ctest.log 2>&1

Note that it might be necessary to place these commands in a shell script called by the crontab. For example, one can create a shell script with:

#!/bin/bash
BUILD_DIR=/home/stomach/anton/dart-builds/gcc-4.1-debug/build
CTEST=/usr/local/bin/ctest
LOG_FILE=$BUILD_DIR/ctest.log 
echo "------ cisstvars.sh -------" > $LOG_FILE
. $BUILD_DIR/cisstvars.sh >> $LOG_FILE 2>&1
echo "------ make clean -------" >> $LOG_FILE
cd $BUILD_DIR; make clean >> $LOG_FILE 2>&1
echo "------ ctest -------" >> $LOG_FILE
cd $BUILD_DIR; $CTEST -D Nightly -V >> $LOG_FILE 2>&1

and then use the following crontab:

00 01 * * * /home/stomach/anton/dart-builds/gcc-4.1-debug/build/nightly-build.sh

For Mac OS, one can use Makefiles (first two builds) or XCode (the Apple IDE):

  00  00 * * * cd /Users/anton/dart-builds/darwin-make-gcc-4.0-debug/build && make clean && /usr/local/bin/ctest -D Nightly -V > ctest.log 2>&1
  00  01 * * * cd /Users/anton/dart-builds/darwin-make-gcc-4.0-release/build && make clean && /usr/local/bin/ctest -D Nightly -V > ctest.log 2>&1
  00  02 * * * cd /Users/anton/dart-builds/darwin-xcode-gcc-4.0-debug/build && xcodebuild clean && /usr/local/bin/ctest -D Nightly -V > ctest.log 2>&1

For a Windows based computer, it is necessary to add a "scheduled task". To simplify the command line used it is recommended to create a small batch file used by the scheduled task. For example, one can create "nightly-build.bat" containing:

  @rem Go to the build directory
  c:
  cd "C:\users\anton\dart-build\msvc7.1-static-nmake\build"

  @rem Set the env. variables
  call cisstvsvars.bat
  call cisstvars.bat

  @rem Clean and build
  nmake clean
  "C:\Program Files\CMake 2.4\bin\ctest.exe" -D Nightly

The previous example works for a build configuration using the Microsoft Visual Studio .net 2003 compiler cl.exe with nmake.