1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<!--#include file="Head.html"-->
<body bgcolor="#FFFFFF" leftmargin=0 topmargin=0 text="black" link="#0000FF"
vlink="#000000" alink="#000000">
<!--#include file="Table.html"-->
<table>
<tr>
<!--#include file="SideBar.html"-->
<td width="550" valign="top" bgcolor="#FFFFFF">
<div align="left">
<a name="installation"></a><font size=5>Dart Installation</font>
<p> Dart can be installed anywhere on your system. Installation
scripts will be distributed soon.
<P>
<a name="cmake"></a><font size=5>Dart with CMake</font>
<p> Dart can be controlled by <a href="http://www.cmake.org">CMake</a>. Please see the CMake website for installation instructions for CMake.
<P>
<a name="nocmake"></a><font size=5>Dart without CMake</font>
<p> Dart can be used on projects without CMake. Additional client and server configuration is required. Details will be provided soon.
<P>
<a name="client"></a><font size=5>Configuring the Dart
Client</font>
<p>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 <a href="Download.shtml">here</a>.
<P>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.
<P>The Dart client is controlled via <a
href="http://www.cmake.org">CMake</a> 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 <b>Dart.cmake</b> 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 <b>ADD_TEST()</b> command is used to identify tests for
Dart. <b>ADD_TEST</b> takes a test identifier, an executable or program
name to execute, and a series of arguments to pass to the test.
<h3>Activating Dart for a CMake compatible project </h3>
<P>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:
<pre>
#
# 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
#
</pre>
<h3>Configuring Dart with CMake - DartConfig.cmake</h3>
<p>The root directory for a software project needs to include a file called
<b>DartConfig.cmake</b>. This file identifies the Dart server to be used for
your software project. An example <b>DartConfig.cmake</b> file is below
<pre>
#
# 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
#
</pre>
<p><H4>Explanation of Dart.cmake items</h4>
<ul>
<li> <b>NIGHTLY_START_TIME - </b> 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.<p>
<li> <b>DROP_METHOD - </b> Method used for submitting results to the Dart server. Can be "ftp" or "scp".<p>
<li> <b>DROP_SITE - </b> 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).<p>
<li> <b>DROP_LOCATION - </b> 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.<p>
<li> <b>DROP_SITE_USER - </b> 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.<p>
<li> <b>DROP_SITE_PASSWORD - </b> Password for the above username. Most ftp servers require a password even for user "anonymous". No used when DROP_METHOD is "scp".<p>
<li> <b>DROP_SITE_MODE - </b> Optional FTP mode. Most ftp
servers will handle the default passive mode. Set the mode explicitly to active if your server does not. <p>
<li> <b>TRIGGER_SITE - </b> 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.<p>
<li> <b>CVS_WEB_URL - </b> URL for the this project's cvsweb script.<p>
<li> <b>CVS_WEB_CVSROOT - </b> 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.<p>
<li> <b>BUILD_DOXYGEN - </b> 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.<p>
<li> <b>DOXYGEN_URL - </b> URL for the Doxygen generated documentation.<p>
<li> <b>USE_DOXYGEN - </b> Place a button on all Dart web pages to link to your doxygen documentation.<p>
<li> <b>DOXYGEN_CONFIG - </b> Location of the config file used by doxygen for your project.<p>
<li> <b>USE_GNATS - </b> 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.<p>
<li> <b>GNATS_WEB_URL - </b> URL to the Gnats server.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL - </b> 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.<p>
<li> <b>EMAIL_FROM - </b> Sender used for email sent from the Dart server when a Continuous build has errors.<p>
<li> <b>DARTBOARD_BASE_URL - </b> URL to the Dart server. The "Sites" and "Dashboard" directories must be directly under this URL.<p>
<li> <b>EMAIL_PROJECT_NAME - </b> The email will describe the project using
this string.<p>
<li> <b>BUILD_MONITORS - </b> A list of pairs to map build names to monitor's email addresses.
Each pair is a tcl regular expression/replacement string.<p>
<li> <b>CVS_IDENT_TO_EMAIL - </b> 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.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL_WITH_CONFIGURE_FAILURES - </b> Control whether to send mail if the configuration step has problems.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_ERRORS - </b> Control whether to send mail if the build produces errors.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL_WITH_BUILD_WARNINGS - </b> Control whether to send mail if the build produces warnings.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_NOT_RUNS - </b> Control whether to send mail if some tests do not run.<p>
<li> <b>DELIVER_BROKEN_BUILD_EMAIL_WITH_TEST_FAILURES - </b> Control whether to send mail if some tests fail.<p>
<li> <b>CONFIGURE_FILE - </b> 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.<p>
<li> <b>FIND_PROGRAM - </b> 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.
</ul>
<p> <H3>Defining tests in Dart</h3>
<p>With the above two configuration files, developers can submit build
results to the Dart server. To add tests to your system, add
<b>ADD_TEST()</b> CMake commands to your CMakeLists.txt files. <b>ADD_TEST()</b> has the form
<pre>
ADD_TEST(TestIdentifier ExecutableName [Arguments])
</pre>
The <em>ExecutableName</em> 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
<b>ADD_TEST()</b> command needs to be in the same CMakeLists.txt file as the
<b>EXECUTABLE()</b> 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".
<P>
<a name="client"></a><font size=5>Configuring the Dart Server</font>
<p>The Dart server consists of five parts:
<ol>
<li> 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.<br><br>
<li> 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.<br><br>
<li> 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.<br><br>
<li> 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.<br><br>
<li> 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):
<pre>
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
#
</pre>
<li> XSLT modifications. None needed. Project specific settings can be
set through a <b>DartConfig.cmake</b> file for the project. See <a href="#client">Configuring
the client</a> (the server is itself a client).
</div>
</td>
</tr>
</body>
|
