Creating custom Pre-Build and Post-Build options

Yes, pretty well everything in the Build component is open-ended (except for the web UI, but we're working on that for 3.0).

To add a pre-build or post-build option, you'll need to do the following:

1. Add a new 'build configuration element' extension to allow extra configuration on the build definition.
2. You'll probably want to define a new 'build definition template' to allow your new configuration to be chosen by default (or just be made available) when creating a new build definition. You choose a template in the first page of the build definition wizard.
3. To add UI to the build definition editor for setting the various properties, you'll need to add a 'build configuration element editor' extension to the Eclipse UI.
4. To do the real work in the build engine using the configured info (unless it's just to pass properties through to the build script), you'll need to add a 'build participant' extension to the build engine.

For example, the Jazz SCM pre-build participant does the following for each of the above:

1. Build configuration element for Jazz SCM, currently defined in the plugin.xml for com.ibm.team.build.common. Note the PRE_BUILD phase is specified here, so it shows up in the pre-build options page of the build definition wizard.

    <extension

          point="com.ibm.team.build.common.buildConfigurationElements">



        <buildConfigurationElement

            id="com.ibm.team.build.jazzscm" buildPhase="PRE_BUILD"

            description="%JazzScmConfigElementDescription"

            name="%JazzScmConfigElementName">

             <configurationProperty name="com.ibm.team.build.engine.variable.substitution"/>

            

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.workspaceUUID"

                       description="%JazzScmWorkspaceUUID" 

                       required="true"

                       kind="com.ibm.team.scm.property.workspace"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.fetchDestination"

                       description="%JazzScmDestination" 

                       required="true"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.deleteDestinationBeforeFetch"

                       description="%JazzScmDeleteDestinationBeforeFetch" 

                       required="true"

                       defaultValue="false"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.acceptBeforeFetch"

                       description="%JazzScmAcceptFirst" 

                       required="true"

                       defaultValue="true"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.buildOnlyIfChanges"

                       description="%JazzScmBuildOnlyIfChanges" 

                       required="true"

                       defaultValue="true"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.componentLoadRules"

                       description="%JazzScmComponentLoadRuleUUIDs" 

                       required="false"

                       defaultValue=""/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.includeComponents"

                       description="%JazzScmIncludeComponents" 

                       required="false"

                       defaultValue="false"/>

             <genericProperty

                       genericEditAllowed="false"

                       name="team.scm.loadComponents"

                       description="%JazzScmLoadComponentUUIDs" 

                       required="false"

                       defaultValue=""/>

        </buildConfigurationElement>

    </extension>

2. Although Jazz SCM doesn't define its own template, it's added as an available configuration in other ones, such as the template for Ant (again excerpted from the plugin.xml for com.ibm.team.build.common):

    <extension

          point="com.ibm.team.build.common.buildDefinitionTemplates">

        <buildDefinitionTemplate

              id="com.ibm.team.build.ant"

              description="%AntTemplateDescription"

              name="%AntTemplateName">

           <buildConfigurationElement id="com.ibm.team.build.general"/>

           <buildConfigurationElement id="com.ibm.team.build.ant"/>

           <buildConfigurationElement id="com.ibm.team.build.schedule"/>

           <buildConfigurationElement id="com.ibm.team.build.properties"/>

           <availableBuildConfigurationElement id="com.ibm.team.build.jazzscm"/>

           <availableBuildConfigurationElement id="com.ibm.team.build.jdt.publishing"/>

           <availableBuildConfigurationElement id="com.ibm.team.build.junit.publishing"/>

        </buildDefinitionTemplate>

    </extension>

3. The Jazz SCM page of the build definition editor is contributed by the following extension in com.ibm.team.build.ui.

    <extension

          point="com.ibm.team.build.ui.buildConfigurationElementEditors">

        <buildConfigurationElementEditor

              class="com.ibm.team.build.internal.ui.editors.builddefinition.JazzScmConfigurationEditorFactory"

              configurationElementId="com.ibm.team.build.jazzscm"

              name="%JazzScmEditorName">

        </buildConfigurationElementEditor>

    </extension>

The JazzScmConfigurationEditorFactory class implements com.ibm.team.build.ui.editors.builddefinition.IConfigurationElementEditorFactory, which is a simple factory interface. In this case it creates an instance of com.ibm.team.build.internal.ui.editors.builddefinition.JazzScmConfigurationEditor, which extends the API class com.ibm.team.build.ui.editors.builddefinition.AbstractConfigurationElementEditor.

4. To do the actual work of accepting changes and loading the build workspace, the Jazz SCM build participant extension is added to the build engine (this time in plugin com.ibm.team.build.engine). Note that the phase is repeated here.

    <extension

          point="com.ibm.team.build.engine.buildEngineParticipants">

        <buildEngineParticipant

            id="com.ibm.team.build.internal.engine.JazzScmPreBuildParticipant"

            class="com.ibm.team.build.internal.engine.JazzScmPreBuildParticipant"

            buildPhase="PRE_BUILD"

            configurationElementId="com.ibm.team.build.jazzscm">

        </buildEngineParticipant>

    </extension>

The JazzScmPreBuildParticipant class extends the API class com.ibm.team.build.engine.AbstractPreBuildParticipant, which in turn extends com.ibm.team.build.engine.AbstractBuildEngineParticipant.

For more details on how these are implemented, you can check the source, available in the RTC SDK:
https://jazz.net/wiki/bin/view/Main/RtcSdk20

More programming examples using the Build API are available at:
https://jazz.net/wiki/bin/view/Main/BuildJavaProgrammingExamples

Regards,
Nick Edgar
RTC Build component lead

See also: https://jazz.net/wiki/bin/view/Main/BuildArchitecture
for a high-level overview of the architecture of RTC Build.
From this you can see where the various extensions mentioned above live. The extensions in 'common' plug-ins exist in both the Eclipse client and the Jazz server. 'ui' plug-ins are just in the Eclipse client. 'engine' plug-ins are used in the build engine (jbe process), which is also a client of the Jazz server (and therefore includes 'common' and 'client' plug-ins).

Hi,

I'm also keen to do something similar to this original request, but I hope its far simpler. I'm hoping to add the JAZZ SCM as a pre build step to the existing Generic Build Template. It seems from the information above that this will be both possible and simple. However I do not know where to find the plugin.xml for com.ibm.team.build.common.

I'm very new to plugin development/enhancement for Jazz so hopefully I've not missed something. I have however looked around and lack this final piece of information.

I hope you can help.

Thanks in advance.

Kind regards, Andrew

Hi Andrew,

Could you clarify why you want to add Jazz SCM to the Generic template? Normally the Generic template is used only when the build is driven externally, e.g. from an Ant script, in which case the script uses the teamAccept and teamFetch Ant tasks to do the SCM work.

If we were to add Jazz SCM to the Generic template, then it could do the SCM work for you, but it then has no way to do the rest of the build.

But to answer your questions:
> I do not know where to find the plugin.xml for com.ibm.team.build.common.
The com.ibm.team.build.common plug-in can be found under {installDir}\jazz\client\eclipse\jazz\build\eclipse\plugins in the RTC Eclipse client, and under {installDir}\jazz\buildsystem\buildengine\eclipse\plugins in the Build System Toolkit. It's also in the server. However, I don't recommend modifying its plugin.xml.

> It seems from the information above that this will be both possible and simple.
Unfortunately it is not currently possible to add a build configuration to an existing template. Instead, a new template would need to be defined (either in com.ibm.team.build.common or in a separate plug-in).

Regards,
Nick

Hi Nick,

Thanks for the detailed response.

I recently attempted to get a "Hello World" version of a custom build configuration element running in my RTC 2.0 client but was unsuccessful. I completed steps 1-3 by manually editing the plugin.xml files in {installDir}\jazz\client\eclipse\jazz\build\eclipse\plugins\com.ibm.team.build.ui_2.0.0.I200906081817.jar and {installDir}\jazz\client\eclipse\jazz\build\eclipse\plugins\com.ibm.team.build.common_2.0.0.I200906091854.jar to match the changes you outlined in your post. (I attempted to outline them here but for some reason the forum was not correctly displaying the changes. I have sent a zip with the relevant files to your email address.) I have not moved onto step 4 but I don't think that will affect the client. Am I missing something in my configuration? I do not see an option to add my configuration element to the build definition.

Thank you in advance for any help that you can offer.

-Dave

If you were modifying the plugin jars directly, you need to restart with -clean to ensure it picks up the changes. Eclipse keeps a cache of the extension registry under the configuration directory, so the alternative is to delete everthing under there (well, almost everything -- keep the config.ini file).

If you tried to post the XML snippets here, chances are they got munged. Try checking 'Disable HTML in this post' next time. Be warned that if you use Preview, the preview works but then loses this setting, so you need to re-check it before posting. You can also make that the default in your forum profile settings.

For forum profile settings, use the little human icon, not the "Edit Profile" link at top.

Hm, looks like those settings are not honoured anyway. I have mine turned off, but they're still enabled when making a post.

The -clean option did the trick!

I missed the 'Disable HTML in this post' check box. I'm sure that was my problem.

Thanks for your help.