Jump to: navigation, search

Using Hudson/Building a software project

Hudson Continuous Integration Server
Mailing ListForumsIRC
Help Wanted
Bug Day
Browse Source
Hudson-bust.png Building a Software Project with Hudson

Hudson can be used to perform the typical build server work, such as doing continuous/official/nightly builds, run tests, or perform some repetitive batch tasks. This is called "free-style software project" in Hudson.

Setting up the project

Go to Hudson top page, select "New Job", then choose "Build a free-style software project". This job type consists of the following elements:

  • optional SCM, such as CVS or Subversion where your source code resides.
  • optional triggers to control when Hudson will perform builds.
  • some sort of build script that performs the build (ant, maven, shell script, batch file, etc.) where the real work happens
  • optional steps to collect information out of the build, such as archiving the artifacts and/or recording javadoc and test results.
  • optional steps to notify other people/systems with the build result, such as sending e-mails, IMs, updating issue tracker, etc.

For more details, click the (?) icons in the configuration page.

Hudson sets some environment variables that are available to shell scripts, Windows batch files, Ant and Maven^[#1]^ files that are executed by Hudson. A list of environment variables and how they are used are shown below.

Builds for Non-Source Control Projects

There is sometimes a need to build a project simply for demonstration purposes or access to a SVN/CVS repository is unavailable. By choosing to configure the project  as "None" under "Source Code Management" you will have to:

  1. Build the Project at least once, (it will fail), but Hudson will create the structure hudson/jobs/PROJECTNAME/workspace
  2. Copy the project files to hudson/jobs/PROJECTNAME/workspace
  3. Build again and configure appropriately

Hudson Set Environment Variables

When a Hudson job executes, it sets some environment variables that you may use in your shell script, batch command, Ant script or Maven POM ^[#1]^. The following table contains a list of all of these environment variables.

Environment Variable Description
BUILD_NUMBER The current build number, such as "153"
BUILD_ID The current build id, such as "2005-08-22_23-59-59" (YYYY-MM-DD_hh-mm-ss)
JOB_NAME Name of the project of this build. This is the name you gave your job when you first set it up. It's the third column of the Hudson Dashboard main page.
BUILD_TAG String of {{hudson-$\{JOBNAME\}-$\{BUILD_NUMBER\}}}. Convenient to put into a resource file, a jar file, etc for easier identification.
EXECUTOR_NUMBER The unique number that identifies the current executor (among executors of the same machine) that's carrying out this build. This is the number you see in the "build executor status", except that the number starts from 0, not 1.
JAVA_HOME If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to have $JAVA_HOME/bin.
WORKSPACE The absolute path of the workspace.
SVN_REVISION For Subversion-based projects, this variable contains the revision number of the module. If you have more than one module specified, this won't be set.
CVS_BRANCH For CVS-based projects, this variable contains the branch of the module. If CVS is configured to check out the trunk, this environment variable will not be set.

Shell Scripts and Windows Batch Commands

If you're using a shell script to do your build, you can either put these environment variables directly into your shell scripts, or call them as parameters in your shell script. Below is an example how this can be done:

Shell script.jpg

If you are executing a Windows Batch Command, the variables should be referenced using the %VARIABLE_NAME% pattern. For example:


Ant Scripts

If you're using an Ant script to do your build, you may include environment variables in property settings. Click on the *{_}Advanced..._* button just below where you put the Ant targets you want to build. This will display the _Properties_ box. Below is an example how to use the Properties box to set Ant properties with Hudson Environment variables:

Ant script.jpg

As an alternative, you can use the Environmental prefix to pull in all environmental variables as properties right inside your Template:Build.xml file.

Below is an example how to set the property "label" to include the Project Name and the Build Number:

<property environment="env"/> 
<property name="label" value="${env.JOB_NAME}-${env.BUILD_NUMBER}"/>

Configuring automatic builds

Builds in Hudson can be triggered periodically (on a schedule, specified in configuration), or when source changes in the project have been detected, or they can be automatically triggered by requesting the URL:


This allows you to hook Hudson builds into a variety of setups. For more information (in particular doing this with security enabled), see Remote access API.

Builds by changes in Git

To perform builds whenever someone pushes a change to a Git repository, use a post-receive hook to trigger a new build. The hook can use wget/curl to access the build URL shown above, or send email to trigger a build as described below, but these approaches are specific to a particular job. You could configure Hudson to poll your source control system periodically and start new builds when changes have been detected. But this has the disadvantage of causing overhead when there have been no changes, and responding slowly when there have been changes. The best approach is to trigger polling with the post-receive hook. Configure the job for polling but leave the schedule empty or specify a long period, e.g., @yearly. Then set up the post-receive hook in the Git repository server like this:

In file .git/hooks/post-receive:

curl http://HUDSON/git/notifyCommit?url=REPOSITORY_URL

Replace HUDSON with your Hudson host name and REPOSITORY_URL with the Git repository URL used in your jobs. In Git, unlike Subversion, a single repository sometimes has multiple URLs to access it. In such a case, simply execute the curl commands multiple times with all the different URLs you actually use in jobs.

Any push to the repository will trigger the post-receive hook. When Hudson receives the notifyCommit, it will trigger polling for all jobs set up to poll the specified Git repository URL. In addition to starting builds in a timely manner, this prevents Hudson from running a build with no relevant changes, e.g., for commits affecting branches that are unrelated to the job.

Builds by changes in Subversion/CVS

To perform builds whenever someone makes a change in the repository, use a post-commit hook (hooks/post-commit for Subversion, CVSROOT/loginfo for CVS) to trigger a new build. The hook can use wget/curl to access the build URL shown above, or send email to trigger a build as described below. The trigger may use /polling instead of /build at the end of the URL to make Hudson poll the SCM for changes rather than building immediately. This prevents Hudson from running a build with no relevant changes for commits affecting modules or branches that are unrelated to the job. When using /polling, the job must be configured for polling, but the schedule can be empty. Or, you could configure Hudson to poll your source control system periodically and start new builds when the changes have been detected.

Builds by e-mail (sendmail)

If you have the root account of your system and you are using sendmail, I found it the easiest to tweak /etc/aliases and add the following entry:

hudson-foo: "|/bin/wget -o /dev/null http://YOURHOST/hudson/job/PROJECTNAME/build"

and then run newaliases command to let sendmail know of the change. Whenever someone sends an e-mail to "hudson-foo@yoursystem", this will trigger a new build. See [this|http://www.developer.com/open/article.php/615931] for more details about configuring sendmail.

Builds by e-mail (qmail)

With qmail, you can write Using Hudson/Building a software project/var/qmail/alias/.qmail-hudson as follows:

|/bin/wget -o /dev/null http://YOURHOST/hudson/job/PROJECTNAME/build" 

^1^ {anchor:1}Maven requires that you include the parameter as part of the build goals. \\ Example Hudson configuration for the Maven "Goals" field: clean install \-DBUILD_NUMBER=$\{BUILD_NUMBER\}