Preparing for Plugin Development

Download and install a JDK

Jenkins is based on Java, and to build Jenkins plugins, you need to install a Java Development Kit, or JDK. Recent Jenkins releases require JDK 8 to run, so that’s what we’re using here.

Download JDK 8 for free from the Oracle website and install it.

Many Linux distributions provide packages for Oracle JDK or OpenJDK JDK for an easier install and upgrade experience. Consult your distribution’s documentation for details. It may even be installed already. To find out, type javac -version on a command prompt.

Download and install Maven

Jenkins plugins overwhelmingly use Maven to build, so that’s what we’re going to use in this tutorial.

Download Maven from its website. Make sure to download one of the files with bin in their name. src indicates a source distribution.

Many Linux distributions provide packages for Maven for an easier install and upgrade experience. Consult your distribution’s documentation for details. On macOS, the Homebrew package manager offers Maven packages. Make sure a recent version of Maven 3, ideally 3.3.9 or newer, is provided if you decide to go this route.

Download and extract Maven, and note its location. You now have the following options:

  1. Add the bin/ subdirectory of the extracted directory to your PATH. This will let you invoke Maven using mvn. How this works is dependent on your OS and command shell.

  2. Always use the full path to the mvn executable, for example ~/Applications/apache-maven/bin/mvn or C:\Program files\Maven\bin\mvn

The rest of the tutorial assumes that Maven is on your PATH, but you can also just type the full path.

Once downloaded and extracted somewhere, let’s make sure everything works as expected by typing the following in a command prompt:

This is Terminal.app on macOS, cmd.exe on Windows, and any shell on Linux.
mvn -version

This prints some diagnostic output, including the versions of Java and Maven, and which Java installation was found by Maven. This should indicate a 1.8 version of Java, and list the path to the JDK. If either of these is not the case, see Troubleshooting.

Setting up a productive environment with your IDE

NetBeans

NetBeans users can use the IDE’s Maven support to open the project directly.

As you navigate through the code, you can tell NetBeans to attach source code JAR files by clicking the "Attach" button that appears in the top of the main content window. This allows you to read the Jenkins core source code as you develop plugins. (Or just select Download Sources on the Dependencies node.)

You are advised to use the NetBeans plugin for Jenkins/Stapler development. This offers many Jenkins-specific features. Most visibly, create a new plugin using New Project » Maven » Jenkins Plugin, and use Run project to test it.

IntelliJ IDEA

IntelliJ 7.0 (or later) users can load pom.xml directly from IDE, and you should see all the source code of libraries and Jenkins core all the way to the bottom. Consider installing the IntelliJ IDEA plugin for Stapler to make the development easier.

Alternatively,emtpy create a new Maven project using Create from archetype and Add an Archetype. Select the GroupId and ArtifactId as above and choose RELEASE as version. In the next screen select io.jenkins.plugins as groupID and choose an artifactId (Project name) and Version to your liking. This will automatically create a maven project based on the specified artifact (e.g. empty-plugin).

IntelliJ defaults to downloading sources and JavaDocs on demand. So, to see the source, you may need to click the Download artifacts button in the Maven Projects tab.

Eclipse

Use Eclipse Juno (4.2) or later for the best experience.

Eclipse versions between 4.5 and < 4.6.2 contain a bug that causes errors such as "Only a type can be imported. hudson.model.Job resolves to a package". If you encounter this error please upgrade to Eclipse Neon.2 (4.6.2) or higher (Bug 495598).

As Jenkins plugins are Maven projects, Eclipse users have two ways to load a Jenkins plugin project. One is to use m2e, which tries to make Eclipse understand Maven "natively", and the other is to use theusing maven, but Maven Eclipse plugin, which makes Maven generate Eclipse project definitions. At the moment, unless you have some prior experience with m2e, we currently recommend plugin developers to go with the Maven Eclipse plugin.

Eclipse users can run the following Maven command to generate Eclipse project files (the custom outputDirectory parameter is used to work around the lack of JSR-269 annotation processor support in Eclipse:)

$ mvn -DdownloadSources=true -DdownloadJavadocs=true -DoutputDirectory=target/eclipse-classes -Declipse.workspace=/path/to/workspace eclipse:eclipse eclipse:configure-workspace

Where /path/to/workspace is the path to your Eclipse workspace.

Once this command completes successfully, use "Import…​" (under the File menu in Eclipse) and select "General" > "Existing Projects into Workspace".

Do not select "Existing Maven Projects", which takes you to the m2e route

See Jenkins plugin development with Eclipse for gotchas and other known Eclipse/Maven related issues with Jenkins plugin development.

See Eclipse alternative build setup for an alternative way of setting up the Eclipse build environment, that is a bit more technically involved than using Maven but can give faster build times.

Troubleshooting

Anything not working for you? Ask for help in IRC or on the jenkinsci-dev mailing list.

References