The project recipe
******************

The ``collective.buildbot:project`` recipe is responsible for creating
the buildbot configuration for a project which is a single testable
component. Whether this project corresponds to a single sofware
package or many is up to you. In most cases a project corresponds to a
buildout which in turn may contain one or many software packages. Each
project has a separate state and is visualized as a column in the
waterfall display.

This recipe should be used in the same buildout with
``collective.buildbot:master``.


Supported options
=================

The recipe supports the following options:

``slave-names`` (mandatory)

  A white-space separated list of slave names that the project will be
  built on. These must correspond to the section names that use the
  ``collective.buildbot:slave`` recipe and that are consequently
  referred in the ``slaves`` option of the section using the
  ``collective.buildbot:master`` recipe.

``vcs`` (optional)

  The version control system used to obtain the source code for the
  project. Defaults to ``svn``. Other possible values are: ``hg``,
  ``bzr`` and ``git``.

``repositories`` (mandatory)

  A sequence of newline separated URLs to the code repositories that
  correspond to the selected version control system. For Subversion
  this could be something like
  ``https://svn.plone.org/svn/collective/collective.buildbot/trunk``
  or for Git something like
  ``git@github.com:dokai/hexagonit-swfheader.git``.

  For each repository you define a separate Buildbot project
  configuration will be generated that shares all the other
  options. This is useful if you have multiple similar projects within
  the same repository and can save you a lot of typing. Since
  Subversion URLs contain the branch information it is even possible
  to pull in code from separate branches. For other version control
  system that use the ``branch`` option (e.g. Git) you're limited to a
  single shared branch name.

``branch`` (optional)

  The branch in the version control system that will be checked
  out. For Subversion checkouts you should provide the full URL to the
  desired branch (e.g. something that ends with ``trunk`` or
  ``branches/foo``) and leave this option empty. For Git repositories
  the default value is ``master``.

``email-notification-sender`` (optional)

  An email address that will be used in the From: header for the
  notification messages.

``email-notification-recipients`` (optional)

  A newline separated sequence of email addresses the notification
  messages will be sent to.

``build-sequence`` (optional)

  A newline separated sequence of shell commands executed on the build
  slave after checking out the code from the repository that will
  build the project.

  Defaults to::

    bin/python bootstrap.py
    bin/buildout

  which is appropriate for buildout based projects.

``test-sequence`` (optional)

  A newline separated sequence of shell commands executed on the build
  slave to execute the test suite. Defaults to::

    bin/test

``periodic-scheduler`` (optional)

  Sets up a periodic scheduler that schedules a build every ``n``
  minutes, where ``n`` is the given integer value.

``cron-scheduler`` (optional)

  Sets up a cron-like scheduler that schedules a build at a given
  time. The time is configured in a crontab manner using white space
  separated values for the following fields::

    [minute] [hour] [day of month] [month] [day of week]

  The values should be integers in the approriate range for the given
  field or ``*`` (asterisk) for all values. For example to schedule a
  build at 3:00 am every night you would use::

    cron-scheduler = 0 3 * * *

``pyflakes`` (optional)

  A sequence of newline separated PyFlakes_ commands to run. If
  defined, the given PyFlakes commands will be run after the test
  sequence.

  The commands should consist of a path to the ``pyflakes`` script and
  a path to the source code container. For example, using a global
  pyflakes installation on a project located under
  ``src/some.project`` within the build directory you would set::

    pyflakes = pyflakes src/some.project

  You can also have your slave buildout install pyflakes and use that
  instead of a globally installed version.

  .. _PyFlakes: http://divmod.org/trac/wiki/DivmodPyflakes   

Example usage
=============

We'll start by creating a buildout that uses the recipe. A full
example would propably have other sections defining the build master
and slaves, but here we will demonstrate only the use of the
``collective.buildbot:project`` recipe.

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = my.package
    ... 
    ... [my.package]
    ... recipe = collective.buildbot:project
    ... slave-names = slave1
    ... vcs = svn
    ... repositories = http://example.com/svn/my.package/trunk
    ... """)

Running the buildout gives us::

    >>> print system(buildout)
    Installing my.package.
    Generated config '/sample-buildout/parts/projects/my.package.cfg'.

As we can see, the recipe generated the project configuration file
under the ``projects`` directory in the parts::

    >>> cat(join('parts', 'projects', 'my.package.cfg'))
    [project]
    ...
    name = my.package
    repository = http://example.com/svn/my.package/trunk
    ...
    slave-names = slave1
    ...
    vcs = svn
    <BLANKLINE>

If you have multiple similar projects you can define them within a
single buildout section by providing multiple repository URLs. All the
projects share the same options (except the repository URL). To
further reduce repetition we've defined the base URL to our repository
in the buildout section.

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = my_project
    ... svn = http://svn.example.com/svnroot
    ... 
    ... [my_project]
    ... recipe = collective.buildbot:project
    ... slave-names = slave1
    ... vcs = svn
    ... repositories =
    ...    ${buildout:svn}/my.package/trunk
    ...    ${buildout:svn}/other.package/tags/1.2.3
    ...    ${buildout:svn}/third.package/branches/foobar
    ...    ${buildout:svn}/third.package/branches/another
    ... """)

When we run the buildout we can see that it generated a separate
configuration file for each project representing a single repository::

    >>> print system(buildout)
    Uninstalling my.package.
    Installing my_project.
    Generated config '/sample-buildout/parts/projects/my.package.cfg'.
    Generated config '/sample-buildout/parts/projects/other.package.cfg'.
    Generated config '/sample-buildout/parts/projects/third.package.cfg'.
    Generated config '/sample-buildout/parts/projects/third.package_2.cfg'.


The projects recipe
*******************

The ``collective.buildbot:projects`` recipe is deprecated and not
supported anymore. Simply supply multiple repositories for the
``collective.buildbot:project`` recipe to achieve the same result.

  
