ohsuke Kawaguchi, a staff engineer at Sun Microsystems, released Hudson in February of 2005. Since that time, Java developers have adopted Hudson as their continuous integration server in greater and greater numbers. From February 1 through February 7 of this year, users downloaded Hudson 2855 times.
Java developers use Hudson for three major reasons: ease of installation, ease of configuration, and ease of extensibility. Additionally, Hudson handles distributed builds across multiple platforms very well. A single Hudson master can control multiple Hudson slaves installed on different operating systems. My team runs our Hudson master on Linux with a Windows slave when we have jobs that require Windows. Hudson is truly easy and enjoyable to use. Fortunately, through some .NET-specific plug-ins, .NET developers can have that same ease of use.
Hudson incorporates a simple plug-in model that has encouraged the community to author and submit over 100 plug-ins to the master Hudson repository. An additional 100 unofficial plug-ins appear in the Hudson usage statistics. While many of those extensions focus on the Java core for the Hudson community, there are enough Microsoft-specific and general-use plug-ins to make Hudson worth a serious investigation. The .NET offerings include MSBuild, NAnt, MSTest, and FxCop. In addition, Hudson has easy integration with source control systems including Subversion, Git, Team Foundation Server, Visual Source Safe, CVS, and others. See the sidebar “More Plug-ins” for descriptions of more useful extensions to the Hudson system.
I will cover the initial installation of Hudson and setting up a complete build for an example project. My project will include integrating with Google Code for source control and source browsing, compiling with MSBuild, executing NUnit tests, publishing test results, and publishing build artifacts.
To get started, you?ll need to download a few resources. You should get the latest versions for all downloads unless explicitly stated otherwise.
java -jar hudson.war
You can override the Hudson home directory using the HUDSON_HOME environment variable. To change the directory Hudson works from and the port that Hudson runs on, use this command:
-jar hudson.war --httpPort=
Assuming that you started Hudson on the default port, verify your Hudson installation by pointing your browser to http://localhost:8080/. You should see the Hudson home page as shown in Figure 1.
|Editor’s Note: This article was first published in the March/April, 2009 issue of CoDe Magazine, and is reprinted here by permission.|
Developers love Hudson for its ease of configuration. Rather than dealing with XML files, users can configure all Hudson options via a clean web UI. This includes configuring the base system, adding and configuring jobs, and installing plug-ins. Though Hudson actually stores its configuration in XML files, I have never needed to edit any XML manually while configuring Hudson.
To build .NET projects, you will need to get a few Hudson plug-ins. Fortunately, installing plug-ins, like all Hudson configuration, is simple. Follow these steps to get to plug-in configuration:
- Navigate to the Hudson home page.
- Click “Manage Hudson.”
- Click “Manage Plug-ins.”
You should find yourself at http://localhost:8080/pluginManager/. From here you will see tabs that show plug-in information, including lists of installed and available plug-ins. If your network requires you to download through a proxy server, you should configure the proxy settings under the “Advanced” tab.
Look at the list of available plug-ins under the “Available” tab. Select the checkboxes next to the plug-ins “Google Code,” “MSBuild,” and “NUnit.”
Next, click the Install button at the bottom of the page, and Hudson will download and install your selections. After installing the plug-ins, restart Hudson by terminating the program with a CTRL-C in the command window and reissuing the Hudson command.
When using Hudson’s configuration web interface, you’ll see help links for all portions of the configuration that appear as blue question marks. These links provide excellent in-line help. If you have questions about a particular configuration, be sure to check the help links first. Follow these steps to get started configuring Hudson:
- Navigate to the Hudson home page.
- Click “Manage Hudson.”
- Click “Configure System.”
You should now be the URL http://localhost:8080/configure. Note that the Hudson home directory appears at the top of the page next to the label, “Home directory.” This is where Hudson will store all configuration and jobs, including the workspace, and the previous build archive.
You will need to set the path to your msbuild.exe under the heading, “MSBuild Builder.” The Framework installs in version-specific subdirectories under C:WINDOWS directory; that’s where you’ll find msbuild.exe. The example project requires .NET 3.5. Therefore, you can use this path:
|Figure 2. Configuring Hudson Email: Fill out this form to enable failed-build email notifications.|
You will most likely want to configure the “EMail Notification” section so that you can get emails notifications of failed builds (see Figure 2). After configuring the SMTP server and the System Admin EMail Address, you can use the link provided to send yourself a test email from Hudson.
Click the “Save” button at the bottom of the page to save your configuration.
Building Hello World
Now that you have configured Hudson, you can add your first build. A Hello World project has been setup at Google Code for this purpose. Since the source repository has public read-only access, anyone is welcome to set up a build for this project.
Creating the Base Project Configuration
Navigate to the home page for your Hudson installation at http://localhost:8080 and then click on New Job. Name your project Hello_World, select the “free-style software project” option, and click OK.
At a minimum, you will need to configure the project name, source code repository, build trigger, and build steps to get anything useful. Here are the configurations:
Project Name: Hello_WorldGoogle code website: http://code.google.com/p/helloworlddotnet/Source Code Management: Google CodeBuild Triggers: Poll SCMSchedule: * * * * *
The schedule setting tells Hudson to check source control for changes every minute. To reduce the polling interval, see the help link for more instructions.
To add a build step, click “Add build step” in the “Build” section, and then select “Build a Visual Studio project or solution using MSBuild.” You can then configure the build file and command arguments as follows:
MsBuild Build File: HelloWorld.slnCommand Line Arguments: /t:Rebuild
Save the configuration, and then press the “Build Now” link in the upper-left to get your first build. Hudson will create a workspace, download the latest source code, and rebuild the project. When the build starts, a new entry will appear in the “Build History” panel on the left-hand side of the browser. You can watch the console output of the build by clicking on the build timestamp link in the “Build History” box, then clicking on “Console Output.”
Source Code Integration
Hudson comes with the ability to talk with many source control systems. Some of them, like Subversion and CVS, ship with Hudson. Others, like Team Foundation Server and Git, require a plug-in. With the Google Code plug-in installed, Hudson will provide links through Google?s REST API so that with a couple of clicks, you can navigate from your Hudson build to the Google Code display of the change set for that build. I checked in one change to the repository after I set up the Hello World build for this article, and you can see the link that Hudson provides to Google Code in Figure 3. Following the link takes you to the Google Code website to display the changes as shown in Figure 4.
The “Changes” link appears after Hudson starts detecting changes in the source control. If you want to see Hudson detecting changes, you will need to create a Hudson build for your own project. Once you commit a change to source control for that project, Hudson will start showing you the changes.
Hudson also provides integration with web interfaces for Subversion and CVS repositories including Trac, ViewSVN, FishEye, WebSVN, and others. Once you have configured the repository browser in the project settings, you will see a link similar to the Google Code link mentioned above.
If you look through the output, you will see that the build has created the HelloWorld.exe in the directory:
While it is nice that Hudson built the artifact, it is not especially accessible there. Instead, you should publish the .exe built by Hudson as a build artifact. That way, users can easily download the output of the build and you can more easily move the artifacts through the rest of your deployment process. To publish the .exe as a build artifact, go back into the project configuration for the Hello_World project. Toward the bottom, select the “Archive the Artifacts” check box under the “Post-build Actions” heading. Under, “Files to Archive,” enter:
Save the configuration. Press “Build Now” and Hudson will rebuild the project and provide a link to the HelloWorld.exe. You can click on the link and download the .exe now. Note that each build keeps a reference to its published artifacts, and the project page will have links to the artifacts for the last successful build.
Running Unit Tests
At this point, you should have a successful (blue) build for the Hello World project. However, Hudson is not running unit tests. To get more confidence in your build, you should run the unit tests with each build. The Hello World project comes with a unit test project including a single NUnit test. The NUnit plug-in for Hudson will reformat the NUnit output, but it will not execute the NUnit tests. To execute the test, you need to set up a batch process that uses the NUnit console runner.
Go back to the project configuration for the Hello_World project, scroll down to the build steps, and add a build step of type, “Execute Windows batch command.” Assuming you have installed NUnit 2.4.8 in the default location, your batch command should look like:
"C:Program FilesNUnit 2.4.8in unit-console.exe" HelloWorldTestsinDebugHelloWorldTests.dll /xml=nunit-output.xmlexit %%ERRORLEVEL%%
The first line of the script executes the nunit-console.exe and runs all tests found in HelloWorldTests.dll, placing the results in nunit-output.xml. The second line of the script tells the batch script to bubble out the error level of the NUnit run. This bubbled out error level will cause the build to fail if any tests fail.
|Figure 5. Example Project: The example project showing the test trend, published artifact, and build history.|
To publish the test results, select “Publish NUnit test result report,” and enter the name of the file that you told NUnit to generate, nunit-output.xml.
Save the configuration and then force another build of the project. After the build completes, navigate to the project page at:
You should now see a link to the “Latest Test Result.” You can see the final screenshot of the project page in Figure 5. Note that the link given on the project page will always point to the latest published test results. If you want to send out a link to the test results from a specific build, simply navigate to the page for that build and the “Test Result” link from the build?s page will specifically reference the results from that build number.
Installing Hudson as a Windows Service
Now that you have a build setup, you will probably want to install Hudson so that it runs as a Windows service. Assuming your trial Hudson is still running, click on “Manage Hudson” on the Hudson home page, and then “Install as Windows Service.” Hudson will verify that you want to keep the same working directory and then install itself as a Windows service. After the installation, Hudson will prompt you to restart.
If you were running or want to run Hudson on a port other than 8080, you will have to make one small change to the hudson.xml file. Open the HUDSON_HOMEhudson.xml file with WordPad or some other editor that understands Unix-style line endings. Find the <arguments> block toward the bottom of the file and change the value assigned to the httpPort argument. After saving the configuration file, restart the Windows service and Hudson should start up on the port that you have assigned to it.
You should now have a passing build that is monitoring source control for changes, running unit tests, and publishing the results. (For more information on monitoring Hudson, see the sidebar Monitoring Hudson with CCTray.) You will find many additional useful plug-ins for Hudson as you go along. The “More Plug-ins” sidebar lists some of the more popular and relevant plug-ins for .NET projects.
Be sure to check out the Hudson home page as well as the Hudson wiki and Hudson mailing lists. I love using Hudson, and if you give it a shot, you may too.
Further Reading and Resources
The Hudson home page is a great place to get started. There, you will find links to everything from getting started to writing your own plug-ins. The Hudson wiki also has recent news links for Hudson. You can find links to the Hudson mailing lists from either the Hudson home page or the wiki. I have found the users? mailing list to be both active and helpful. Finally, the project owner for Hudson is Kohsuke Kawaguchi, who frequently writes about Hudson. You may find these links useful.