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 Set Environment Variable Hudson sets some environment variables that are available to shell scripts, Windows batch files, and Ant files that are executed by Hudson^1^. 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, or Ant script¹. The following table contains a list of all of these environment variables.

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:

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:

As an alternative, you can use the Environmental prefix to pull in all environmental variables as properties right inside your 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:

http://YOURHOST/hudson/job/PROJECTNAME/build

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

Alternatively, if you'd like to trigger builds from scripts when Hudson security is enabled, select "Trigger builds remotely" option in your project configuration, and provide an authorization token there. Now you can trigger your builds via the following URL: http://YOURHOST/hudson/job/PROJECTNAME/build?token=YOUR_TOKEN_HERE

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 for more details about configuring sendmail.

Builds by e-mail (qmail)

With qmail, you can write /var/qmail/alias/.qmail-hudson as follows:

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

Builds by changes in CVS

To perform builds whenever someone makes a change in the repository, either invoke the above program from /CVSROOT/loginfo, or hook up CVS notification e-mails as explained above.

Or, you could configure Hudson to poll your source control system periodically and start new builds when the changes have been detected.

¹ Note: I believe Maven builds also have access to these variables. Can someone verify this?