Home

About

Sponsors

Download

Install

Client Usage

Defining Tests

Advanced Dart

Examples

Documentation

FAQ

Mailing Lists

News
Dart Installation

Dart can be installed anywhere on your system. Installation scripts will be distributed soon.

Dart with CMake

Dart can be controlled by CMake. Please see the CMake website for installation instructions for CMake.

Dart without CMake

Dart can be used on projects without CMake. Additional client and server configuration is required. Details will be provided soon.

Configuring the Dart Client

The Dart client consists of a series of Tcl scripts in Dart/Source/Client. The Tcl scripts can be used to build a software project, to run a series of tests, and submit XML reports to the Dart Server. The Dart client can be installed anywhere on your system. The Dart client can be obtained at here.

The Dart client uses a "Testing" subtree under the root of your project's source tree. If this subtree is not present, it will be created. Local copies of XML reports are stored under Testing/HTML.

The Dart client is controlled via CMake and a series of CMakeList.txt files. The Dart client uses the Tcl scripting language which must be installed on your system. On unix based systems, CMake will create a number of build targets to control the Dart client. On MS Windows, CMake will create a number of extra projects (DSP's) for your software project, allowing the Dart client to be triggered from inside of Developer Studio. Dart in enabled for a software project by including the CMake module Dart.cmake in the project's toplevel CMakeLists.txt file. This module locates a number of programs that are needed by Dart (make command, Tcl, Java, hostname, nslookup, etc.) The CMake ADD_TEST() command is used to identify tests for Dart. ADD_TEST takes a test identifier, an executable or program name to execute, and a series of arguments to pass to the test.

Activating Dart for a CMake compatible project

When using CMake with Dart, Dart is activated by including the Dart.cmake module in your project's toplevel CMakeLists.txt file. A sample toplevel CMakeLists.txt snippet is below: 

#
# This toplevel snippet from a CMakeLists.txt configures the testing system.
#

# Include the standard Dart testing module
INCLUDE (${CMAKE_ROOT}/Modules/Dart.cmake)

#
# End of toplevel CMakeLists.txt snippet
#

Configuring Dart with CMake - DartConfig.cmake

The root directory for a software project needs to include a file called DartConfig.cmake. This file identifies the Dart server to be used for your software project. An example DartConfig.cmake file is below 

#
# This is the DartConfig.cmake file for the Insight Toolkit.
# The variables here would be set by the software project administrator
# and should not be modified by the user.
#

# Dashboard is opened for submissions for a 24 hour period starting at
# the specified NIGHLY_START_TIME. Time is specified in 24 hour format.
SET (NIGHTLY_START_TIME "1:00:00 EST")

# Dart server to submit results (used by client)
SET (DROP_METHOD "ftp")
SET (DROP_SITE "www.itk.org")
SET (DROP_LOCATION "/incoming")
SET (DROP_SITE_USER "anonymous")
SET (DROP_SITE_PASSWORD "insight-tester@somewhere.com")
SET (TRIGGER_SITE 
       "http://${DROP_SITE}/cgi-bin/Submit-Insight-TestingResults.pl")

# Dart server configuration 
SET (CVS_WEB_URL "http://${DROP_SITE}/cgi-bin/cvsweb.cgi/Insight/")
SET (CVS_WEB_CVSROOT "Insight")

OPTION(BUILD_DOXYGEN "Build source documentation using doxygen" "On")
SET (DOXYGEN_URL "http://${DROP_SITE}/Insight/Doxygen/html/" )
SET (USE_DOXYGEN "On")
SET (DOXYGEN_CONFIG "${PROJECT_BINARY_DIR}/doxygen.config" )

SET (USE_GNATS "On")
SET (GNATS_WEB_URL "http://${DROP_SITE}/cgi-bin/gnatsweb.pl/Insight/")

# Problem build email delivery variables
SET (DELIVER_BROKEN_BUILD_EMAIL "Continuous")
SET (EMAIL_FROM "someone@somewhere.com")
SET (DARTBOARD_BASE_URL "http://www.itk.org/Testing")
SET (EMAIL_PROJECT_NAME "Insight")
SET (BUILD_MONITORS "{.* monitor@aaa.com}")
SET (CVS_IDENT_TO_EMAIL "{cvsuser1 aa@aaaa.com} {cvsuser2 bb@bbbb.com}")
SET (DELIVER_BROKEN_BUILD_EMAIL_WITH_CONFIGURE_FAILURES "1")
SET (DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_ERRORS "1")
SET (DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_WARNINGS "0")
SET (DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_NOT_RUNS "1")
SET (DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_FAILURES "0")

# Copy over the testing logo
CONFIGURE_FILE(${PROJECT_SOURCE_DIR}/TestingLogo.gif 
     ${PROJECT_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)

# If DROP_METHOD is set to "scp", then add this FIND_PROGRAM to your DartConfig
FIND_PROGRAM(SCPCOMMAND scp DOC 
     "Path to scp command, sometimes used for submitting Dart results.")


#
# End of DartConfig.cmake
#

Explanation of Dart.cmake items

  • NIGHTLY_START_TIME - A new dartboard is opened for submissions for a 24 period starting at the NIGHTLY_START_TIME. This time is specified in 24 hour format using an abbreviation for the time zone. This time is used both for opening the dartboard for submissions and as the timestamp used for all nightly builds.

  • DROP_METHOD - Method used for submitting results to the Dart server. Can be "ftp" or "scp".

  • DROP_SITE - Location of the Dart server. Build and test results generated by Dart clients are sent to this location. This site may be an ftp server or may be a ssh server (meaning scp will be used submissions).

  • DROP_LOCATION - Directory on the server Dart clients leave their build and test reports. DROP_LOCATION must be somewhere where DROP_SITE_USER can write. If submission is via ftp, this location may be relative to the root of the ftp server. If submission is via scp, this location may be a full path.

  • DROP_SITE_USER - Username the client will use on the server. For ftp submissions this user will typically be "anonymous". However, any username that can communicate with the server can be used.

  • DROP_SITE_PASSWORD - Password for the above username. Most ftp servers require a password even for user "anonymous". No used when DROP_METHOD is "scp".

  • DROP_SITE_MODE - Optional FTP mode. Most ftp servers will handle the default passive mode. Set the mode explicitly to active if your server does not.

  • TRIGGER_SITE - Once build and test results are placed on the server, the Dart client will "trigger" the server. This informs the server that new reports are available. When "triggered" the Dart server determines whether these are valid reports and moves them from the submission area to the Dart server area. This provides additional security for the Dart server.

  • CVS_WEB_URL - URL for the this project's cvsweb script.

  • CVS_WEB_CVSROOT - The symbolic name cvsweb uses for this project's cvs repository. A single cvsweb installation can server multiple repositories. CVS_WEB_CVSROOT can be set to "" if ViewCVS is used instead of cvsweb or if a cvsweb installation serves a single cvs repository.

  • BUILD_DOXYGEN - If your project uses Doxygen as its source level documentation system, then the Dart server can be configured to run doxygen every day and summarize any doxygen errors and warnings.

  • DOXYGEN_URL - URL for the Doxygen generated documentation.

  • USE_DOXYGEN - Place a button on all Dart web pages to link to your doxygen documentation.

  • DOXYGEN_CONFIG - Location of the config file used by doxygen for your project.

  • USE_GNATS - If your project uses Gnats as its bug tracker, then the Dart server can be configured to include a button that links every Dart web page to your installation of Gnats.

  • GNATS_WEB_URL - URL to the Gnats server.

  • DELIVER_BROKEN_BUILD_EMAIL - String of Build types that email should be sent about. If this string is not empty, all of the next 10 email settings must be specified.

  • EMAIL_FROM - Sender used for email sent from the Dart server when a Continuous build has errors.

  • DARTBOARD_BASE_URL - URL to the Dart server. The "Sites" and "Dashboard" directories must be directly under this URL.

  • EMAIL_PROJECT_NAME - The email will describe the project using this string.

  • BUILD_MONITORS - A list of pairs to map build names to monitor's email addresses. Each pair is a tcl regular expression/replacement string.

  • CVS_IDENT_TO_EMAIL - A list of pairs of how to map cvs usernames to email address. Each pair is a tcl regular expression and replacement string. The first matching pair is used. Dart will also look for a file called $your_project_source/Documentation/UserList.txt or in your CVSROOT/users file and at the DEFAULTCONTIUOUSDOMAIN setting to guess email address.

  • DELIVER_BROKEN_BUILD_EMAIL_WITH_CONFIGURE_FAILURES - Control whether to send mail if the configuration step has problems.

  • DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_ERRORS - Control whether to send mail if the build produces errors.

  • DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_WARNINGS - Control whether to send mail if the build produces warnings.

  • DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_NOT_RUNS - Control whether to send mail if some tests do not run.

  • DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_FAILURES - Control whether to send mail if some tests fail.

  • CONFIGURE_FILE - This particular configure file command is used to copy a logo from the source tree on the Dart server to the build tree on the Dart server. The first argument is a path to the logo you want to use. The second argument is the path to where this logo needs to be placed on the Dart server. The logo must be called Logo.gif on the Dart server.

  • FIND_PROGRAM - This FIND_PROGRAM call tries to locate "scp". This is only needed if the DROP_METHOD is set to "scp". In future versions of CMake, this FIND_PROGRAM call will be in the CMake module Dart.cmake.

 

Defining tests in Dart

With the above two configuration files, developers can submit build results to the Dart server. To add tests to your system, add ADD_TEST() CMake commands to your CMakeLists.txt files. ADD_TEST() has the form 

ADD_TEST(TestIdentifier ExecutableName [Arguments])
The ExecutableName can be an executable built by your software project (i.e. a build target of your project) or can be any program on your system (for instance Tcl, Python, etc.). If the former, the ADD_TEST() command needs to be in the same CMakeLists.txt file as the EXECUTABLE() target. The latter allows other test control harnesses be use with Dart to run tests and determine wether a test passed or failed. When Dart executes a test, it uses the return status of the program to determine wether the test passed or failed. Tests are summarized on the Dartboards as "passed", "failed" or "not run".

Configuring the Dart Server

Please see the Dart Wiki and manual for details.