h1. continuous4r



h2. <br/>What is it ?

Continuous4R is a continuous integration tool for Ruby on Rails. With it, you can
aggregate reports of the best analysis, quality, tests and deployment tools for
Ruby and Rails.
By just defining one Rake task and writing an XML file describing your project,
Continuous4R builds for you an entire website in a Maven form.

h2. Installing

<pre syntax="ruby">sudo gem install continuous4r</pre>

h2. The basics

h3. Defining the Rake task

In order to build your project, you need to declare one Rake task. Under the lib/tasks
directory of your project, create a file named continuous4r.rake :

<pre syntax="ruby">require 'rubygems'
require 'continuous4r'

# Tache Rake pour la construction du site Continuous4R
namespace :continuous4r do
  desc 'Build Continuous4R Website for the current project'
  task :build do
    Continuous4r.generate_site
  end  
end</pre>

h3. Writing the XML file describing your project

This file must be named continuous4r-project.xml, and must be placed at the top
of your Rails project directory. This file must not have a XML header (&lt;?xml version...).
Here's the model of this file :

<pre syntax="xml"><project name="PROJECT_NAME">
    <description>PROJECT_DESCRIPTION</description>
    <url>PROJECT_URL</url>
    <logo>PROJECT_IMAGE_URI</logo>
    <!-- Describing your project members -->
    <members>
        <member id="MEMBER_LOGIN" name="MEMBER_NAME" email="MEMBER_EMAIL"
            roles="MEMBER_ROLES" company="MEMBER_COMPANY_NAME"/>
        ...
    </members>
    <bugtracker>
        <tracker_type>[Trac|Bugzilla|Mantis|etc...]</tracker_type>
        <tracker_url>BUGTRACKER_URL</tracker_url>
        <tracker_account_create>BUGTRACKER_URL_ACCOUNT_CREATION</tracker_account_create>
        <search>BUGTRACKER_URL_SEARCH_TICKETS</search>
        <url>BUGTRACKER_URL_TICKETS_LIST</url>
        <add>BUGTRACKER_URL_TICKET_ADD</add>
    </bugtracker>
    <scm>
        <repository_type>[svn|cvs]</repository_type>
        <url>SCM_URL</url>
        <view>SCM_VIEWER_URL</view>
        <!-- needed if authentication for access is mandatory -->
        <user>userlogin</user>
        <password>userpassword</password>
    </scm>
    <!-- Gems mandatory for your project -->
    <gems>
        <gem name="GEM_NAME" version="GEM_VERSION"/>
        ...
    </gems>
    <!-- Tasks in order to generate reports, described further -->
    <tasks [autoinstall="true"] <!-- activates autoinstall for gems needed by tasks --> >
        ...
    </tasks>
</project></pre>

h2. Defining tasks

h3. Changelog task

Builds a report of the last modifications on the SCM repository. Only Subversion is supported
at the time.

<pre syntax="xml"><task name="changelog"/>
</pre>

<a href="changelog.png" target="_blank">Sample</a>

h3. Stats task

Generates a report of the Rails statistics on your project.

<pre syntax="xml"><task name="stats">
    <description>Provides statistics on your Rails code</description>
</task></pre>

<a href="stats.png" target="_blank">Sample</a>

h3. Dcov task

Generates a report on the rdoc coverage of your Ruby code. The parts 
which are not covered are colored in red.<br/>
The <strong>pattern</strong> param enables you to select the Ruby code to control.<br/>
The <strong>report</strong> param is the path where Continuous4R can find the dcov 
original report (due to a bug in dcov).

<pre syntax="xml"><task name="dcov">
    <description>Rdoc coverage analysis report</description>
    <params>
        <pattern value="app/**/*.rb"/>
        <report path="coverage.html"/>
    </params>
</task></pre>

<a href="dcov.png" target="_blank">Sample</a>

h3. Rcov task

Builds a report on the coverage of your tests over your Ruby code.

<pre syntax="xml"><task name="rcov">
    <params>
        <!-- file which loads all the necessary test files (based on requires) -->
        <file path="test/rcov_test_all.rb"/>
        <!-- path where to find the reports generated by rcov -->
        <reports path="coverage"/>
    </params>
</task>
</pre>

<a href="rcov.png" target="_blank">Sample</a>

h3. Rdoc task

Generates a report of the rdoc generation, and gives access to the rdoc.

<pre syntax="xml"><task name="rdoc"/>
</pre>

<a href="rdoc.png" target="_blank">Sample</a>

h3. Flog task

<a href="http://ruby.sadi.st/Flog.html" target="_blank">Flog</a> is a tool which 
provides statistics of your Ruby code's complexity. This task generates an HTML
report of these statistics.

<pre syntax="xml"><task name="flog"/>
</pre>

<a href="flog.png" target="_blank">Sample</a>

h3. Kwala task

<a href="http://kwala.rubyforge.org" target="_blank">Kwala</a> is a continuous integration
tool which gathers informations of the quality and metrics on your project. This 
task integrates the reports produced by kwala to the site.

<pre syntax="xml"><task name="kwala">
    <params>
        <!-- set of actions understood by kwala -->
        <actions>
            <action>loc</action>
            <action>syntax_check</action>
            <action>formatting</action>
            <action>code_duplication</action>
            <action>cyclomatic</action>
            <action>unit_test</action>
            <action>comment_check</action>
            <action>requires</action>
            <action>cycles</action>
        </actions>
    </params>
</task>
</pre>

<a href="kwala.png" target="_blank">Sample</a>

h3. Railroad task

Railroad is a tool to generate graphs of your models and/or your controllers. This 
task generates your graphs and presents them on a HTML report. This task is not 
compatible with CruiseControl.rb.

<pre syntax="xml"><task name="railroad">
    <params>
        <generate value="controllers|models|all"/>
    </params>
</task>
</pre>

h3. Httperf task

<a href="http://www.hpl.hp.com/research/linux/httperf/" target="_blank">Httperf</a> 
is a HTTP stress tool which generates text reports for a really important number 
of statistics. This task generates a HTML report for these statistics.

<pre syntax="xml"><task name="httperf">
    <params>
        <!-- set of ports which will match Mongrel instances (all managed within) -->
        <ports>
            <port>3334</port>
        </ports>
        <processes>
            <process port="3334" url="/controller/action?param=value" 
                requests="50" timeout="2">
                <description>Stressing application with 50 requests (URL http://127.0.0.1:3334/controller/action?param=value), 
                    with a timeout set to 2 seconds.</description>
            </process>
            <process port="3334" url="/controller/action?param=value"
                sessions="10,5,2" rate="5" timeout="3">
                <description>Stressing application with 10 sessions (URL http://127.0.0.1:3334/controller/action?param=value),
                    with a rate of 5 sessions per second. Each  session consists 
                    of 5 calls that are spaced out by 2 seconds. Timeout is set to 3 seconds.</description>
            </process>
        </processes>
    </params>
</task>
</pre>

<a href="httperf.png" target="_blank">Sample</a>

h3. Tests task

Generates a report for the results of your tests.

<pre syntax="xml"><task name="tests">
    <params>
        <runner type="units"/><!-- equivalent to rake test:units -->
        <runner type="functionals"/><!-- equivalent to rake test:functionals -->
        <runner type="integration"/><!-- equivalent to rake test:integration -->
        <runner type="rspec"/><!-- equivalent to rake spec -->
    </params>
</task>
</pre>

<a href="tests.png" target="_blank">Sample</a>

h3. ZenTest task

ZenTest is a tool which generates Ruby code to show your test leaks. This task generates
a report to show where these leaks are.

<pre syntax="xml"><task name="zentest">
    <params>
        <!-- runs an analysis of the efficiency/exhaustiveness of the HomeControllerTest 
            test class against the HomeController class -->
        <runner class="app/controllers/home_controller.rb" test="test/functional/home_controller_test.rb"/>
    </params>
</task>
</pre>

<a href="zentest.png" target="_blank">Sample</a>

h3. Capistrano task

Generates reports for you Capistrano deployments.

<pre syntax="xml"><task name="capistrano">
    <!-- set of runners for your Capistrano deployments -->
    <params>
        <runner task="deploy"/><!-- equivalent to 'cap deploy' -->
    </params>
</task>
</pre>

<a href="capistrano.png" target="_blank">Sample</a>

h2. Demonstration of usage

When the XML file describing your project is written, you can build the Continuous4R
website by typing :

<pre syntax="shell">rake continuous4r:build</pre>

Now you can view the website generated for your project by lauching <strong>[project_folder]/continuous4r_build/index.html</strong>.

h2. Integration within CruiseControl.rb

Integration within CruiseControl.rb is quite simple. You just need to configure your
project to build task "rake continuous4r:build". When the build is done, go to the
detail page of the build, and click on the link below "Custom Build Artifacts".

h2. Help needed

This version 0.0.1 is a beta version of Continuous4r. I'm searching for volunteers
to work on this tool. With a more substancial amount of quality and work, this tool 
could be REALLY GREAT.

h2. License

This code is free to use under the terms of the MIT license. 

h2. Contact

Comments are welcome. Send an email to "Vincent Dubois":mailto:duboisv@hotmail.com,
or post a message on the <a href="http://rubyforge.org/forum/forum.php?forum_id=19721" target="_blank">forum</a>.