a place to collect directions and hints about writing plug-ins.

Getting prepared

Be sure to read the documentation on plugins.

Then have a look at the build loop code: you will probably find an existing plugin that is very similar to what you want to do. That will give you a skeleton.

Finally do not hesitate to send a mail to the developer list before and after you write your plugin. You will probably get advices and coding reviews.

General

A plugin is made of one or several classes, but only the main class will be known to CruiseControl.

CruiseControl defines a set of interfaces and your plugin main class will have to implement at least one of them.

Plugin registration

In order to use your plugin, you will have to make your plugin accessible to the config file. There are 2 ways to achieve this registration:

• you use the <plugin>-element for that, as documented in the plugin documentation page.
• if you're writing your plugin as a patch that you want to be integrated into CruiseControl, you can add your plugin to the default-plugins.xml file instead. This is not recommended for your own custom plugins, as you'd need to patch the default-plugins.xml for every new release of CruiseControl.

Plugin configuration

To add XML attributes (e.g. <myplugin param=".">) you need to add an appropriately named public void setParam(TYPE) method for each attribute that can be set. You should check these are set correctly in your plugin's validate() method, throwing a CruiseControlException if a value is missing/illegal. TYPE can be one of the following:

• String
• int
• long
• boolean

Currently, CruiseControl uses its own mechanism for calling your setter, so you can't register JavaBean PropertyEditors to have other types in your setter-methods. This is no real problem, it just means you have to do the conversion from String to your type yourself in the setter.

Please keep in mind that you don't need to write a getter for every setter; the setters are only used to inject the properties! This is mistake often seen in many contributed plugins.

A new instance of your plugin will be created on every run of the project that uses it, so you can't keep state in instance variables between different runs. Also, plugins are meant to be loosely coupled with the rest of the system, so you can't query other plugins for info from your plugin code.

Types of plugins

Bootstrappers

SourceControls

Builders

See also WritingBuilderPlugins

Publishers

Finalizing

Submitting your plugin

If you think your plugin is general enough, (e.g. support a new source control), you want to try to get your plugin integrated into CruiseControl.
The general recommendations for submitting patches still apply. There are a couple of things that are specific to submitting plugins:

• add your plugin to the default-plugins.xml file
• document your plugin in configxml.html

Common coding mistakes

A list of commong coding mistakes. Might as well be moved to a separate page as this applies to all new development

• getters matching your plugin setters are not always necessary
• no unit tests. Your code is probably broken
• unit tests reading resources using a non flexible access strategy (e.g. hardcoded paths). Make sure they cab be run both from your IDE and the command line.
• external commands. CruiseControl provides a set of classes to run external commands. These classes provide functionality to make your code more robust (e.g. time out management) and easier to write and test.
• RuntimeException. Some methods will throw runtime exceptions when passed an invalid argument. This often happens if you wrote your code with a particular assumption (e.g. you expect a particular String format but get something else). Be sure to check the return values of all the methods that can give you a hint that something is going wrong. A particular incarnation of this issue is when using String#indexOf combined with String#substring. When the parsed format changes (e.g. you integrate with a different version of the tool), you will probably get an error there. Better to detect it early, (e.g. checking the return of String#indexOf and treat -1 by logging the appropriate error message, making the job of the person encountering the issue much easier to diagnostic.