View source for Documentation/Nightly/Developers/Tutorials/DashboardSetup

<noinclude>{{documentation/versioncheck}}</noinclude>
=Prerequisites=

Use the latest CMake stable release.

=Setup=

Disable detachedHead warnings:
<pre>
git config --global advice.detachedHead false
</pre>

Follow these instructions to set up dashboard: (by JC, from [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2011/006703.html])

<pre>
$ cd ~
$ mkdir Dashboards
$ mkdir DashboardScripts
$ cd DashboardScripts
$ wget http://svn.slicer.org/Slicer4/trunk/CMake/SlicerDashboardScript.TEMPLATE.cmake
$ mv SlicerDashboardScript.TEMPLATE.cmake <MachineName>_<OperatingSystem>-64bits_slicer_release_nightly.cmake
</pre>

Edit the file <code><MachineName>_<OperatingSystem>-64bits_slicer_release_nightly.cmake</code> to match
your machine settings. You should update the following variables:

<pre>
set(MY_OPERATING_SYSTEM   "<OperatingSystem>") # Windows, Linux, Darwin...
set(MY_COMPILER           "g++4.4.3")
set(MY_QT_VERSION         "4.7.4")
set(QT_QMAKE_EXECUTABLE   "$ENV{HOME}/Projects/QtSDK-1.2/Desktop/Qt/474/gcc/bin/qmake")
set(CTEST_SITE            "karakoram.kitware")
set(CTEST_DASHBOARD_ROOT  "$ENV{HOME}/Dashboards/")
...
set(CTEST_BUILD_CONFIGURATION "Release")
...
set(SCRIPT_MODE "nightly")
</pre>

If git and svn are not in the path, make sure to set the variables CTEST_SVN_COMMAND and CTEST_GIT_COMMAND.

By default, the following directory will be created:
   <CTEST_DASHBOARD_ROOT>/Slicer-<DIRECTORY_IDENTIFIER>        # Source directory
   <CTEST_DASHBOARD_ROOT>/Slicer-<DIRECTORY_IDENTIFIER>-build  # Build directory

The associated build options will be combined together to create an empty text file with the following name:
   <CTEST_DASHBOARD_ROOT>/Slicer-<DIRECTORY_IDENTIFIER>-build - <BUILD_OPTIONS_STRING>-<CTEST_BUILD_CONFIGURATION>-<SCRIPT_MODE>.txt"

This approach has been implemented to keep build directory short and overcome [http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath path length limitation specific to windows].

It means that if you setting up more than on client in a given <code><CTEST_DASHBOARD_ROOT></code> folder, you MUST increment the value associated with <code>DIRECTORY_IDENTIFIER</code> variable.

Finally, you can use <code>CTEST_BUILD_FLAGS</code> to set the number of CPUs to be used by ''make'' (eg, -j4), and CTEST_PARALLEL_LEVEL to set the number of tests to run in parallel (see comments in the [http://svn.slicer.org/Slicer4/trunk/CMake/SlicerDashboardScript.TEMPLATE.cmake configuration script]).


== Scheduling on Unix-like ==

So that your dashboard can automatically start at 11pm daily, you could add an entry similar to the following one in your <code>[http://en.wikipedia.org/wiki/Cron crontab]</code>. (On ubuntu, I am running <code>crontab -e</code> to edit the current user cron list)

<pre>
0 23 * * * /path/to/cmake-2.8.7/bin/ctest -S /Users/JOE/DashboardScripts/<MachineName>_<OperatingSystem>-64bits_slicer_release_nightly.cmake -VV -O /Users/JOE/Dashboards/Logs/<MachineName>-<OperatingSystem>-64bits_slicer_release_nightly.log
</pre>

==Scheduling on Mac OS X==
Mac OS X is deprecating the use of cron in favor of launchd.  

Create a file $HOME/Library/LaunchAgents/org.slicer.NightlyDashboard.plist

This is Jim's plist file which has extra EnvironmentVariables to get through his firewall.  
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>org.slicer.NightlyDashboard</string>

  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/ctest</string>
    <string>-S</string>
    <string>/Users/millerjv/Projects/Slicer4-Dashboard/SlicerDashboardScript.cmake</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
        <key>ALL_PROXY</key>
        <string>proxy.research.ge.com:8080</string>
        <key>http_proxy</key>
        <string>proxy.research.ge.com:8080</string>
        <key>RSYNC_PROXY</key>
        <string>proxy.research.ge.com:8080</string>
  </dict>

  <key>Nice</key>
  <integer>1</integer>

  <key>StartCalendarInterval</key>
  <dict>
        <key>Hour</key>
        <integer>1</integer>
        <key>Minute</key>
        <integer>03</integer>
  </dict>

  <key>StandardErrorPath</key>
  <string>/tmp/org.slicer.NightlyDashboard.err</string>

  <key>StandardOutPath</key>
  <string>/tmp/org.slicer.NightlyDashboard.out</string>
</dict>
</plist>
</pre>

You can manually load this agent using
<pre>
$ launchctl load $HOME/Library/LaunchAgents/org.slicer.NightlyDashboard.plist
</pre>
and the agent will be reloaded automatically on a reboot.

It seems I have to be logged onto the console for the launch agent to get installed and run.  What I do is log on, then select "Login Window..." so that other people can log onto the console. This is suboptimal as I need to do this after each reboot of the system.


==Scheduling on Windows==

===Create a .bat file that performs the build===

For example, a clean nightly build can be performed by a batch file like this:
<pre>
rmdir /S /Q c:\SAB\Slicer-build-64bit-nightly
"c:\Program Files (x86)\CMake 2.8\bin\ctest.exe" -S .\Windows7-64bits_Slicer_Release_Nightly.cmake -VV c:\SAB\Logs\Windows7-64bits_Slicer_Release_Nightly.log -C Release
</pre>

===Create a new scheduled task that runs the .bat file===
* Windows XP: Create a new scheduled task at Control Panel / Scheduled Tasks / Add Scheduled
* Windows 7: Task scheduler can be found at Start Menu / All Programs / Accessories / System Tools / Task Scheduler.

==Setting up a continuous dashboard==

Similarly if you want to setup a continuous dashboard,

<pre>
$ cp <MachineName>_<OperatingSystem>-64bits_slicer_release_nightly.cmake <MachineName>_<OperatingSystem>-64bits_slicer_release_continuous.cmake
</pre>

Edit <code><MachineName>_<OperatingSystem>-64bits_slicer_release_continuous.cmake</code> and set

<pre>
set(SCRIPT_MODE "*continuous*")
</pre>

Then add the corresponding entry in <code>crontab</code> so that it starts everyday at 6am:

<pre>
0 6 * * * /path/to/cmake-2.8.7/bin/ctest -S /Users/JOE/DashboardScripts/<MachineName>_<OperatingSystem>-64bits_slicer_release_continuous.cmake -VV -O /Users/JOE/Dashboards/Logs/<MachineName>_<OperatingSystem>-64bits_slicer_release_nightly.log
</pre>

The output of the build is contained in <code>ctest_package_make_package_output.txt</code> in your slicer build directory, you can check this file if something went wrong.

= Remarks =

==Setting up a dashboard on a Windows machine==
=== Disabling TortoiseSVN Icon Overlay ===
If you're using an interface for version control such as TortoiseSVN, make sure in the Icon Overlay settings that the status cache is set to None.
[[Image:TortoiseGit.png|thumb|300px|Make sure the status cache is set to "None."]]

=== Keep short path ===
Keep the paths to your Nightly, Continuous, and Experimental directories as terse as possible.  A good standard is <code>C:\D</code> for dashboards, and C:\D\<N,C,E> subdirectories for Nightly, Continuous, and Experimental.  Otherwise, CMake will choke on the paths.

=== How can I prevent the “… has stopped working” window ===

As documented [http://msdn.microsoft.com/en-us/library/2ac5yxx6(VS.80).aspx here], set registry key <code>HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\DbgJITDebugLaunchSetting</code> value to 1.

Value 1 simply return control. This results in a stack dump, after which the process is terminated.

This has been documented while trying to prevent the dialog "Microsoft Visual Studio 8 has stopped working" from appearing when Slicer extensions dashboard were running. The details associated with the dialog were:
<pre>
Problem signature:
  Problem Event Name:	BEX
  Application Name:	devenv.exe
  Application Version:	9.0.21022.8
  Application Timestamp:	47317b3d
  Fault Module Name:	VCProjectEngine.dll_unloaded
  Fault Module Version:	0.0.0.0
  Fault Module Timestamp:	47318038
  Exception Offset:	72dbdce0
  Exception Code:	c0000005
  Exception Data:	00000008
</pre>

Reference:
* http://stackoverflow.com/questions/2507464/how-can-i-prevent-the-has-stopped-working-window-on-my-server-2008-r2-dev
* http://msdn.microsoft.com/en-us/library/2ac5yxx6(VS.80).aspx

===Lockhunter: Unlock directories or folders ===
Often on Windows, once a dashboard build is started, it is impossible to delete anything from the source or build directory.  Windows will report that this file is currently in use by another program, or "locking" it.  For this, we recommend installing [http://www.lockhunter.com Lockhunter].
[[Image:LockHunderExample.png|thumb|left|300px| Lockhunter screenshot]]