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.

Server Configuration

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

   $CDASH_MANAGE_CLIENTS = '1';

As administrator of a project. Go to the administration page for the project and click on the Clients tab. A default template is created by default but you can edit as needed for the project. This is the CTest script that will be appended and sent to the client.

CDash CTest variables

CDash defines the following variables:

• JOB_BUILDTYPE: Track of the submission: experimental, nightly, continuous
• PROJECT_NAME: Name of the project
• JOB_REPOSITORY: Repository where to get the source code
• JOB_MODULE: Repository module defined by the scheduler
• JOB_TAG: Repository tag defined by the scheduler
• JOB_BUILDNAME_SUFFIX: Suffix for the buildname defined by the scheduler
• JOB_CMAKE_GENERATOR: Generator corresponding to the compiler selected
• JOB_BUILD_CONFIGURATION: Build type
• CLIENT_BASE_DIRECTORY: Base directory on the client machine
• CLIENT_CMAKE_PATH: Path to CMake on the client
• CLIENT_SITE: Name of the client site
• JOB_OS_NAME: Name of the OS on the client
• JOB_OS_VERSION: Version of the OS on the client
• JOB_OS_BITS: Number of bits for the OS on the client
• JOB_COMPILER_NAME: Name of the compiler on the client
• JOB_COMPILER_VERSION: Version of the compiler on the client
• CTEST_DROP_METHOD: HTTP or HTTPS
• CTEST_DROP_SITE_CDASH: Set to 1
• CTEST_DROP_SITE: Sites by default is the current CDash
• CTEST_DROP_LOCATION: Location by default is the current CDash

Job-Specific Scripts

You can also use custom CTest scripts for a specific job instead of using the same script across a project.

On the Schedule Builds page, check the check box and fill in the text area marked Job-specific client script with the desired script. All the same variables mentioned above will be defined for this custom script. If you don't define a job-specific script, the project-level client script will be used.

CDash CTest macros

• JOB_FAILED Macro: Use this macro to mark the client has failed to CDash so the submission can be rescheduled automatically (not implemented yet)

Program variables

Foreach <program> tag in the client.cdash.xml file, CDash creates a variable corresponding to the name and version of the program and the path. CDash also creates a variable with just the name with the newest version of the program.

 <program>
    <name>git</name>
    <version>1.7</version>
    <path>C:/git-bin.git</path>
  </program>

will result in

 SET(CLIENT_EXECUTABLE_GIT "C:/git-bin.git");
 SET(CLIENT_EXECUTABLE_GIT_1_7 "C:/git-bin.git");

Client Configuration

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.

The platform tag can be one of these:

 Windows
 Linux
 Mac

The OS version can be one of these

 Vista
 7
 Ubuntu
 Debian
 Fedora
 CentOS
 Tiger
 Leopard
 SnowLeopard

The XML file looks like this:

 <?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...")
     ctest_sleep(20)
   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")
   
 endwhile(${CTEST_ELAPSED_TIME} LESS 36000)

Start the script:

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