This document, together with the hello-world plugin, shows you how to get started with the plugin development.
Hudson defines extensibility points, which are interfaces or abstract classes that model an aspect of a build system. Those interfaces define contracts of what need to be implemented, and Hudson allows plugins to contribute those implementations. See this document for more about extension points.
In this document, we'll be implementing a Builder that says hello. (built-in builders include Ant, Maven, and shell script. Builders build a project.)
Besides this tutorial, there are other tutorials and examples available on line:
To develop a plugin, you need Maven 2 (why?) and JDK 6.0 or later. If this is the first time you use Maven, make sure Maven can download stuff over the internet.
With a fairly recent version of Maven (ie. 2.0.9 or newer) you should only need to add the following to your ~/.m2/settings.xml
(Windows users will find them in %USERPROFILE%\.m2\settings.xml
):
<settings> <pluginGroups> <pluginGroup>org.jvnet.hudson.tools</pluginGroup> </pluginGroups> </settings> |
This will let you use short names of Hudson Maven plugins (ie. hpi:create instead of org.jvnet.hudson.tools:maven-hpi-plugin:1.23:create).
If you are using Maven version earlier than 2.0.9, you'll need to follow additional steps. |
To start a new plugin, run the following maven command:
$ mvn -cpu hpi:create |
This will ask you a few question, like the groupId (the maven jargon for the package name) and the artifactId (the maven jargon for your project name), then create a skeleton plugin from which you can start with. Make sure you can build this:
$ cd newly-created-directory $ mvn package |
NetBeans users can use the IDE's Maven support to open the project directly. (Bundled in 6.7 and up; available from Plugin Manager for 6.5.) The archetype may also be available right from the New Project dialog.
IntelliJ 7.0 (or later) users can load pom.xml directly from IDE, and you should see all the source code of libraries and Hudson core all the way to the bottom.
Use Eclipse 3.3 or later to avoid a bug in Eclipse 3.2 (more details.)
Eclipse users can run the following Maven command to generate Eclipse project files:
$ mvn -DdownloadSources=true -DdownloadJavadocs=true eclipse:eclipse |
Alternatively, Eclipse users can install the maven2 eclipse plug-in, to open a Maven project directly in IDE.
If you get the error message Unable to find a plugin class. Did you put @plugin in javadoc? this maybe caused by eclipse and maven both use the target folder for build output.
Run mvn clean before building with maven or change the output path.
The plugin workspace consists of the following major pieces:
Maven uses it for building your plugin
Java source files of the plugin
Jelly/Groovy views of the plugin. See this document for more about it.
Static resources of the plugin, such as images and HTML files.
Let's take a look at the source code. A plugin's main entry point is a PluginImpl class that extends from Plugin. Once Hudson detects your plugin class (via its inheritance relationship from Plugin
), it will create an instance, and invokes methods.
Most of the time, a plugin class just registers extension points, and your main work involves in implementing those extension points. See the source code for more about how a Builder
is implemented and what it does.
NetBeans 6.7+ users can just hit Debug. For all others, run the following command to launch Hudson with your plugin:
Unix:
$ export MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n" $ mvn hpi:run |
Windows:
> set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n > mvn hpi:run |
If you open http://localhost:8080/
in your browser, you should see the Hudson page running in Jetty. The MAVEN_OPTS
portion launches this whole thing with the debugger port 8000, so you should be able to start a debug session to this port from your IDE.
Once this starts running, keep it running. Jetty will pick up all the changes automatically.
src/main/resources
or resource files in src/main/webapp
, just hit F5 in your browser to see the changes.mvn
at all.
MAVEN_OPTS can be used to specify all sorts of other JVM parameters, like |
If you need to launch the Hudson on a different port than 8080, set the port through the system property port
$ mvn hpi:run -Dport=8090 |
To create a distribution image of your plugin, run the following Maven goal:
$ mvn package |
This should create target/*.hpi
file. Other users can use Hudson's web UI to upload this plugin to Hudson (or place it in $HUDSON_HOME/plugins
.)
If you got to this point, you should definitely consider hosting your plugin on java.net. Move on to this document for how to do that.
mvn -o ...
to avoid hitting repositories every time. This will make various operations considerably faster.users@hudson.dev.java.net
from here so that we can get in touch with you.mvn clean
once, in particular to delete target/work
that Jetty uses. Newer versions may just use work, not target/work. Otherwise your Jetty may continue to pick up old left-over jar files.