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, simply 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>
   <allowedproject>ProjectX</allowedproject>
   <allowedproject>ProjectY</allowedproject>
   <allowedproject>ProjectZ</allowedproject>
 </cdash>

NOTE: The <allowedproject> tags are optional. If you don't specify a list of projects that are allowed to build jobs on the machine, then any project will be allowed to send jobs to the machine.

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
 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")
 set(CTEST_DROP_URL "/CDash/submit.php")
 
 # Now include the common setup for cdash
 include(cdash_client_common.ctest)

Other configurable options you may want to add in mymachine.ctest:

• CLIENT_TIME_LIMIT: set to the number of seconds the script will run in total (default is 36000)
• ALLOWED_PROJECTS: set to a list of project names that are allowed to submit jobs to this machine (default is to allow all projects)

Download the driver script cdash_client_common.ctest and place it in the same directory as mymachine.ctest:

[[1]]

Start the script:

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