Automatic Build System

Every night an automatic build system runs to compile and test the software in the VRL group. This page is for documenting that process. Unless you are working on the build process itself, you probably don't need to know or care about these details. However, they need to be recorded somewhere, and this is as good a place as any.

The cron Job

The machine called franklin has a cron job running that every day at 1am (see /etc/cron.d/regression_test), runs a perl script created by t-staff. The script (/tstaff/bin/regtest) executes (as root) whatever it finds in /systest/bin.

Most days, what it finds in that directory is a bunch of scripts tstaff uses to manage the process and a couple of scripts called vrl_fast and vrl_slow that actually do the work.

• vrl_fast executes the script /research/graphics/tools/gfxtools-startup.sh, and then executes $G/common/build/valid/test.platform.py.
• vrl_slow does the same thing, but executes test.platform.py with the option -config $G/common/build/site/test.platform_slow.cfg.

Any scripts found in the /systest/bin directory that end in .weekly will only be run on Sundays.

To add more tests to the nightly run, use the systest tools, found in /systest/bin:

systest-link

Add a link to the /systest/bin directory. If it links to something executable, the system will run it every night. The script will run as the user (and group) of the file owner.

Use it like this: /systest/bin/systest-link /systest/projects/vrl/vrl_critical.sh /systest/bin/vrl_crit

systest-rem

Remove a link in the /systest/bin directory.

There is also a systest-req which stores metadata (i.e. documentation) about each of the links in /systest/bin and a systest-info which regurgitates it.

The Test Script (test.platform.py)

The test script is a python program at $G/common/build/valid/test.platform.py. It runs a series of tests and sends an email to people if they fail.

Configuration File

The tests run by the test.platform.py script are listed and configured in $G/common/build/site/test.platform.cfg (by default) and test.platform_slow.cfg.

The configuration file has a line for the Developer and a line for the emails of whoever wants to receive the Summary email messages. Each line after looks like this:

testName  testList  archList  scriptName  outputDir

Where:

• testName is an arbitrary string used to label this test.
• testList is a comma-separated list of email addresses who will hear about it if this test fails. Use none if nobody cares.
• archList is a comma-separated list of architectures for which this test is designed. This is just a string to be compared with the $GARCH environment variable set in gfxtools-startup.sh (see above).
• scriptName, outputDir The scriptName is executed in the outputDir directory. The script should contain the build and all the tests that need to be run. We encourage you to use a simple makefile, and to make the default target do a build and test.

The arguments are separated by spaces so there should be no spaces within the arguments.

Blank lines are ignored and the # indicates a comment.

Editing the Test Script

The actual copy of the test script that runs is the one in /research/graphics/common/build/valid. Please don't edit this (or the configuration file) directly. Instead, edit the version that is in your sandbox and use CVS to check it in. Note that the first thing test.platform.py does is check stuff out from the main CVS archive and run that. If you edit this script, expect your changes to take effect the night after whatever runs tonight because whatever you check in will be checked out into the appropriate place, but by that point, the build process is already running.