1. Setting up a CI Server for PHPUnit with Git using phpUnderControl Carly Ho, Gabrielle Knight, Nick Pizzolato

2. Platform This guide is written for Ubuntu 10.04, php 5, phpUnderControl 2.8, and phpUnit 0.5. This guide also assumes you have administrator privileges on your server for the purpose of installing all necessary files.

3. Setting up phpUnderControl First you need to make sure you have the necessary applications installed. PhpUnderControl is an addon to CruiseControl, a java plugin. So we will need java6. You will also need php5 with xdebug and php-pear to install PHPUnit. You will also need unzip, although you probably already have this installed. sudo apt-get install sun-java6-sdk sudo apt-get install php5-xdebug sudo apt-get install php-pear sudo apt-get install unzip Now you will use pear to install PHPUnit and phpUnderControl. To have phpUnderControl show graphs, you will need to install a graph library. sudo pear channel-discover components.ez.no sudo pear install -a ezc/Graph Now you will install phpUnderControl. Since it is in beta, you need to change the config to allow beta installs. sudo pear config-set preferred_state beta sudo pear channel-discover pear.phpunit.de sudo pear install --alldeps phpunit/phpUnderControl

4. Now we will download and install CruiseControl itself. First we download it, then we unzip it to /opt. Then we create a symbolic link to make upgrading CruiseControl easy in the future. cd /preferred/download/directory wget http://heanet.dl.sourceforge.net/sourceforge/cruisecontrol/cruisecontrol-bin-2.8.2.zip sudo unzip cruisecontrol-bin-2.8.2.zip -d /opt sudo ln -s /opt/cruisecontrol-bin-2.8.2 /opt/cruisecontrol Now we configure CruiseControl by running the install script. sudo phpuc install /opt/cruisecontrol Now we will install an example project and run the CI server. While not strictly necessary, it is highly recommended you follow the following steps in order to check that your installation was successful. sudo phpuc example /opt/cruisecontrol CruiseControl needs the JAVA_HOME variable set in order to run. Whether you want to set it every time or change your.bashrc to keep it set is up to you. Either way, the commands need to be run: JAVA_HOME="/usr/lib/jvm/java-6-sun"; export JAVA_HOME Now we can start CruiseControl. cd /opt/cruisecontrol sudo -E./cruisecontrol.sh

5. If everything was installed correctly, you should be able to type http://[ip-of-server]:8080/cruisecontrol and see something similar to the below image. If you are running this on a local machine, the address will be http://localhost:8080/cruisecontrol. Stopping CruiseControl elegantly is something we never quite figured out. You can stop CruiseControl with the command: kill `cat /opt/cruisecontrol/cc.pid` However the process still seems to be running on port 8080. So you need to find the pid of the process on 8080 with sudo netstat -anp |grep 8080 |grep -v grep That should give you a pid for a process listening on port 8080. Now kill it with the command kill -9 pid-found-from-above-command

6. Setting Up a New Project Now we will set up CruiseControl to work with a new project. The following assumes the project name is my_project. Simply substitute that for your project's name. It also assumes you have test cases for your project. To create a project, you have to create a project configuration, set up a directory structure, and add the project to the main configuration. cd /opt/cruisecontrol/projects mkdir my_project cd my_project If you do not have any test cases for your project, create the following files in my_project/. If you do, replace all references to these test cases with your own. Calculator.php: <?php Class Calculator { public static function Add($a, $b) { return $a + $b; } } CalculatorTest.php: assertEquals(3, Calculator::Add(1,2)); } } Now create build.xml in my_project/ with the following contents: The structure of a project for build.xml follows this structure. It has a target element with a name element that contains an exec element. The exec element may contain an arg element.......

7. The exec element has an executable attribute that points to the program to run and a dir attribute that determines the directory in which the program is executed. Within the exec element is an arg element that holds the command line argument. So the checkout tagged in the exec element below Is equivalent to cd my_project/source git pull Add this target to build.xml. This will run git checkout in projects/my_projects/source/. To get your files there you need to clone your git repository. git clone /path/to/repository/my_project.git/ /opt/cruisecontrol/projects/my_project/source Now we can test the build.xml file. Ant is the program that actually runs the builds.../../apache-ant-1.7.0/bin/ant checkout It everything is set up correctly you should see something like this: checkout: [exec] At revision 1. BUILD SUCCESSFUL Total time: 1 second

8. Now we're going to add the following targets to build.xml. PhpDocumentor is an automatic documentation tool. You can read about specific arguments by running phpdoc -h. It creates its documentation in the build/api directory, but you need to manually create that first. PHPUnit is the unit tester and creates its output in build/logs and build/coverage. These also have to be manually created. sudo mkdir -p build/api build/logs build/coverage <arg line="-ct type -ue on -t ${basedir}/build/api -tb /usr/share/php/data/phpUnderControl/data/phpdoc -o HTML:Phpuc:phpuc -d."/> <arg line="--log-xml ${basedir}/build/logs/phpunit.xml --log-pmd ${basedir}/build/logs/phpunit.pmd.xml --log-metrics ${basedir}/build/logs/phpunit.metrics.xml --coverage-xml ${basedir}/build/logs/phpunit.coverage.xml --coverage-html ${basedir}/build/coverage CalculatorTest.php" /> Now we combine the targets into one target And we make this the default target, so replace the project tag with this

9. Configuring CruiseControl The actual configuration for CruiseControl is located in /opt/cruisecontrol/config.xml. We're going to edit this to run the project how we want it to. Copy the default config.xml to config.xml.default. Create a new config.xml file with the following contents. All new fields will go between the tags. Next is the modification set, which tells CruiseControl when to rebuild the project. We're going to have it check every 60 seconds if there have been changes to the repository. To do that we need to tell CruiseControl to load the git plugin. Schedule tells CruiseControl what to actually do, which in this case is to build our project. The listener allows CruiseControl to communicate the status of the build to other applications

10. Log tells CruiseControl where to place the information gathered during the build process. A publisher allows CruiseControl to publish results of the build. The artifactpublishers place the information in a publicly accessible directory. The execute creates graphs of the builds. <artifactspublisher dir="projects/${project.name}/build/api" dest="artifacts/${project.name}" subdirectory="api"/> <artifactspublisher dir="projects/${project.name}/build/coverage" dest="artifacts/${project.name}" subdirectory="coverage"/> <execute command="phpuc graph logs/${project.name} artifacts/${project.name}"/> CruiseControl should now be fully configured. Execute these commands to run the system. Make sure JAVA_HOME exists. See several slides back on how to stop it. cd /opt/cruisecontrol./cruisecontrol.sh

11. Resources The backbone of this guide is a merger of the following guides: http://jpablobr.com/past/php-staging-environment-for-continuous-integration-part-2 http://techportal.ibuildings.com/2009/03/03/getting-started-with-phpundercontrol/ The following website was used to find out where to download CruiseControl from http://blog.felixdv.com/2009/02/07/setting-up-phpundercontrol/ The following website was used to find information on how to successfully shut down CruiseControl http://old.nabble.com/CruiseControl-2.7.2-released-td16458637.html