This repository contains much of the configuration which defines what Pulse projects do and some Coin shared code. Below you will find documentation only for the first one. HOW IT WORKS: ============= Each Pulse project is made up of several stages. A stage is used to test a particular configuration of the tested product. Like this: Qt 4.7 Autotests | +-- linux-g++-32 Ubuntu 9.10 | +-- win32-msvc2008 Windows XP | +-- macx-g++ cocoa OSX 10.6 | ...etc The combination of project & stage names are used to look up all the settings for the current test. Effectively, all Pulse projects and stages should call exactly the same top-level script, and that script looks up the settings for the test in a big hash, where the key is the combination of project and stage name, and the value is the settings and script needed to do the test. LAYOUT: ======= Note that project and stage names have whitespace and special characters replaced with an `_' when mapping to a filename. projects//properties This directory contains one file named after each Pulse property to set. During the test, the Pulse property named after the file will be set to the first line of content in the file (properties with values containing a newline character aren't supported). The values here may refer to other Pulse properties using the syntax $(my.property), and may refer to environment variables using the syntax ${MY_ENVIRONMENT_VARIABLE}. If you want to include a literal $ or \ in the value, you must escape it with \ (i.e., use \$ or \\). Having a cyclic dependency between properties is an error. These properties are global to all build stages for the given project. projects//environment This directory contains one file named after each environment variable to set. During the test, the environment variable named after the file will be set to the first line of content in the file. The values here may refer to other Pulse properties in the same way as values in the `properties' directory. Please note that environment variables can refer to Pulse properties, but not to other environment variables. These environment variables are global to all build stages for the given project. projects//repository This file contains a single line specifying an additional git repository needed to do the test. The format is: git/uri#gitbranch directory ...which will cause the specified git repository and branch to be checked out into the given directory. For Qt5, this will usually be: git://gitorious.org/qt/qtqa _qtqa_latest ... as most test scripts are located in this repository at time of writing. By convention, the destination directory for the clone starts with the _ character, to differentiate it in build logs from directories contained in the source under test. This file is optional if no extra repo needs to be checked out for the test. projects//script This file contains a single line specifying the script to run in order to do the test. Please do not try to do anything tricky here. In particular, don't put any test logic here! Just run a single command stored _outside_ of this repository. This will usually be something like: perl _qtqa_latest/scripts/setup.pl --install && perl _qtqa_latest/scripts/.pl projects//forcesuccess If this file exists and contains a true value, then test.pl will exit with a 0 exit code even when the test fails. This is intended to be used for "trial" stages which should be put into Pulse but may not yet be 100% reliable. Using this, the stage can be put into the true production environment with minimal risk of causing build failures. The forcesuccess file can later be deleted once the stage is thought to be stable. Note that `forcesuccess' is unable to catch certain classes of critical failure, such as a hanging build. projects//inherits projects//stages//inherits If present, these are symbolic links to another project or stage which the current project or stage inherits from. All settings from the parent project/stage will apply, unless otherwise overriden. projects//stages//properties projects//stages//environment projects//stages//repository projects//stages//script projects//stages//forcesuccess These work identically to their counterparts in the project directory. When a file exists in both the project and stage directory, the version in the stage directory is preferred. Therefore, one can set default values in the project directory and override them on a per-stage basis. manual_overrides/properties manual_overrides/environment These work identically to their counterparts in the project directories but they're applied only when running test.pl outside of Pulse. Use this sparingly! It's mainly a hack to prevent people from accidentally uploading binary packages, test results, etc. Without this, one could easily clobber real test artifacts when testing locally. test.pl guesses that it's running outside of Pulse based on the absence of certain environment variables set by Pulse. CAVEATS: ======== Adding projects/stages in this source tree does _not_ automatically create the corresponding projects/stages in Pulse. That step needs to be done manually. There is no way to represent "required resources" here. This means that the part of the Pulse configuration specifying which machines a stage can run on remains not under source control. This can be mitigated by reducing our usage of "required resources" as much as possible. In particular, requiring a resource should ideally _not_ set any additional properties when doing a test. There is (currently) no way to represent per-agent properties here. This could be implemented if it seems worth the effort. Since this repository uses symbolic links in some places, please be very careful making any changes on Windows. It is easy to accidentally destroy the symbolic links when working on that operating system.