====== Hudson on Debian Lenny ======

===== Install Hudson & Java =====

Hudson is written in Java so we will need to install Java, and to make things simpler we will install Hudson from its reporitory.

Edit ''/etc/apt/sources.list'' and append every line that ends with "lenny main" with " contrib non-free" and at the end of the file add this line

  deb http://hudson-ci.org/debian binary/

This is needed because Java is not in Debians main repository. Your sources.list should look something like this

  # deb http://ftp.hr.debian.org/debian/ lenny main
  
  deb http://ftp.hr.debian.org/debian/ lenny main contrib non-free
  deb-src http://ftp.hr.debian.org/debian/ lenny main contrib non-free   
  
  deb http://security.debian.org/ lenny/updates main contrib non-free
  deb-src http://security.debian.org/ lenny/updates main contrib non-free
  
  deb http://volatile.debian.org/debian-volatile lenny/volatile main contrib non-free
  deb-src http://volatile.debian.org/debian-volatile lenny/volatile main contrib non-free
  
  deb http://hudson-ci.org/debian binary/

Update apt information

  apt-get update

To install Java, Hudson and Ant (you do not need Ant if you plan to use Phing for building your project)

  apt-get install sun-java6-jdk hudson ant

To start Hudson after installation enter

  /etc/init.d/hudson start

Hudson should now be available through your browser at http://you-ip-address:8080 

===== PHP Hudson Plugins =====

Once on Hudsons front page select **Manage Hudson** and then **Manage Plugins** and install this plugins:

  * Clover plugin
  * Checkstyle Plug-in
  * PMD Plug-in
  * xUnit Plugin
  * Phing plugin (if you are using Phing)

Return to the Manage Hudson page and select **Configure System**. If you are using Ant, select **Add Ant**, uncheck "Install automatically" and under name enter "Ant 1.7.0" and for ANT_HOME enter ''/usr/share/ant'' . 

You can also enter settings for E-mail notifications.

===== PHP code metrics =====

Running automatic unit tests is probably the main reason for having a continuous integration server so lets install PHPUnit.

First make sure you have pear installed

  apt-get install php-pear

To get the latest version of PHPUnit we will have to update our pear installer as well.

  pear upgrade pear
  pear channel-update pear.php.net
  pear channel-discover pear.phpunit.de
  pear channel-discover components.ez.no
  pear channel-discover pear.symfony-project.com
  pear install phpunit/PHPUnit

PHPUnit requires Xdebug PHP extension, to install it

  apt-get install php5-xdebug

Why we are at it, let's install some other useful tools for code metrics in you PHP projects.

**PHP CodeSniffer**:

  pear install PHP_CodeSniffer

**phploc** (you must have pear channel pear.phpunit.de that we added while installing PHPUnit):

  pear install phpunit/phploc

**PHP Depend**:

  pear channel-discover pear.pdepend.org 
  pear install pdepend/PHP_Depend-beta 

===== phpDocumentor =====

To install phpDocumentor enter

  pear upgrade PhpDocumentor


===== Create a build file for your project =====

This is an example build.xml file that you should place in the root folder of your project and commit to your SCM before creating a new project in Hudson.

You will of course have to modify this file to match your environment.

<code>
<?xml version="1.0" encoding="UTF-8"?>
<project name="NAME_OF_YOUR_PROJECT" default="build" basedir=".">
  <property name="basedir" value="${WORKSPACE}"/>
  
  <target name="init">
    <!-- Create the different build directories -->
    <mkdir dir="${basedir}/build/logs" />
    <mkdir dir="${basedir}/build/api" />
    <mkdir dir="${basedir}/build/coverage" />
  </target>

  <target name="clean">
    <!-- Delete build directories from the previous run -->
    <delete>
      <fileset dir="${basedir}/build/logs" includes="**.*" />
    </delete>
    <delete>
      <fileset dir="${basedir}/build/api" includes="**.*" />
    </delete>                                                 
    <delete>
      <fileset dir="${basedir}/build/coverage" includes="**.*" />
    </delete>
  </target>

  <!-- Default target -->
  <target name="build" depends="init,phpunit,php-documentor" />

  <target name="php-documentor">
    <exec executable="phpdoc" dir="${basedir}/gameplay">
      <arg line="-ct type -t ${basedir}/build/api -ti 'Name of your project' -ue on -s -d ./ "/>
    </exec>
  </target>
  
  <target name="phpunit">
    <exec executable="phpunit" dir="${basedir}/source/tests" failonerror="off">
      <arg line="--log-xml ${basedir}/build/logs/phpunit.xml
                 --log-pmd ${basedir}/build/logs/phpunit.pmd.xml
                 --log-metrics ${basedir}/build/logs/metrics.xml
                 --coverage-xml  ${basedir}/build/logs/coverage.xml
                 --coverage-html ${basedir}/build/coverage
                 --coverage-clover ${basedir}/build/coverage/clover.xml
                 --configuration phpunit.xml
                " />
    </exec>
  </target>
</project>
</code>

After the first successful build you can replace 

  <target name="build" depends="init,phpunit,php-documentor" />

with

<target name="build" depends="clean,init,phpunit,php-documentor" />

===== Create your project in Hudson =====

Return to the Hudsons front page and select "create a new jobs".

  - Enter job name
  - select "Build a free-style software project"
  - under "Source Code Management" select your SCM (I use Subversion) and enter required details (after entering your Repository URL Hudson will provide you with an option to enter username and password if they are needed for access to your repository
  - for "Local module directory (optional)" enter "source"
  - for "Build Triggers" select Poll SCM and enter "* * * * *" this will make Hudson poll your repository every minute and trigger the build if if there are updates in your SCM
  - click on "Add build step" and select either Ant of Phing depending on what you are using to run your builds. I have selected "Invoke Ant", and selected the Ant version we configured earlier on for the "Targets" I have entered "build" since this is the name of the build target I am using to build my project

If you are using Ant and the variation of the build file provided on this page click "Advanced" under Ant configuration and for Properties enter:

  basedir=/var/lib/hudson/jobs/NAME_OF_YOUR_PROJECT/workspace

''/var/lib/hudson/jobs/NAME_OF_YOUR_PROJECT/'' is the place where Hudson will keep all informations about your project so it is important to pass this property to Ant so Ant can resolve path names that we are using in the Ants build file.

Other steps are optional and depend on you needs. I am using phpDocumentor to generate API docs for my project so I have selected Publish Javadoc and have entered "build/api/" as my Javadoc directory.

If you want to generate Clover Coverage Report using PHPUnit select Clover Coverage Report and enter ''build/coverage'' for Clover report directory and ''clover.xml'' for Clover report file name.

If you are using PHPUnit you probably want to check this options as well:

Check "Publish testing tools result report" select phpUnit from the dropdown menu and enter ''build/logs/*.xml'' for PHPUnit Pattern.

Check "Publish PMD analysis results" and enter for PMD results enter ''build/logs/phpunit.pmd.xml''

Save the setting and your first build should start.

===== Notes =====

PHPUnit requres a lot of memory, and default memory limit for PHP running on CLI is 32M. Edit ''/etc/php/cli/php.ini'' and set memory_limit to 512MB if you have enough RAM installed.

Looking at the console output will help you to determine what went wrong during the build process.

That's about it.

You can visit my blog at [[http://gogs.info/]].