CDash:Build Management

CDash 1.6 implements a beta version of remote build management from CDash. This page describes how to enable build management in CDash and will be updated as we improve the concept.

Introduction

The main idea of the CDash/CTest build management is to have clients announce their availability to the CDash server. The server then schedules and allocates the proper clients based on build requirements.

Installation

In your config.local.php put the following line:

   $CDASH_MANAGE_CLIENTS = '1';

Then create a machine description XML file (mymachine.cdash.xml) on each client machine. Note that you can have multiple <compiler>, <cmake>, <library> and <program> tags within the file, if you have multiple compilers for instance.

 <?xml version="1.0" encoding="UTF-8"?>
 <cdash>
   <system>
     <platform>windows</platform>
     <version>7</version>
     <bits>32</bits>
     <basedirectory>C:/CDashClient</basedirectory> 
   </system>
   <compiler>
     <name>MSVC</name>
     <version>2009</version> 
     <generator>Visual Studio 9 2008</generator> 
   </compiler>
   <cmake>
     <version>2.8</version> 
     <path>C:/Program Files/CMake 2.8/bin</path> 
   </cmake>
   <library>
     <name>OpenGL</name>
     <version>1.3</version>
     <include>C:/OpenGL</include>
     <path>C:/OpenGL-bin</path>
   </library>
   <program>
     <name>git</name>
     <version>1.7</version>
     <path>C:/git-bin.git</path>
   </program>
 </cdash>

Then create the following CTest script: mymachine.ctest. This script uses the mymachine.cdash.xml to send the site description to CDash, then loop and ask CDash for build to perform:

 # These variables define the system and should be set
 # In the future CTest might be able to determine this automatically
 set(CDASH_SITENAME "yellowstone.kitware")
 set(CDASH_SYSTEMNAME "Ubuntu-32bits")
 set(CDASH_SITE_CONFIG_FILE "/workspace/Dashboard/yellowstone.cdash.xml")
 set(CDASH_TEMP_DIRECTORY "/workspace/Dashboard/tmp")
 set(CTEST_EXECUTABLE "/Workspace/CMake-bin/bin/ctest")
 set(CTEST_DROP_SITE "dash1old")

 # Everything below this line shouldn't be modified
 set(CTEST_SOURCE_DIRECTORY "${CDASH_TEMP_DIRECTORY}/dummysource")
 set(CTEST_BINARY_DIRECTORY "${CDASH_TEMP_DIRECTORY}/dummybin")
 set(CTEST_DROP_URL "/CDash/submit.php")
 set(CTEST_DROP_METHOD "http")
 set(CTEST_DROP_LOCATION ${CTEST_DROP_URL}?sitename=${CDASH_SITENAME}&systemname=${CDASH_SYSTEMNAME}&submitinfo=1)
 set(CTEST_DROP_SITE_CDASH true)
 ctest_submit(FILES ${CDASH_SITE_CONFIG_FILE} RETURN_VALUE res)

 IF(NOT "${res}" STREQUAL "0")
   MESSAGE(FATAL_ERROR "Cannot submit site file")
 ENDIF(NOT "${res}" STREQUAL "0")

 # Get the siteid from CDash
 SET(CDASH_URL ${CTEST_DROP_METHOD}://${CTEST_DROP_SITE}${CTEST_DROP_URL})
 SET(CDASH_CTESTSCRIPT_FILE ${CDASH_TEMP_DIRECTORY}/ctestscript.cdash)
 file(DOWNLOAD ${CDASH_URL}?sitename=${CDASH_SITENAME}&systemname=${CDASH_SYSTEMNAME}&getsiteid=1 ${CDASH_CTESTSCRIPT_FILE})
 file(READ ${CDASH_CTESTSCRIPT_FILE} CDASH_SITE_ID)
 string(STRIP ${CDASH_SITE_ID} CDASH_SITE_ID)

 IF(${CDASH_SITE_ID} MATCHES  "ERROR:")
   MESSAGE(FATAL_ERROR ${CDASH_SITE_ID})
 ENDIF(${CDASH_SITE_ID} MATCHES  "ERROR:")

 IF(${CDASH_SITE_ID} EQUAL "0")
   MESSAGE(FATAL_ERROR "Cannot define site id")
 ENDIF(${CDASH_SITE_ID} EQUAL "0")

 MESSAGE("SiteId="${CDASH_SITE_ID})

 # Start the loop
 while (${CTEST_ELAPSED_TIME} LESS 36000)

   # Check if CDash has a job to run
   file(DOWNLOAD ${CDASH_URL}?siteid=${CDASH_SITE_ID}&getjob=1 ${CDASH_CTESTSCRIPT_FILE})
 
   file(READ ${CDASH_CTESTSCRIPT_FILE} CDASH_CTEST_SCRIPT)

   IF(${CDASH_CTEST_SCRIPT} EQUAL "0")
     MESSAGE("Nothing to do...")
   ENDIF(${CDASH_CTEST_SCRIPT} EQUAL "0")

   # If it's not zero that means CDash has something for me
   IF(NOT ${CDASH_CTEST_SCRIPT} EQUAL "0")
     # Run the script
     MESSAGE("Running script")
     SET(CTEST_RUN_CURRENT_SCRIPT 0)
     ctest_run_script(${CDASH_CTESTSCRIPT_FILE})
     # Mark the job has done
     file(DOWNLOAD ${CDASH_URL}?siteid=${CDASH_SITE_ID}&jobdone=1 ${CDASH_CTESTSCRIPT_FILE})
     MESSAGE("DONE Running script")
   ENDIF(NOT ${CDASH_CTEST_SCRIPT} EQUAL "0")
   ctest_sleep(20)
 endwhile(${CTEST_ELAPSED_TIME} LESS 36000)

Start the script:

 ctest -S mymachine.ctest -V (verbose to see what's happening)

One you launch the script on one client, go on CDash, go to the user.php page and click on "Schedule build" under "Actions" for a project (the icon of a floppy).