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

The Dart server consists of five parts:

An ftp, ssh, or local directory site for the client to drop build and test XML reports. The simplest procedure is to allow anonymous ftp access to the /incoming directory of an ftp server. If you are worried about opening up your ftp site for anyone to store files on, most ftp servers can be configured so a client cannot view /incoming. Hence it is of no use to the casual hacker. If you want to use a directory other than /incoming, you'll need to change the client's DartConfig.cmake DROP_LOCATION variable. You can also specify a user other than anonymous for submissions. If more security is needed, scp can be used as the submission process instead of ftp. This will require establishing an ssh userid that can be used by all Dart clients and distributing the appropriate keys between clients and servers.
The server needs to have a checkout of your project's software and an installation of the Dart tree. This checkout of your software needs to be configured to perform a build (i.e. CMake must be run in the build tree to properly configure the Dart server settings). The build tree is only used for gathering the testing results from the clients and for generating dashboards. Since Dart's dashboard mechanism is driven by CMake, we need to have a build tree available. This checkout and build tree must be accessible (writable) from the web server (usually "nobody") since the web server will move XML files to this build tree. A cvs update will be done on the web server (typically "nobody") so that user must have permission to do a cvs update on that checkout. The best bet is to checkout the source tree from the user nobody in the first place.
A web server capable of running a cgi-bin script. The perl script Dart/Source/Server/www/cgi-bin/TriggerDart.cgi can be copied onto your web server. The name of the script should match the TRIGGER_SITE variable that is specified in the client's DartConfig.cmake file. There are two variables in the TriggerDart.cgi to modify. "dropLocation" is the directory where the client submitted their XML reports. This must match the DROP_LOCATION variable in the client's DartConfig.cmake file. "destination" is where these XML files should be moved. The XML reports encode their site name and build name into the filename that is placed on the ftp server. This information is decoded as the XML files are moved from "dropLocation" to a subdirectory under "destination". "destination" should be set to the Testing/HTML/TestingResults/Sites directory of the build tree on the server setup in step 2 above.
An installation of Java. Java is used to convert build/test reports from XML to HMTL using XSLT. All the code for the XSLT engine is included with Dart (Dart/Source/Server/XSL/xalan.jar) so all Dart requires is a Java installation.
A series of cron jobs control the opening and closing of dashboards and periodically converting the XML submissions into HTML reports. The conversion to HTML uses a Java XSLT engine which is included in Dart/Source/Server/XSL subtree. The cron jobs need to be run as the same user as the web server (typically "nobody"). Below is a snippet of a crontab (also available in Dart/Source/Server/cron):
```
MAILTO=root@localhost
SHELL=/bin/tcsh

# Open the insight dashboard at 11pm
5 23 * * * cd /insight/TestingTree/Insight-TestingResults;  \
make NightlyDashboardStart; ./myconfig > /dev/null; make NightlyDashboardEnd

# Roll up each hour on the hour
0 0-22 * * * cd /insight/TestingTree/Insight-TestingResults; \
make NightlyDasboardEnd >>& Log.txt

#
# End of cron tab
#
```
XSLT modifications. None needed. Project specific settings can be set through a DartConfig.cmake file for the project. See Configuring the client (the server is itself a client).