Jump to: navigation, search

Using Hudson/Building a multi-configuration project

Hudson Continuous Integration Server
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source
Hudson-bust.png Building a multi-configuration project with Hudson











What's this?

Hudson comes with a job type called "multi-configuration project", which expands [free-style software project|Building a software project] to a large number of parameterized build configurations.

Here's how this job type is typically useful. Let's say you are developing [the JAX-WS RI|https://jax-ws.dev.java.net/]. This project needs its tests to run on many different environments. We need to test on Solaris, Linux, and Windows. We need to test with Glassfish, Tomcat, and Jetty. We need to test with JDK5 and JDK6. We need to test with two kinds of different StAX implementations. If you test all possible combinations, you have 36 different combinations. With free-style software project, you need to set up 36 different jobs that are almost identical to each other. This is clearly unmaintainable.

Matrix project is designed to handle situations like this. It lets you set up a single configuration with user-defined parameters, and when you tell Hudson to build it, it will build all the possible combinations of parameters and aggregate results for easier comprehension.

In addition to testing, this job type should be also useful for building a software project for multiple target platforms.

Configuration Axis

This job type offers two dedicated configuration parameters:

  • JDKs: you can specify multiple JDKs that add to your combination matrix. For example in the above JAX-WS example, you'd be checking both JDK5 and JDK6 to indicate that you'd like to test both.
  • Nodes: you can specify multiple slaves and labels that add to your combination matrix. For example, in the above JAX-WS example, you'd be creating labels for Windows, Solaris, and Linux, then check all three to indicate that you want each configuration to be run on all 3 kinds of nodes. See [Distributed builds] for more about labels.

You can also add arbitrary number of additional configuration axes. Each axis has a name and multiple values, and values add to the combination. These user-defined axes are passed to the build script as "variables", and it is the responsibility of your build script to recognize them and act accordingly. For example, if your main build is set up as Ant project, you'll get them as Ant properties. If it's shell script, you get environment variables, etc.

When multiple axes/JDKs/nodes are specified, all the combinations are built exhaustively. So in the earlier JAX-WS example, each matrix project run will consist of 36 sub-builds each with different configuration. All the sub-builds will check out the exact same copy of the workspace from SCM, so that you can be sure that all builds are from the same source code.

Workarounds

For issue "936 Matrix parent build shouldn't consume an executor":

First find a machine (virtual or whatever) with resources making it unusable for any other work. Add it as a slave with say 10 executors and let it be "Utilize as much as possible". Then parent job will execute on it (given you don't have other such slaves) so you will not block a good executor for such a job.