The Dart Source

This document is aimed at Dart developers, or anyone who runs a Dart server and wants to change something.

How the Client works

The Client is relatively straight forward. Depending on the Options passed to DashboardManager.tcl, the client will run several programs, and store each programs standard output log, and return status. It will then attempt to parse the logs, and produce an XML file for each stage in the build process. The client then uses one of various means to transfer the XML files to the server. The submission process finally triggers the server to copy the XML files to the appropriate place in the build tree. Note that if the server runs a dashboard client in the same directory tree, you will not need an explicit submit - the files will already be in the correct place.

Client/DashboardManager.tcl
Manages the client process.
Client/Update.tcl
Runs a cvs update command and produces Update.xml
Client/Configure.tcl
Runs a Configure command and produces Configure.xml
Client/Build.tcl
Runs a build command and produces Build.xml
Client/ftp.tcl
Actually performs ftp protocol when using ftp submission
Client/Utility.conf.in
Configuration Source for CMake to control Dart parameters.
Client/Submit.tcl
Manages submission process
Client/Test.tcl
Runs all the Tests and produces Test.xml.
Test.tcl parses the output of a test looking for DartMeasurement and DartMeasurementFile tags. When it finds a tagset, it converts the tag into a NamedMeasurement tag in the Test.xml file. If the tag was a DartMeasurementFile tag, the data from the file is read and converted to base64 and placed within the NamedMeasurement tag in the Test.xml file. Any part of the test's stdout that is not within DartMeasurements tags is passed as the measurement for a test (just like before).

How the Server works

The Server is fairly complicated beast. The first point is that in some senses it is just another client. The server does not actively manage the receiving of client submission. Some intermediate scripts place that data into the server's directory tree. The server roll-up process is started when something (Cron or a roll-up web button) calls DashboardManager.tcl ... DashboardEnd

The roll-up process goes roughly as follows

Dashboard manager looks for new dashboard submission directories ($d) with dates that fit into the current dashboard's timeframe. In each directory $d:
- The manager goes through all the $d/XML/$s.xml files that could have been submitted, and if the equivalent $d/$s.html does not exist it passes the $d/XML/$s.xml file to the XSLT processor running Server/XSL/$s.xsl
  - Server/XSL/Update.xsl
    produces $d/Update.html which displays the update details for that build and $d/UpdateSummary.xml which will be used to build the dashboard.
  - Server/XSL/Configure.xsl
    produces $d/Configure.html which displays the configure details for that build and $d/ConfigureSummary.xml which will be used to build the dashboard.
  - Server/XSL/Build.xsl
    produces $d/Build.html, an empty file which indicates that this step has been run, $d/BuildError.html which displays that build's error details, $d/BuildError.html which displays that build's warning details, and $d/BuildSummary.xml which will be used to build the dashboard, and the dashboard's build summary.
  - Server/XSL/Test.xsl
    produces $d/Test.html which displays that build's list of tests along with summary details, (probably a $d/Results/__$t.html for each test $t with the test output,) and $d/TestSummary.xml which will be used to build the dashboard, and the dashboard's all builds test summary. If there are any identified measurements in a test output, Test.xsl creates a table labelling the rows with the "name"'s of the measurements and filling in the entries with the specific measurement. If the measurement was an image, Test.xsl extracts the base64 data for that image from Test.xml into a separate file. An img tagset is placed in the measurement table, referencing an image whose name is constructed from the "measurement name" (i.e. the value of the "name" attribute in the tag). (DashboardManager.tcl then converts all base64 files into the unencoded files.)
- The manager examines the summary files using functions like GetErrorsWarningsFromBuildSummary() in Client/Utility.tcl to decide if and what to send in an email. It records if it has already sent an email in this module by leaving an empty mailsent.txt file in the submission directory.
The Manager then starts (over)-writing Dashboard.xml in the Dashboard directory with the information about date, etc. It then concatenates the UpdateSummary.xml, ConfigureSummary.xml, etc. from each of the day's submission directories to form a finished Dashboard.xml.
If needed, Server/XSL/Dashboard.xsltakes Dashboard.xml and produces Dashboard.html, TestOverview.xml and BuildOverview.xml. Needed means if Dashboard.xml is newer that Dashboard.html. TestOverview.xml is only produced if a newly submitted test file was processed above.
If needed, Server/XSL/BuildOverview.xsltakes BuildOverview.xml and produces BuildOverview.html. Needed means if BuildOverview.xml is newer that BuildOverview.html.
If needed, Server/XSL/TestOverview.xsltakes TestOverview.xml and produces TestOverview.html, and others.

Things I haven't explained:

How the specialist builds work.
How the notes system works
How the detailed test information and summaries are created.
How the nightly server update information is built.

Feel free to fix any errors.

Ian Scott
24 Feb 2003