How to Build an Atlassian Plugin

Overview

This documentation contains all of the information you'll need to start building your own plugins and extensions for Atlassian's products. We set several goals for our plugin development process:

Allow you to set up a complete plugin development environment with just a few commands.
Ensure that all plugins are set up, built, tested and released in a consistent way.
To allow you to use the IDE you prefer.
To make the code/deploy/test cycle as efficient as possible.
To encourage unit and functional testing
To use continuous integration and code coverage metrics to ensure plugins are of high quality, and that they stay compatible with new releases of the products.
Make it easy to release your plugins to the community.
To encourage collaboration around plugin development.

Quickstart for the impatient

Download and install JDK 1.4. or JDK 5
Download and install the latest release of Maven 2.
Follow the instructions at Example settings.xml
Create a plugin template using one of the Atlassian Plugin Archetypes.
Run mvn idea:idea or mvn eclipse:eclipse in the top-level directory of your new plugin.
Open your IDE and start coding.
Write unit and functional tests.
Release your plugin.

Please note that the new Eclipse plugin is unable to deal with source 'includes' and 'excludes'.

Use the following command :mvn org.apache.maven.plugins:maven-eclipse-plugin:2.6:eclipse as this will force mvn to use version 2.6 of the maven eclipse plugin.

The error that you will see if 2.7 is used in your mvn build :

[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Request to merge when 'filtering' is not identical. 
[INFO] Original=resource src/main/resources: output=target/classes, 
[INFO]    include=[atlassian-plugin.xml], exclude=[**/*.java], test=false, 
[INFO]    filtering=true, merging with=resource src/main/resources: 
[INFO]    output=target/classes, include=[], exclude=[atlassian-plugin.xml|**/*.java], 
[INFO]    test=false, filtering=false
[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------

Requirements

Java: Depending on which Atlassian product (and which version of the product) you are building plugins for, you may need either JDK 5 or JDK 1.4. Many of Atlassian customers are still using Java 1.4, either by choice or because their app servers still require it. If you are building a plugin exclusively for internal use, you're free to target whichever JDK you wish. However, if you are planning to share your plugin with other Atlassian users, you must check what requirements your targetted product has, and unless stated explicitly we recommend you make sure that it is compatible with Java 1.4.

Read How do I specify a particular version of Java? to learn how to use Java 5 language features or enforce building with a particular version of Java.

Maven 2: The Atlassian plugin development process depends heavily on Maven. Calling Maven a "build tool" would be an understatement - but if you have no experience with Maven yet, start thinking of it as a tool for simplifying your life by building your plugin. Quoting its homepage, "Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information."

Maven is particularly useful in this instance because it can automatically manage massive dependency trees - especially transitive dependencies where Plugin X depends on Product Y, which depends on Shared Library Z. Using Maven, you should be able to quickly and easily retrieve all the dependencies that your plugin will need, and create a working development environment in just a few steps.

Download and install the latest release of Maven 2. You must install Maven 2.0.9 or newer.

Atlassian Maven PDK: We've written a Maven extension specifically for plugin developers. The extension provides a new packaging type for atlassian-plugins, gives you some utility methods for uploading, enabling, disabling and uninstalling a plugin to the product, and provides methods for integration and functional testing. This plugins is automatically installed when you build an Atlassian plugin.

More information about the Atlassian Maven PDK

Settings.xml

In order for Maven to find and download all of the necessary dependencies, we have to tell it where everything is stored. The best option is to do that once, in your $HOME/.m2/settings.xml file. We've included instructions and an example that you can copy and paste at Example settings.xml. If you look closely, you will find two lines containing placeholders for username & password. Don't worry about them at this moment — you don't need them to get started.

Your plugin will depend on many different artifacts: the Atlassian product itself, Atlassian modules and various open-source libraries. All of those artifacts are stored in different maven repositories scattered around the net. However, to simplify configuration and speed downloads, Atlassian provides a Maven proxy that contains all of the dependencies for all of our products. The example settings file contains just one repository entry for this proxy, and saves Maven from having to check several different repositories for each artifact it needs. You can find more information about the repositories that are behind the Maven Proxy.

Atlassian will release binary and javadoc artifacts for all of our product releases and their Atlassian-managed dependencies. We will release source artifacts wherever we can freely do so. Some of our closed-source artifacts will only be available via manual download by source-license-holders.

We will also be releasing various milestone and snapshot releases during product development to aid plugin developers in testing their work against upcoming product releases.

You will be able to find all of these artifacts in the Maven proxy.

Creating a skeleton plugin

Now you're ready to create your (skeleton) plugin. This involves creating plenty of directories and subdirectories, two XML files and initial Java files. Fortunately, Maven can help here, too, and simplify your life a lot! Maven has a concept called an Archetype, which is basically a plugin template. We've created plugin templates for each of our pluggable products, so you can use those templates to set up your initial plugin skeleton easily. You can find the Atlassian Plugin Archetypes and how you use them here. Visit the page, create a plugin for your targetted Atlassian product, and return to this page later.

Running an plugin archetype will download dependencies from the internet, set up a project skeleton, and prepare you to run unit and functional tests. Once you run the Maven archetype command, you'll find that it creates a new directory structure that looks like this:
Here a a few points to note:

the "pom.xml", which stands for Project Object Model definition file.
Directories for your sources and test sources.
Directories for your resources (templates, javascript, css, images, etc.)
The "it" package for your integration tests.
An atlassian-plugin.xml plugin definition file.
A license file.

It's important to understand a little bit about the pom.xml, and what's in it. The Project Object Model describes everything that maven needs to know about your plugin, from dependencies, to source control, to authors, to tests, to deployment locations. The POM is also hierarchical, so many properties are inherited. You'll note that this pom.xml inherits from something like confluence-plugin-base, which contains lots of information about the products and the Atlassian development environment. Some properties are later overridden in your plugin's POM.

We've written a page with an Example pom.xml that explains what's going on in your plugin's POM.

Please note: The plugin now knows about the target product's binaries, because it has downloaded the JAR files - but it has not downloaded the actual source code. You don't need to have access to the target product's sourcecode to be able to develop a plugin, the JAR files alone will enable you to go and write the plugin, using the product's API. If you do have access to the source code (e.g. as a commercial license holder) then it helps to download and set up the source code now:

Special section for commercial license holders with Confluence source access.

Since you have purchased a commercial license to Confluence, you have access to the Confluence source code. You can download a source distribution by visiting http://my.atlassian.com. You can attach the Confluence source code to your plugin project so that you can step through the Confluence code in your debugger. It's often helpful to do this to better understand that API, or to track down problems.

Once you've downloaded and unpacked the source distribution, you'll see a bunch of directories and files, exactly as they are checked out of our SVN repository. This is perfect for reading and exploring, but it doesn't do you much good in the brave new world of Maven 2. So what you'll need to do is create and install source artifacts into your local maven repository. Once you've done that, the maven IDE plugins will recognize that they are there and link them up for debugging purposes.

From the top level of the source distribution, run:

mvn source:jar install -Dmaven.test.skip=true

This will build JAR files containing most of our source-code into the target directory of each subproject. There are still a few items that aren't yet set up for this, but the important ones are, like the core product source code. Likewise, we will soon be enabling this same process for JIRA.

The JAR files can be copied into your local Maven repository to make them available in your IDE when you run mvn idea:idea or mvn eclipse:eclipse. For example, to install the source code for Confluence 2.10 core, copy confluence-project/confluence/target/confluence-2.10-sources.jar to $HOME/.m2/repository/com/atlassian/confluence/confluence/2.10.

A note about memory: This is a resource intensive process, and you may need to allocate more memory to maven in order to complete it. You can do so be setting an environment variable called MAVEN_OPTS, like so export MAVEN_OPTS=-Xmx512m

A note about versions: Make sure that you download and install the same version of the source code that is set in the atlassian.product.version property in your pom.xml.

Maven and your IDE

We have our plugin skeleton, and now it's time to get it set up in your IDE, if you use one. Once again, Maven comes to the rescue. Maven has plugins to generate project files for both Eclipse and IntelliJ IDEA. Our instructions will cover these two IDEs, but you're free to use whichever IDE or editor you prefer.

To set up your IDE project, simply run mvn eclipse:eclipse or mvn idea:idea from the root folder of the newly created directory (e.g. where the pom.xml resides).

First, Maven will download all of the dependencies referenced in your pom.xml, and then all the inherited dependencies from the parent POMs. Your settings.xml specifies that maven should down the javadoc and source files as well, where they are available. This is likely to take quite a while: Depending on what product you are targetting, Maven will now download hundred MB or more from the internet. Go relax, get some coffee, read a blog. Fortunately, after you've downloaded these files for the first time, they are stored in your local Maven repository ($HOME/.m2/repository/) and won't be downloaded again unless they change.

In case this process ended with an error message (e.g. "required artifact missing") please refer to FAQ and Troubleshooting

Second, Maven will construct project files that your IDE can understand. It will reference all the dependent jars in the right projects, and attach the sources and javadoc where they are available. Note, when you're ready to check in your plugin, don't commit these project files as they are generally specific to each developer's machine.

Open the project files in your IDE, and you should see the mostly-empty template directory for your new plugin, matching the directory structure in the screenshot above.

Eclipse Workspace Setup
Eclipse requires an additional one-time step to configure your workspace with the Maven repository location:

 mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo

You can also accomplish the same thing by adding the M2_REPO classpath variable, pointing to your .m2/repository directory, in Eclipse preferences

Using a different build tool

These instructions depend on using Maven. However, if you want to use your own build environment (e.g. Ant), the following Maven command will export all the JAR files you need to develop against to the directory you specify, and you can then ensure that these JAR files are in your CLASSPATH using your build tool.

mvn dependency:copy-dependencies -DoutputDirectory=<specify a directory>

Developing your plugin

So now what? Find out how the development/test/debug cycle works. We've tried to make it as efficient as possible.

Testing your plugin

Atlassian plugins depend on Maven 2 for running their test suites. This is advantageous because all plugins are always tested the same way, and because Bamboo, our continuous integration server, can do likewise.

Building a suite of tests for your plugin is extremely important. We're big believers in Test Driven Development, and we think that writing tests as you go is one of the best ways to ensure you build a high-quality and functional application. Additionally, having a comprehensive suite of tests means that other developers in the community (or even Atlassian developers) can jump in and collaborate on your plugin without fear of breaking anything inadvertently.

Find out how to make it happen on the Testing your plugin page.

A note about quality

We have set certain criteria for our own plugin development. If you are working on a plugin that you wish to share with the community, we encourage you to try and meet these same criteria in your work. It will result in a higher quality product and make it easier for other to collaborate.

Your plugin should:

be available in Developer Network SVN.
have its dependencies in the Developer Maven Repository.
have a JIRA project.
have a Bamboo Project.
be in the plugin repository (for Confluence).
have unit and functional tests with a significant amount of code-coverage.
have complete, accurate and attractive documentation in the Plugin Library on Confluence.
display a compatibility matrix for the last three product releases.
be internationalized.

Atlassian offers hosting for plugins to all authors. Find out more about the resources and how to take advantage of them here.

Releasing your plugin

Atlassian offers lots of services to help you host your plugin development project. We can provide an SVN repository with Fisheye and Crucible, a JIRA project, Confluence space, a Bamboo Project, a Maven repository for artifacts, and more. When you're ready to start collaborating with other developers on your plugin project, read about Releasing your plugin. Contact us and we'll grant you account and get everything set up for you.

Resources

Where do you go for help? For questions about plugin development for Atlassian products, head to the Developer Forum. These are community run forums where other plugin developers ask and answer questions, get advice, and publicize their latest work.

FAQ and Troubleshooting
Plugin Development Resources
Developer Mailing Lists and Support
Report bugs with the plugin development process

NOTE: Please do not file support tickets at http://support.atlassian.com regarding plugin development questions. The engineers on support are not equipped to answer those sorts of questions.

How to Build an Atlassian Plugin

Overview

Quickstart for the impatient

Requirements

Settings.xml

Creating a skeleton plugin

Special section for commercial license holders with Confluence source access.

Maven and your IDE

Using a different build tool

Developing your plugin

Testing your plugin

A note about quality

Releasing your plugin

Resources

Labels

Children (7)

Comments (63)

Bill Smith says:

ananth says:

aaron frishling says:

ananth says:

aaron frishling says:

Kristyn Oliveti says:

Jonathan Nolen says:

Roberto Dominguez says:

Joshua Goodall says:

Matt Doar says:

Matt Doar says:

Matt Doar says:

Frank Stiller says:

Ali Ibrahim says:

Chris Fletcher says:

David Peterson [CustomWare] says:

Justy Justinson says:

Tim Moore says:

Michael Immell says:

iconde says:

Tim Moore says:

Jacky Li says:

Tim Moore says:

Jacky Li says:

Jacky Li says:

Tim Moore says:

Jacky Li says:

Ray La Valley says:

Tim Moore says:

joshua Rodman says:

Tim Moore says:

Jeff Kirby says:

Jeff Kirby says:

Tim Moore says:

Ethan McDonald says:

Jeff Kirby says:

Ethan McDonald says:

Tim Moore says:

Daniel Berkich says:

Tim Moore says:

Thomas Allen says:

Tim Moore says:

Thomas Allen says:

Tim Moore says:

Jeff Kirby says:

Jeff Kirby says:

Espog says:

Jonathan Nolen says:

Espog says:

Tim McDougall says:

Wayne Le-Trung says:

Jonathan Nolen says:

Wayne Le-Trung says:

Kevin Ross says:

Kevin Ross says:

Roberto Dominguez says:

Tim Moore says:

Thomas Dudziak says:

Royce Wong says:

Thomas Dudziak says:

Conversión Magro says:

Stefan Wolf says:

Stefan Wolf says: