/hudson-war/src/main/webapp/help/matrix/combinationfilter.html

 1<div>
 2  By default, Hudson builds all the possible combinations of axes exhaustively. But sometimes this is too many,
 3  or may contain combinations that don't make sense.
 4  In such a situation, you can make the matrix sparse by filtering out combinations that you don't want through
 5  a Groovy expression that returns true or false.
 6
 7  <p>
 8  When you specify a Groovy expression here, only the combinations that result in <b>true</b>
 9  will be built. In evaluating the expression, axes are exposed as variables (with their values set
10  to the current combination evaluated).
11
12  <h4>Filtering based on values</h4>
13  <p>
14  For example, let's say you are building on different operating systems for
15  different compilers. Assume that your slave labels are <b>label=[linux,solaris]</b> and you have
16  created an axis as <b>compiler=[gcc,cc].</b>
17
18  Any of the following expressions will filter out <b>cc</b> builds on <b>linux</b>. Depending on
19  how you think about this constraint, you'll probably find some more intuitive than others.
20
21  <center>
22    <table>
23        <tr>
24            <td>Read "if both linux and cc, it's invalid"</td>
25            <td>
26                <pre>!(label=="linux" && compiler=="cc")</pre>
27            </td>
28        </tr>
29        <tr>
30            <td>Read "for a combination to be valid, it has to be either on solaris or on gcc."</td>
31            <td>
32                <pre>label=="solaris" || compiler=="gcc"</pre>
33            </td>
34        </tr>
35        <tr>
36            <td>Read "if on Solaris, just do cc"</td>
37            <td>
38                <pre>(label=="solaris").implies(compiler=="cc")</pre>
39            </td>
40        </tr>
41    </table>
42  </center>
43
44  <h4>Sparsening of the matrix</h4>
45  <p>
46  In addition to the specific filtering rules based on values, one can also use a special
47  variable "<tt>index</tt>", which can be used to sparsen the matrix.
48
49  <p>
50  For example, <tt>index%2==0</tt> would cut the matrix size in half by removing one
51  combination per every 2 combinations, in such a way that the coverage is still reasonable.
52  Similarly, <tt>index%3!=0</tt> would cut the matrix size into 66% by throwing
53  away every 1 out of 3 combinations.
54 <p>
55 It's possible to use Project cascading feature for this property. Please review <a href="http://wiki.hudson-ci.org/display/HUDSON/Project+cascading">
56 this document</a>.
57</div>