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