Write Your First Plugin

Version 3 by Robin Shen
on Dec 27, 2012 02:18.

<< Changes from 2 to 3

compared with

Current by Robin Shen
on Dec 27, 2012 02:50.

Key

These lines were removed. This word was removed.

These lines were added. This word was added.

View page history

There are 1 changes. View first change.

		To start simple, we will create a plugin adding a "hello world" step to the step choice menu. A "hello world" message will be printed in the build log if this step is executed.

		# Open the plugin development workspace mentioned in the [workspace setup\|Set up Plugin Development Workspace] page.
		# Create a new plugin project as demonstrated below:
		!newproject.png!
		# Click next to bring out the _Plugin Project_ screen. Specify project name and select _Equinox_ as target platform as shown below:
		!newproject2.png!
		# Click next to bring out plugin content screen. Fill various properties and click finish as below:
		!newproject3.png!
		# The plugin overview screen will be presented. Switch to dependencies tab and add plugin _com.pmease.quickbuild_ as required plugins like below:
		!required-plugins.png!
		Press _Ctrl-S_ to save the setting.
		# Create a new class _MyStep_ like below:
		{code}
		package com.example.myplugin;

		import com.pmease.quickbuild.Context;
		import com.pmease.quickbuild.annotation.Editable;
		import com.pmease.quickbuild.stepsupport.Step;

		@Editable(category = "examples", name = "say hello world",
		description = "This step simply prints \"hello world\" into the build log.")
		public class MyStep extends Step {

		private static final long serialVersionUID = 1L;

		@Override
		public void run() {
		Context.getLogger().info("hello world");
		}

		}
		{code}
		Here we define a step class and log a "hello world" messsage in its _run_ method. The annotation _@Editable_ provides some meta information about the step, such as its category, name and description. Refer to [Working with Plugin UI] for more information on how to control user interface by annotating classes.
		{info}Press _F1_ over the _Step_ class (or any other framework classes defined in QuickBuild) will display its documentation since javadoc is automatically associated with the framework plugins when you set up the plugin workspace.{info}
		# Open the class _MyPlugin_, and change it as below:
		{code}
		package com.example.myplugin;

		import com.pmease.quickbuild.extensionpoint.StepProvider;
		import com.pmease.quickbuild.pluginsupport.AbstractPlugin;
		import com.pmease.quickbuild.stepsupport.Step;

		public class MyPlugin extends AbstractPlugin {

		@Override
		public Object[] getExtensions() {
		return new Object[] {
		new StepProvider() {

		@Override
		public Class<? extends Step> getStepClass() {
		return MyStep.class;
		}

		}
		};
		}

		}
		{code}
		Here class _AbstractPlugin_ is defined in project _com.pmease.quickbuild_, and every plugin needs to extend this class. The _getExtensions_ method returns an array of extensions, and each extension needs to extend an extension point defined in QuickBuild framework or other plugins. Here we extend the extension point _StepProvider_ to provide a new step type. Open file _<QuickBuild install dir>/plugins/com.pmease.quickbuild.bootstrap/javadoc.zip/com/pmease/quickbuild/extensionpoint/package-summary.html_ for all extension points defined in the framework.
		# {anchor:export_package} Save above classes, bring up the plugin manifest editing UI by double clicking file _META-INF/MANIFEST.MF_ of the plugin, switch to the runtime tab and export all packages of the plugin like below:
		!export_package.png!
		# Now we've finished developing of our first plugin. Let's examine the result by launching QuickBuild through the Bootstrap configuration like below:
		!launch3.png!
		# Open a browser and point to address _http://localhost:8810_ (or any other port you've configured in file _<QuickBuild install dir>/conf/node.properties_). Set up the server if necessary, and select the root configuration in QuickBuild. Switch to _steps_ tab and click the _add_ icon at right side of the master step, you will be presented with below screen:
		!step1.png!
		A new category _examples_ appears in the step menu containing a new step type _say hello world_. Select this step and click save on the step definition screen.
		# Click run button to run _root_ configuration, a new build will be generated after a while. Select _log_ tab of the newly generated build, you will find the logged "hello world" message like below:
		!log.png!
		# After you've finished writing and testing the plugin, you can export the plugin to QuickBuild server's installation directory for production use. To do so:
		## Right click desired plugin projects and select _export_ menu item from the popup menu like below:
		!export1.png!
		## Select _Deployable plugins and fragments_ in the next dialog like below:
		!export2.png!
		## Click next, and specify QuickBuild server's installation directory in the next dialog as below:
		!export3.png!
		## Click the finish button, and the plugin will be exported to the _plugins_ sub directory under QuickBuild server's installation directory. Now you can run command _bin/server.(bat\|sh) console_ to start QuickBuild outside of Eclipse, and the newly exported plugins will be loaded. The plugin will also be propogated to all connected agents automatically upon server startup.
		{info}Exporting to QuickBuild server's installation directory is not mandatory, you can also deploy the plugin by exporting it to some other directories, and manually copy exported plugin to _plugins_ folder under QuickBuild server's installation directory later.{info}
		# {anchor:headless_build}To build plugin in headless mode:
		## Make sure you have [Ant\|http://ant.apache.org] installed.
		## Place all your plugin projects in a directory, and copy file _<QuickBuild server install dir>/dev/plugin/samples/build.xml_ to that directory. The directory should then look like this:
		{code}
		build.xml
		com.example.myplugin
		com.example.anotherplugin
		{code}
		## Open a command prompt window and change to that directory. Define environment variable _QUICKBUILD_HOME_ to point to installation directory of QuickBuild.
		## Run command _ant_ to build the plugins. If successful, you will find your plugins packaged in sub directory _stage/plugins_.
		## You may run command _ant clean_ to optionally clean generated directories and files.