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