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.
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.
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
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)
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");
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:
Start the script:
ctest -S mymachine.ctest -V (verbose to see what's happening)