Using Hudson

If you're practicing CI properly you should be integrating new code on a pretty regular basis. When new code is integrated the project should then run through its build process which should include running all the unit tests and building the project if all the unit tests pass. This is where Hudson comes in. Hudson can monitor your source repository and whenever new code is committed it will retrieve it and build the project. Now I'm going to show you how to set up the CIExample project in Hudson.

If you happen to follow the steps in the previous part of this series, or have your own Hudson server properly configured navigate to the Hudson install's home page. It should look like this:

Hudson dashboard

Click the "New Job" link in the top left. In the 'Job name' field enter 'CIExample' and select the "Build a free-style software project" option. The screen should look like this:

New job screen

Click the OK button. If you'd like you can fill out a description for the project. But for now we're going to be quick and dirty. Scroll down a bit to the Source Code Management section. Select the Subversion option and some form fields should appear. Configure the repository URL with the CIExample project SVN repository: http://ci-example.googlecode.com/svn/trunk/ It should look like this:

Hudson source code management configuration

Scroll all the way down so that you can see the Build Environment and Build sections. First check the "Run Xvnc during build" check box. This ensures the Flash Player will be able to be used when inspecting the unit tests. Lastly, in the Build section, click the "Add build step" button and select "Invoke Ant" from the list of options. We don't need to specify any targets since the default target of the project's build file builds the project. The screen should look like this:

Hudson VNC and ANT configuration

Lastly, click the "Save" button to save the project. This should take you to the project's dashboard and look like this:

Hudson project dashboard

Now, the only thing left to do is click the "Build Now" button in the left hand navigation. After a second or two of clicking the button a notification window should appear and should look like this:

Hudson notification panel

If everything has been installed and configured properly the build should be successful and you'll see a little blue dot notifying you that the build has completed. It should look like this:

Build completed!

Wa-la! Thats it! You've got Hudson working and building your project for you. Pretty awesome. Now you can configure the project with various options. For instance, you can configure Hudson to build the project whenever it detects new code has been committed to the repository so that you don't have to initiate the build by hand every time.

Wrap Up

So that concludes my "Practicing Continuous Integration on Flash Projects" series. In the first part I covered what Continuous Integration is and why it might be useful to your process. In the second part of the series I covered how to set up a project and its unit tests with the assumption that the build and tests will be automated. In the third part of the series I covered how to automate the build process using Apache Ant. In the fourth part of the series I covered how to setup a Continuous Integration server on a bare bones Fedora 8 Linux box using Amazon's EC2 service. And lastly, in this fifth and final part I covered how to setup the project in Hudson so that the build process can be automated and monitored

Series Index

1. What is CI?
2. Project Structure
3. Automation
4. Integration Server Setup
5. Using Hudson

Introduction

Code integration happens whenever you commit code into the project's mainline. There are essentially two camps when it comes to building the project after new code has been committed. Some developers prefer to do it manually, meaning that the developer switches to the "integration machine", checks out the new code and runs the build process. If the build is successful then the developer's commit is also successful. If its not successful, then the developer should revert their commit, make adjustments to their code, and attempt to integrate again later.

The other camp enjoys using a CI server such as Hudson or CruiseControl. A CI server will monitor the project's mainline and attempt to build the project any time new code is committed. A developer can check out the CI server website to see the progress or the eventual status of the build. When the build is complete, successful or not, the CI server should notify the developer who committed the new code. Personally I think a CI server is an invaluable tool when it comes to practicing CI and thus I'd like to show you how to get Hudson up and running.

Amazon EC2

Amazon EC2 is a great service that allows you to create computing resources on demand. In other words, it gives you an easy way of expanding your network infrastructure without actually having to buy hardware. In my mind, its the perfect service to run a CI server on because its easy to use and relatively cheap (you only pay for what you use). Otherwise, you'll need to find an machine in your network to install your flavor of CI server on. Personally, I'd rather not bog down an existing machine on my network with building projects. Amazon EC2 gives me nearly instant access to a virtual Linux box with root access and a decent amount of storage.

Creating an Instance on EC2

First allow me to make a disclaimer. Just because I'm advocating the use of EC2, doesn't mean you'll need an Amazon Web Services account to run a CI server. The steps needed to get Hudson up and running will depend on the flavor of Linux you're running, but if you know Linux then it shouldn't be too hard to know what to adjust for your setup. Additionally, Hudson runs just fine on Windows. If you need information about installing Hudson on other platforms visit their website.

So, before we can do anything, we'll need a machine to run Hudson on. With EC2 that means starting an instance. Before starting up an instance you should consider if you might ever want to reuse the resulting system configuration. If you think you might want to reuse it then ensure that you create an EBS backed instance. This will allow you to easily create an AMI from it and then be able to easily launch a new instance of the same configuration later on. Information about creating an EBS backed instance can be found in their documentation.

For the purpose of this example a small instance of a bare bones, 32-bit, Fedora 8 system is just fine. Here is what I did to get my instance running:

1. Log in to the AWS Management Console
2. Click the AMIs button in the navigation panel on the left hand side
3. Select EBS Images from the combo box labeled Viewing above the list of AMIs
4. Click the Owner column label to sort the AMIs by owner.
5. Select the AMI with the source name amazon/fedora-8-i386-v1.14-std. It should be the first one on the list.
6. Click the Launch button above the list.
7. Select the default settings on the Instance Details panel
8. Create a key pair or use an existing key pair.
9. Configure the firewall to allow connections on port 22, 80, 8080 and any other ports that you think might be necessary
10. Review the details and launch the instance.

Eventually you're instance will show up as running in the dashboard. Once its running ensure you can connect to the instance using your favorite SSH client. I personally use PuTTy. Bear in mind that EC2 instances don't use password authentication to connect. They use the public keys. PuTTy is a little weird when it comes to public keys and requires them to be converted to a specific format. Luckily Amazon has a quick little tutorial on how to properly configure PuTTy with the public keys.

Software

Once you're able to connect to your instance its time to start installing all the software you'll need to run Hudson and build your Flash project. The following is a list of all the software needed:

1. vnc (remote display system)
2. vnc-server (to allow connections)
3. X-Window (windowing agent)
4. GNOME (window manager/desktop)
5. Subversion (SVN)
6. Java Development Kit (JDK)
7. Apache Tomcat (or other Java servlet service)
8. Apache Ant
9. Flex SDK
10. Hudson
11. Xvnc plugin for Hudson

Installing vnc and vnc-server
Installing vnc and vnc-server is important because in order to analyze the compiled unit tests the resulting SWF needs to run in the Flash Player. Linux needs a windowing environment and a way of redirecting the windowing output to a virtual display. vnc is what does the redirecting. To install vnc and vnc-server simply type the following commands and agree to download the files:

# yum install vnc
#yum install vnc-server

Installing X-Window (X11)
As previously mentioned, you'll need a windowing environment to run the Flash Player, particularly for analyzing unit test results. To install X-Window type the following command:

# yum -y install xorg*

Installing GNOME
X-Window(X11) will need a window manager and, more importantly, we'll need a window manager that works with X11 and doesn't require any user input to create a screen. GNOME is a decent choice and will make connecting through a visual VNC client pretty nice as well. To install GNOME type the following command:

# yum groupinstall "GNOME Desktop Environment"

Installing Subversion
The CIExample project resides in a Subversion repository on Google Code, thus you'll need Subversion to be installed to retrieve it. To install Subversion simply type the following:

# yum install subversion

Installing the Java Development Kit
Installing the JDK is a little tricky mainly because Sun doesn't make finding the distributable files very easy. You'll want to download a binary package from somewhere into some location on the machine. I like to create a downloads folder at the root of the machine for this. At the time of writing this you can download the latest self extracting RPM by typing the following commands:

# wget http://www.java.net/download/jdk6/6u21/promoted/b05/binaries/jdk-6u21-ea-bin-b05-linux-i586-29_may_2010-rpm.bin
# chmod 755 jdk-6u21-ea-bin-b05-linux-i586-29_may_2010-rpm.bin
# ./jdk-6u21-ea-bin-b05-linux-i586-29_may_2010-rpm.bin

To confirm the JDK was installed, you can type the following command:

# java -version

You should see something like the following:

java version "1.6.0_21-ea"
Java(TM) SE Runtime Environment (build 1.6.0_21-ea-b05)
Java HotSpot(TM) Client VM (build 17.0-b15, mixed mode, sharing)

Install Apache Tomcat

Apache Tomcat is needed because Hudson is written in Java. Before we install tomcat, however, a new Linux user should be created to run tomcat under. Create a user named tomcat by typing the following command:

# useradd tomcat

Switch to the tomcat user by typing the following command:

# su tomcat

Create a folder for tomcat to be installed in within the /usr/local folder by typing the following commands:

# cd /usr/local
# mkdir tomcat

Download Apache Tomcat into the folder you created from any of the available mirrors and extract the files. At the time of this writing I typed the follwing:

# cd tomcat
# wget http://mirror.atlanticmetro.net/apache/tomcat/tomcat-7/v7.0.0-beta/bin/apache-tomcat-7.0.0.tar.gz
# tar -xvf apache-tomcat-7.0.0.tar.gz

Now all the files for tomcat are located in /usr/local/tomcat/apache-tomcat-7.0.0. Last thing to do now is switch back to the root user:

# exit

Install Apache Ant
Apache Ant is need to run the automated build process. Ant doesn't require anything special for installing, simply download the binary and extract it into a convenient location. I prefer to install it in the the /usr/ant/<version> folder. Also, don't forget to switch back to the root user. At the time of this writing I typed the following:

# cd /usr
# mkdir ant
# cd ant
# wget http://apache.opensourceresources.org/ant/binaries/apache-ant-1.8.1-bin.tar.gz
# tar -xvf apache-ant-1.8.1-bin.tar.gz

Now all the files for Ant should reside in the folder /usr/ant/apache-ant-1.8.1.

Install the Flex SDK
Now we need to install the Flex SDK. This will be just like installing Ant. I like to install any SDK's in a folder structure such as this: /sdk/<name-version>. Type the following to install the Flex SDK:

# cd /
# mkdir sdk
# cd sdk
# mkdir flex-4.1
# wget http://fpdownload.adobe.com/pub/flex/sdk/builds/flex4/flex_sdk_4.1.0.16076.zip
# unzip flex_sdk_4.1.0.16076.zip -d /sdk/flex-4.1

Set Environment Variables and Permissions
In order for a lot of this software to run properly you'll need to set some environment variables, add additional directories to the system PATH variable, change some file permissions. First, lets set the JAVA_HOME, ANT_HOME, CATALINA_HOME and FLEX_HOME environment variables and add Ant to the system PATH. To do this we'll need to edit the /etc/profile file. Type the following to open the file in the basic vi text editor:

# vi/etc/profile

Now we need to add some new lines to the file. Using the vi text editor is a little weird if you haven't used it before. I'll describe exactly what I did.

1. Navigate one line below the line that reads: "export PATH USER LOGNAME MAIL HOSTNAME HITSIZE INPUTRC" by using the arrow keys on your keyboard.
2. Press the letter i on your keyboard to enter insert mode.
3. Enter the following text into the file:
   export JAVA_HOME=/usr/java/jdk1.6.0_21
   export ANT_HOME=/usr/ant/apache-ant-1.8.1
   export CATALINA_HOME=/usr/local/tomcat/apache-tomcat-7.0.0
   export FLEX_HOME=/sdk/flex-4.1
   export PATH=$PATH:$ANT_HOME/bin
   
4. Press the escape key on your keyboard to exit insert mode
5. Type the following to save and quit the text editor::wq
6. Logout of your SSH session
7. Log back into your SSH session
8. Verify that each environment variable has been set by typing the following:
   
   # echo $JAVA_HOME
   # echo $ANT_HOME
   # echo $CATALINA_HOME
   # echo $FLEX_HOME
   
9. Verify that Ant can be called by the tomcat user from within the tomcat folder by typing the following:
   
   # su tomcat
   # cd /usr/local/tomcat
   # ant -version

Hopefully all went well for you there. Now we just need to change the permissions on the Flex SDK so that any user Linux user, specifically the tomcat user, can use the SDK. Type the following:

# exit (switch back to root user)
# cd /sdk
# chmod -R 755 flex-4.1

Verify the tomcat user can execute the mxmlc compiler by typing the following:

# cd /usr/local/tomcat
# su tomcat
# /sdk/flex-4.1/bin/mxmlc

If you don't get a permission error you're good to go!

Installing Hudson
Hudson can be installed in many ways, but in my opinion, the easiest way to install it is to deploy through the Tomcat manager. First you'll need to download Hudson to your local machine. The most recent WAR file can always be downloaded from this link. Save it somewhere easy to remember.

Now before you can access the Tomcat manager you're going to need to add a user with permission to view the web manager. To do this we need to modify the Tomcat user file. Type the following:

# su tomcat
# vi /usr/local/tomcat/apache-tomcat-7.0.0/conf/tomcat-users.xml

Now modify the file using the following steps:

1. Navigate between the <tomcat-users></tomcat-users> XML node by using the arrow keys on your keyboard.
2. Press the i key on your keyboard to enter insert mode.
3. Enter the following text:<user username="admin" password="tomcatadmin" roles="manager-gui"/>
4. Modify the username and password to your liking.
5. Press the escape key on your keyboard to exit insert mode.
6. Type the following to save and quit the text editor
   :wq<enter>

Now its time to startup Tomcat. To start Tomcat type the following:

# $CATALINA_HOME/bin/startup.sh

You should see some output in the console. Now, open your favorite web browser and navigate to the URL of your EC2 instance on port 8080. For instance, my url looked like this:

http://<some-ec2-id>.compute-1.amazonaws.com:8080

Navigate to the manager console by clicking on the Tomcat Manager button in the left navigation under the Administration tab. Login with the user credentials you created in the tomcat-users.xml file. You should see a list of the web apps that have been packaged with Tomcat. Now its time to deploy Hudson on Tomcat. Perform the following:

1. Scroll down to the Deploy section of the manager console.
2. Click the Choose File button in the War file to deploy section of the console.
3. Click the deploy button below the Choose File button.
4. Wait for the file to upload
5. Find Hudson in the list of applications and verify that it is running

Now there's a little tricky thing you have to do in order to get the index page of Hudson to appear. From what I understand its discrepency in the Java servlet specification. Alas, all you need to do is modify Hudson's web.xml file.

1. Open Hudson's web.xml file in a text editor by typing the following:
   # vi /usr/local/tomcat/apache-tomcat-7.0.0/webapps/hudson/WEB-INF/web.xml
   
2. Find the <servlet-mapping> node that looks like the following:
   <servlet-mapping>
   <servlet-name>Stapler</servlet-name>
   <url-pattern>/</url-pattern>
   </servlet-mapping>
   
3. Press the letter i on your keyboard to enter insert mode.
4. Modify the entry to look like the following:
   <servlet-mapping>
   <servlet-name>Stapler</servlet-name>
   <url-pattern>/*</url-pattern>
   </servlet-mapping>
   
5. Press the escape key on your keyboard to exit insert mode.
6. Type the following command to save and quit
   :wq<enter>

Now you can view Hudson in your browser with no trouble. Go to the following URL:

http://<some-ec2-id>.compute-1.amazonaws.com:8080/hudson/

You should now be able see the Hudson dashboard!

Install Hudson Plugins
There are loads of plugins for Hudson, including this totally sweet Chuck Norris Plugin, that you may or may not want to install. At the very least you'll need at least one Hudson plugin to be able to run vnc so that the Flash Player can redirect its output. Download the Xvnc plugin to your local machine.  Navigate to the Advanced panel of the Hudson plugin manager by going to the following URL:

http://<some-ec2-id>.compute-1.amazonaws.com:8080/hudson/pluginManager/advanced

Upload the plugin using the Upload Plugin section of the plugin manager. Once both plugins are uploaded you'll need to restart Hudson. Navigate to the Tomcat manager again

http://<some-ec2-id>.compute-1.amazonaws.com:8080/manager/html

Find Hudson in the list of web apps again and click Reload button to the right under the Commands column. Once this has completed, verify that the plugins have been installed by navigating to:

http://<some-ec2-id>.compute-1.amazonaws.com:8080/hudson/pluginManager/installed

You should now see the Git and Xvnc plugins listed.

Configure the Flash Player Debugger
I know this seems like a lot, but we're almost there. Time to configure the Flash Player debugger. First we'll need to extract the debugger from the Flex SDK. Make sure you switch back to the root user if you haven't already. Type the following commands:

# cd /sdk/flex-4.1/runtimes/player/10.1/lnx
# tar -xvf flashplayerdebugger.tar.gz

Now that the debugger has been extracted you you'll need to create a a symbolic link to it named gflashplayer.  To create the link type the following commands:

# cd /usr/sbin
# ln -s /sdk/flex-4.1/runtimes/player/10.1/lnx/flashplayerdebugger gflashplayer

Now, in order for the Flash Player debugger to "trust" our unit test SWF(s), we have to create the "would-be" folder that the normal Flash Player security settings would be stored in. Create the following folder tree:

/home/tomcat/.macromedia/Flash_Player/#Security/FlashPlayerTrust

Configure VNC
Now, the last thing to do is to configure the VNC server for the tomcat user and ensure that its using GNOME as its window manager. Lets first configure the vnc server for the tomcat user. Make sure you're the root user and open the vnc server config file by typing the following:

# vi /etc/sysconfig/vncservers

Now you'll need to add a server for the tomcat user. Do this by performing the following steps:

1. Move the cursor below all the comments.
2. Press the letter i on your keyboard to enter insert mode.
3. Enter the following text:VNCSERVERS="1:tomcat"
   VNCSERVERARGS[1]="-geometry 1024x769 -depth 16"
   
4. Press escape to exit insert mode.
5. Type the following to save and quit the text editor
   :wq<enter>

Now that this is done, you'll need to set the tomcat user's vnc password. Type the following:

# su tomcat
# vncpasswd

Set the password to whatever you like. Just remember this if you ever want to connect through a VNC viewer! The next thing to do is configure the tomcat user to use GNOME instead of the default window manager. To do this open the tomcat user's vnc configuration file by typing the following:

# vi /home/tomcat/.vnc/xstartup

By now you should know how to edit a text file, so make it look like the following:

#!/bin/sh
# Uncomment the following two lines for normal desktop:
unset SESSION_MANAGER
exec /etc/X11/xinit/xinitrc
[ -x /etc/vnc/xstartup ] && exec /etc/vnc/xstartup
[ -r $HOME/.Xresources ] && xrdb $HOME/.Xresources
#xsetroot -solid grey
#vncconfig -iconic &
#xterm -geometry 80x24+10+10 -ls -title "$VNCDESKTOP Desktop" &
#twm
&startx &

Save and quit the text editor. Lastly, start the vnc server by typing the following command:

# service vncserver start

Now guess what? You're done installing and configuring everything! Woohoo!

Wrap Up

After all that work you should now have your CI server up and running. The only thing left to do is add the project to Hudson so that it can start building it. I'll explain how to do this in the following section. For now, go grab yourself a well deserved beverage or snack.

Series Index

1. What is CI?
2. Project Structure
3. Automation
4. Integration Server Setup
5. Using Hudson

Introduction

One of the  most import parts of CI is the need to automate the build process. Building a Flash project means, at the very least, compiling your code into a SWF file. There are various ways to compile a SWF, but in order to be able to automate the process its best to use the mxmlc compiler thats part of the Flex SDK. If you are using the Flash IDE to compile your projects I would say that CI is not for you and/or your organization. However, thats not to say you should stop reading or stop using the IDE. I still use the IDE on nearly all my projects, just differently than I used to. Anything that requires timeline animation or is just easier to draw using the IDE I publish into a SWF. I then import the symbols from that SWF into my project when I compile with mxmlc. Explaining how to do this and just exactly how to use the mxmlc compiler is outside the scope of this blog series but you can learn more about using it on the Flex 4 product support page.

Apache Ant

Performing the automation can be achieved in various ways. For instance, depending on your operating system you could write a batch file or shell script that contains everything you'd need to run to compile the SWF. While this method works, it also requires you to consider each operating system that the project might be built on. Knowledge of each OS would be necessary to write equivalent routines for compiling, deployment, and such. In order to get around this developers created automation software such as Ant and Maven. Ant is my tool of choice and is what I will use to illustrate how to automate the build process of a Flash project. Ant is great because its quite easy to use, has a lot of native functionality, and can be extended with third party tools. Ant reads a simple XML file that identifies commands you wish to run. For instance, if you need to copy a file, you would use the <copy> task and Ant would copy whatever files you wished to wherever you specified. This eliminates the need to know the native command for copying files.

Compiling With Ant

Using Ant is quite simple. Real quick, if you haven't used Ant before, you simply navigate to the folder containing your build.xml file from a command prompt and run the ant command. Ant will run the default target specified in the default attribute of the <project> node of your build file. If you want to run a different target, you simply follow the ant call with the name of the target you wish to run. More information about using Ant can be found on the Apache Ant website. Compiling a SWF with mxmlc can be achieved in three different ways using Ant. The first, and probably the most obvious, is by using Ant's <exec> task. The <exec> task allows you to run an executable and specify arguments and parameters. It would look something like this:

The second method would be to use the Flex Ant tasks provided with the Flex SDK. To use them you'll have to copy them into your Ant installation or package them with your project. I recommend you always package it with your project. This will eliminate an extra step for any new developer that comes on to the project. The tasks file is located in the FLEX_HOME/ant/lib folder.By including the Flex Ant tasks you'll be given about to use a new task named <mxmlc>. Using the Flex Ant tasks would look something like this:

The third method, my preferred method, would be to use the <java> task to invoke the mxmlc.jar file. This method would look something like the following:

There are pros and cons to each method, but most importantly, using the <mxmlc> or the <java> Ant tasks will make it easier to compile your SWFs across platforms so long as the JDK is installed.

The Project Build File

Lets take a look at the various targets in the CIExample project's build file. Open this link in a new tab or window. Before any of the targets you will see the the following code:

In the previous code, four things are happening. The first is that a properties file is specified. View the properties file here. The properties file defines various properties that are going to be useful throughout the build file. All properties in an Ant build file are referenced by wrapping the property name like so: ${propertyname}. After the properties file is loaded, any environment variables are inserted as Ant propreties and prefixed with "env".  After this, two additional Ant task definitions are loaded: ant-contrib.jar and flexUnitTasks.jar. Ant-Contrib is an additional set of tasks that are extremely useful when writing your buidl files. More information about Ant-Contrib can be read here. The FlexUnit tasks will allow us to automate the analyzation of the unit test results. Now lets take a look at the first target in the build file:

The init target may look a bit strange, but it performs a crucial routine that I prefer to run over setting a property in the build.properties file. I've found it common practice throughout the industry to set the FLEX_HOME property in the build.properties file. I'm not a fan of this because I like to keep the build.properties file under version control. With multiple developers on a project, managing this file would get tricky as most developers have a unique development environment. Personally, I prefer to allow the configuration of the FLEX_HOME either through an environment variable or by passing the property value as a parameter when running the build. So set an environment variable named FLEX_HOME or pass the property value in the command line. It would look something like this: ant -DFLEX_HOME='/sdk/flex/4.1' desired-target-name Now lets take a look at the next two targets:

These two targets, clean-bin and clean-test are relatively simple. They both delete folders that contain generated files. Specifically, the bin folder is where the project's SWF is compiled to, whereas the bin-test folder is where the unit tests SWF and resulting report is compiled to. Now lets take a look at the next two targets:

The compile-swf target, well, it compiles the project into a SWF. This is the target that will be run if all the unit tests pass. The compile-test target simply compiles the unit tests into a SWF. Both of these targets depend on the init target and their respective clean targets. Following these targets is the run-flexunit target:

In the run-flexunit target the FlexUnit task is used to analyze the unit test SWF. It requires that you have the stand-alone debugger version of the Flash Player so that it can open it and listen to the SWF's trace output. This is what allows the task to determine if the unit tests passed or failed. After it analyzes the SWF it output's an XML file into the directory specified in the toDir attribute. Additionally, it sets a property of your liking equal to a value of true that specifies if the tests failed or not. In this case its a property named flexunit.failed. This property will be useful later on. The following target makes use of the flexunit.failed property generated by the FlexUnit ant task:

The run-test target is quite simple. It depends on the run-flexunit target which in turn depends on the compile-test target. After the tests are compiled and analyzed, a simple condition is checked on the flexunit.failed property. If its true, the Ant <fail> task is called to stop the build process. If its not true, simply echo out a message that says that all the unit tests passed. Following the run-test target is the run-debug target:

The run-debug target will probably be the most used target by developers on their local machine. It depends on the compile-swf target and then launches the compile output in a browser to check out the results. This target simply opens the SWF itself, but if you wanted to you could create another target that generates an HTML container and launches the HTML file instead of the SWF. You'll also notice this target checks the local OS to ensure the proper method of opening the browser. And finally, the last three targets:

The build target depends on the run-test and compile-swf targets. This will run the tests and, so long as they pass, then compile the project SWF. If the tests fail, the build will fail and the project SWF will not be compiled. The deploy-testing and deploy-production targets don't do anything as they would be very specific to your own needs, but they do depend on the build target to ensure the project is built properly before deploying anywhere.

Wrap Up

Using Ant is a great way to automate your build process as it can be used on a variety of platforms. Hopefully you now have a sense of how to use Ant to automate the build process. Feel free to use the CIExample project as a template for your own projects that you wish to automate.

In the next part of this series, I'll explain how to set up a CI server using Amazon's EC2 service.

Series Index

1. What is CI?
2. Project Structure
3. Automation
4. Integration Server Setup
5. Using Hudson

Introduction

Practicing CI relies heavily on a consistent process. Having a well defined project structure will definitely be an important piece to the puzzle as well. Flash projects are unique in how they are structured and any seasoned developer has their preferred way of doing things. Regardless of if you are a seasoned developer or new to all of this, this part of my series is meant to serve as a simple guideline to developers who are new to the practice of CI. I truly believe that having a simple and consistent project structure is extremely important to being able to make a project portable and easily built on various platforms. That being said, I've created a very simple project called CIExample. Its under version control at google code. This is the project that I will be referencing throughout the rest of this series.

Folder Structure

Open the CIExample project website . First, lets take a look at the folder structure. There are five folders in the project.

lib
The lib folder is where any of the SWC files that the project needs should be placed. Many third party code libraries are distributed as SWC files now and I highly recommend using them. The CIExample project currently doesn't include any SWC files, but its always nice to have a place to put them should you need to use one.

lib-test
The lib-test folder is where any of the SWC files that the unit tests need should be placed. The CIExample project uses FlexUnit for unit testing. All the necessary FlexUnit SWC files are placed here. Its nice to have a place to keep files that are specific to test compiling  away from your project files. Unit testing is a whole other topic, and unfortunately is not within the scope of this series. I highly recommend FlexUnit. Their website has plenty of information to get you started writing unit tests for your project.

resources
The resources folder is where you can place any additional files that are needed for the build process. The CIExample project uses this folder to hold two .jar files. Thes files contain additional Ant tasks that are needed for the build process. You'll learn more about these files in the Automation part of this series. In many of my projects this folder contains files and templates for generating code and HTML containers.

src
The src folder contains all the source code for the project. The CIExample project contains but one class file which will be the project's compile target.

src-test
The src-test folder contains all the source code for the project's unit tests. The CIExample project includes a basic test runner and one test suite. The test suite includes one dummy test case.

Build Files

At the root of the project you'll notice a few files.

README
The README file is a very underrated project file. This file should include basic instructions on how to build the project. Any new developers should be able to look at this file, follow its instructions, and get the project running on their local development environment so that they may begin to contribute.

build.xml
The build.xml file is the core automation file used by Apache Ant. This file will be explained in full in the Automation part of this series.

build.properties
The build.properties file contains property names and values that are used in the build.xml file. Apache Ant reads this file before any automation is performed.

Wrap Up

This part of the series is rather short but its meant to briefly outline a basic project structure that will make practicing CI relatively easy. Basically, there are three main areas for files: Project files (src and lib), test files (src-test and lib-test) and build files (resources). Keeping this structure will allow you to easily locate files that relate either to the project, tests or the build. Every project should also include automation file(s). The CIExample project uses Apache Ant, thus the build.xml and build.properties files are located at the root of the project. And finally, always remember to include a README file that includes instructions on how to build the project. In the next part of this series I'll explain how to automate the build process.

Series Index

1. What is CI?
2. Project Structure
3. Automation
4. Integration Server Setup
5. Using Hudson

Introduction

So just what the heck is CI? What I've come to understand is that CI is a software development practice that is most commonly associated with agile software development. In practice it involves the "continuous integration" of code  and tests from the various developers of a project at a desired frequency. Integration of new code always occurs in the project's main line (trunk or master branch) of development. Once the new code is committed an automated process is invoked to run various tests and build the project (if the tests don't fail). Additionally, the automation process can, and should, include a method of deploying the project to various contexts such as a testing or production server.

My understanding of what CI is didn't come to me so easily. When I first heard the term it was in the form of "Continuous Integration Server" and its my guess that one of the most common misunderstandings that developers have with regards to CI is that it is centered around a piece of software. A CI server is just a tool that helps you practice CI. There are a lot of different CI servers out there that will help you manage the process of automating your build process. Out of all my research the two most common ones seem to be CruiseControl and Hudson. In part three of this series I'll explain  how to use Hudson on a remote Linux box to manage your build process.

Best Practices

With any methodology, there are good and bad ways to go about practicing them. When practicing CI you should try to adhere to the following:

Use a version control system such as Subversion, Git, or CVS.
Using a version control system such as Subversion, Git, or CVS will allow the developers on the project to easily commit their work to a single place of storage. Additionally, version control systems provide mechanisms for resolving conflicts between files edited by more than one person at a time. This type of functionality can make integration of new or changed code much easier. In part three of this series I'll explain how to configure Hudson to pull files from a Git repository.

Automate the build process
Building a project usually consists of running various sets of commands, moving files, generating files, etc. Lucky for us, there are plenty of tools out there to help automate these steps. Tools like Ant and Maven gives developers the ability to create simple commands to perform all the steps needed to build the project. Minimizing human error during the build process is essential and a good practice for any development methodology you practice.

Make the build self testing
There's more than one way to skin(test) a cat (your code). Regardless of how you test your code, it should be part of your automated build process. Test Driven Development is a popular technique to test code before a project can successfully be built. In part two you'll see how a tool like FlexUnit fits into the CI process.

Everyone commits to the mainline at a desired frequency
The desired frequency is up to you. Its generally considered that the more often you commit the better. Checking your code in often allows developers to recognize bugs earlier and thus resolve them earlier. Imagine if you didn't commit you're code for a whole week. Unless the other developers on the project are exact clones of you, there's probably going to be more conflicts than if you were to commit every day. However, thats not to say you have to do this. Another approach in agile development is to perform a "sprint". During a sprint developers write code for a desired about of time, this can last anywhere from a few days to a few weeks. At some point the developers stop working on their code and begin to merge their work together into the mainline. This can last anywhere from a day or more. Regardless of your approach, both rely heavily on good communication between the development team to ensure everyone is on the right path.

Run the build each time you commit new code
Whenever you commit new code you should build the project to verify the new code has integrated properly. Developers themselves should also be building the project on their local machine to ensure their code works with whatever is in the project's mainline. This is where tools like Hudson and CruiseControl come in. These server's can begin the automated build process whenever code is committed into the mainline.

Keep the build fast
A project's build process should be optimized to run as fast as possible. This will enable developers to quickly identify problems with integration. If its not fast then you're not going to benefit from this methodology. Most Flash projects don't take too long to build, but the more complicated your project gets the longer it may take to build. If you feel as if you're project is taking too long to build consider breaking it up into various smaller projects with a master project that pulls everything together.

Test in a clone of the production environment whenever possible
Naturally you'll want to ensure your project is ready to be deployed to production. This can only really be done if you have an environment that's identical to your production environment. While not always possible this will hopefully reduce any failures when deploying to production.

Make it easy to get the latest build files
There should always be an easy way for anyone involved in the project to retrieve the latest build files. In the case of a Flash project this could be a multitude of things, but at the very least this means a SWF file. For instance, as part of the build process, perhaps there's a protected website somewhere in which someone can download an ZIP archive of the SWF file, its HTML container and image assets.

Everyone can see whats happening
This is where tools like CruiseControl and Hudson come in again. They each have fancy schmancyweb consoles that show if there's a build in progress and what the result of the last build was. Otherwise, if you're manually invoking the build process, you should  have some way of indicating to the team the status of the build. I recommend getting your hands on a traffic light and hooking it up to your automation machine.

Automate Deployment
When a build successfully completes you'll most likely want to deploy it somewhere at some point. This process should also be automated. CI servers usually give you the ability to run a script or another process after the build completes to make deploying, say to your production server, less prone to human error.

If you'd like, you can read other descriptions of these practices elsewhere such as Wikipedia or this paper written by Martin Fowler.

Advantages & Disadvantages

So you might be thinking to yourself, "This all sounds a bit crazy to me!" Or maybe you're thinking "This all sounds awesome, but what doesn't it provide?" Well then here is a list of various advantages and disadvantages.

Advantages

1. Reduced risk
2. Provides a way of knowing what works and what doesn't at all times
3. Early warnings of incompatible code
4. Early warnings of conflicting changes
5. Easier to find bugs and eliminate them
6. Immediate testing of code
7. Constant availability of a build
8. Projects tend to have  less bug
9. Motivates developers to produce code that works

Disadvantages

1. Initial setup time can be long
2. Good results rely heavily on well written test suites
3. Difficult to introduce large scale refactoring
4. Infrastructure requirements can induce cost

Wrap Up

So that just about covers what CI is. I won't go over everything but just remember that CI is a methodology, a mind set, an attitude. Its not a piece of software or server environment. Its all up to you to decide if its practice benefits you and/or your organization. In the next part of this series I'm going to describe how to structure a Flash project to make practicing CI relatively easy.

Series Index

1. What is CI?
2. Project Structure
3. Automation
4. Integration Server Setup
5. Using Hudson

It took me a while to figure things out entirely but in the end I'm happy to have learned how to use flash.desktop.NativeProcess. Unfortunately, in order to realize my idea faster, I ignored the fact that the application would really depend on a user's system. For instance, I have Ant installed in such a way that its available as a system command so I can run it from the command line like any old DOS command. I know not everyone is setup like this andwould require knowing where Ant is installed on a user's system. Additionally, Ant doesn't come with a good old fashioned .exe file for Windows so I invoked Ant via C:\windows\system32\cmd.exe. Here's some pseudo code that comes straight from my application...

Another (little) thing was that Adobe isn't very clear about the fact that you need to package your application in a native installer in order to use the 'extendedDesktop' profile.  Took me a while to figure it out, but the good news its pretty darn easy to package a native installer from a .air file.

At any rate, its by no means ready for the public, but I wanted to share my work thus far to see if anyone else would be interested in an application such as this. So here's how it looks and works so far:

When you start the application you're presented with a screen that allows you to load a build file...

Once the file is loaded it displays information about the build file and a list of its available targets...

You can then select a task and run it. Here you can see the output in the TextArea component from when I ran the compile-docs target...

Some of my targets require arguments to be passed in for them to work. For instance, my compile-and-debug target requires a debugLevels parameter that specifies the various debug levels (info, status, etc.) to output to the debugging console (which happens to be de MonsterDebugger). So I created a little panel that lets me specify parameters for the target...

Lastly, here you can see the output from the compile-and-debug target after running it with the passed in parameters...

So thats it! And if anyone thinks this would be useful to them leave some comments and/or ideas.

P.S. I built it with robotlegs