CDash:Build Management: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
No edit summary
 
(17 intermediate revisions by 3 users not shown)
Line 4: Line 4:
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.
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 =
= Server Configuration =
In your config.local.php put the following line:
In your config.local.php put the following line:


     $CDASH_MANAGE_CLIENTS = '1';
     $CDASH_MANAGE_CLIENTS = '1';


Then create a machine description XML file (mymachine.cdash.xml) on each client machine:
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"?>
   <?xml version="1.0" encoding="UTF-8"?>
Line 34: Line 105:
       <path>C:/OpenGL-bin</path>
       <path>C:/OpenGL-bin</path>
     </library>
     </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>
   </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:
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)


  # These variables define the system and should be set
Other configurable options you may want to add in mymachine.ctest:
  # In the future CTest might be able to determine this automatically
*'''CLIENT_TIME_LIMIT''': set to the number of seconds the script will run in total (default is 36000)
  set(CDASH_SITENAME "mysite")
*'''ALLOWED_PROJECTS''': set to a list of project names that are allowed to submit jobs to this machine (default is to allow all projects)
  set(CDASH_SYSTEMNAME "Windows7-32bits")
  set(CDASH_SITE_CONFIG_FILE "C:/CDashExample/mymachine.cdash.xml")
  set(CDASH_TEMP_DIRECTORY "C:/CDashExample")
  set(CTEST_EXECUTABLE "C:/Program Files/CMake 2.8/bin/ctest")
  set(CTEST_DROP_SITE "localhost")


  # Everything below this line shouldn't be modified
Download the driver script cdash_client_common.ctest and place it in the same directory as mymachine.ctest:
  set(CTEST_SOURCE_DIRECTORY "${CDASH_TEMP_DIRECTORY}/dummysource")
 
  set(CTEST_BINARY_DIRECTORY "${CDASH_TEMP_DIRECTORY}/dummybin")
[[https://github.com/Kitware/CDash/blob/master/scripts/cdash_client_common.ctest]]
  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)
  SET(CTEST_COMMAND "${CTEST_EXECUTABLE} -S ${CDASH_CTESTSCRIPT_FILE}")
  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_CTEST_SCRIPT_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:
Start the script:


   ctest -S mymachine.ctest -V (verbose to see what's happening)
   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).

Latest revision as of 17:05, 13 March 2018

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)