Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

This document, together with the hello-world plugin, shows you how to get started with the plugin development.

What Can Plugins Do?

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.)

Setting Up Environment

To develop a plugin, you need Maven 2 (why?) and JDK 5.0 or later. If this is the first time you use Maven, make sure Maven can download stuff over the internet.

Next, you'll have to have Maven download the necessary tools for you. Create an empty directory, download this pom.xml in there, and run "mvn package". This should download a bunch of tools.

$ cd /tmp
$ wget https://hudson.dev.java.net/source/browse/*checkout*/hudson/hudson/tools/bootstrap/pom.xml
$ mvn package
$ rm pom.xml

Finally, add the following to your ~/.m2/settings.xml (Windows users will find them in c:\Documents and Settingsyourname\.m2\settings.xml):

<settings>
  ...
  <pluginGroups>
    ...
    <pluginGroup>org.jvnet.hudson.tools</pluginGroup>
  </pluginGroups>

If you are building behind a http proxy, you will need to use Maven 2.0.5 or newer as there is a well known bug fetching artifacts from a https:// repository via a http proxy with Maven 2.0.4.

People very familiar with Maven may be wondering why not just add <pluginRepository> defintions to your settings.xml and not use this "strange" bootstrap/pom.xml method.  This is due to MNG-2261 which causes problems locating plugins when you are in a directory with no pom.xml.  The bootstrap/pom.xml trick should download everything you need into your local repository and bypass the bug.

Also, if your Maven has trouble resolving artifacts, consider adding the following entries to your ~/.m2/settings.xml too. This is a crude way to cause Maven to look at the java.net m2 repository all the time for artifact resolutions.

<settings>
  ...
  <profiles>
    ...
    <profile>
      <id>hudson</id>
      ...
      <repositories>
        ...
        <repository>
          <id>java.net2</id>
          <url>http://download.java.net/maven/2</url>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>hudson</activeProfile>
  </activeProfiles>
</settings>

Creating a New Plugin

To start a new plugin, run the following maven command:

$ mvn org.jvnet.hudson.tools:maven-hpi-plugin:1.11:create

This may not work out of the box. When running the mvn package, I noted that the version it had downloaded was maven-hpi-plugin:1.17-SNAPSHOT, so instead I ran the command:

$ mvn org.jvnet.hudson.tools:maven-hpi-plugin:1.17-SNAPSHOT:create

Which worked for me. If you are failing to achieve this step, verify what version of the maven-hpi-plugin is actually in your system.

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

You should then generate IDE project files, so that you can develop a plugin productively.

// if you are using IntelliJ
$ mvn -DdownloadSources=true idea:idea
// if you are using Eclipse
$ mvn -DdownloadSources=true eclipse:eclipse

NetBeans users should consider using this NetBeans module. Due to a bug in Eclipse, Eclipse users will need to remove src/main/resources from the source folder list after projects are imported to the workspace. See this e-mail thread for more details.

At this point, from your IDE, you should be able to see all files and all the needed libraries complete with their source code.

Plugin Workspace Layout

The plugin workspace consists of the following major pieces:

pom.xml

Maven uses it for building your pluginsrc/main/javaJava source files of the plugin

src/main/resources

Jelly/Groovy views of the plugin. See this document for more about it.

src/main/webapp

Static resources of the plugin, such as images and HTML files.

Source Code

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 (via its @plugin javadoc annotation — this gets copied into manifest during the build), it will create an instance, and invokes methods.

Most of the time, a plugin class just registers extension points. See the source code for more about how a Builder is implemented and what it does.

Developing a Plugin

Run the following command to launch Hudson with your plugin:

$ export 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_OPTSportion 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.

  1. When you make changes to view files in src/main/resources or resource files in src/main/webapp, just hit F5 in your browser to see the changes.
  2. When you change Java source files. Compile them in your IDE and Jetty should automatically redeploy Hudson to pick up those changes There is no need to run mvn at all.

Distributing a Plugin

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.)

Releasing to hudson.dev.java.net

If you have the commit access to the java.net hudson project (and we are giving it away for any plugin developer — you just need to ask) and the java.net maven2-repository project (again you just need to ask), then the easiest way to publish a plugin is to run the maven release plugin:

$ mvn -Djava.net.id=myjavanetid -Dpassword=myjavanetpassword release:prepare release:perform

This will perform all the usual release activity, and it will also post the plugin to the download section. Also, see this document to set up login information so that the uploading can be done programatically.

On Windows you may need to install a CVS client and change the command in the following way (otherwise you will get a CVS authorization error):

$ mvn -Dmaven.scm.provider.cvs.implementation=cvs_native -Djava.net.id=myjavanetid -Dpassword=myjavanetpassword release:prepare release:perform






Other Tips

  1. Consider running Maven like mvn -o ... to avoid hitting repositories every time. This will make various operations considerably faster.
  2. Subscribe to users@hudson.dev.java.net from here so that we can get in touch with you.
  3. When you bump up the version of Hudson you depend on, make sure to run mvn clean once, in particular to delte target/work that Jetty uses. Otherwise your Jetty may continue to pick up old left-over jar files.
  • No labels