What is a Build Style?
At first blush a build style is a set of operations contributed
by a build style provider that operate on iSeries Projects. Typically
a build style will provide push operations and build operations,
although it need not provide these and may provide other operations.
These operations typically show up in the iSeries Project Navigator context
menu under the heading "Remote Actions". These operations are standard
eclipse action contributions.
The build styles provided by IBM implement a "push selected" operation
that pushes a particular resource and its children to a host system whether
they have been modified or not and a "push changes" operation that pushes
any additions and changes made to resources in a project. There is
also a "submit build" operation for each of the two IBM-supplied build
styles. One submits a command and the other submits a "compile and
run" for two CL programs that the user can code to build the project.
Each iSeries project has its own build style, which can be configured
using the properties page of the project. The workspace has a "default"
build style – selectable by the user – that can be configured with defaults
for each new project in the workspace. A build style provider contributes
the configuration dialogs for both of these and is responsible for storing
any resulting configuration data. The underlying build style support
takes care of presenting these dialogs to the user and oversees the selection
of a build style for a project.
So, up to this point, a build style consists of some operations that
show up in a menu and (potentially) a couple of dialogs accessible from
the properties page of a project and the preference page of the workspace.
In addition, a build style can be selected and configured when a project
is created using the “New iSeries Project” wizard. The rest of a
build style is hidden -- it is the code that defines and implements these
operations.
Why do I want to build one of these?
Build styles are meant to provide a means for IBM and other tool providers
to incorporate the eclipse workbench tools and resource management and
the iSeries Project Model into their existing tools. Not everyone
needs to write a build style, but you might consider it if you have any
of the following requirements:
· You need to track files and other resources as they are uploaded
to a host
· You need to interface to an existing build engine on the host
that you support.
· You want to provide operations to your users other than the
ones IBM supplies
· You want to drop IBM's support and supply your own
The build styles IBM provides are plugged into the workbench just as
any other provider. As such, they can be removed and new ones supplied.
How do I start?
You have to do three things to provide a build style:
(1) Define the build style in your plug-in using the plugin.xml file.
(2) Define the client code to support the actions that you define in
your plug-in.
(3) Write your server code to interface to your build engine and your
client-side actions.
Let's examine these more closely.
Defining your plugin.xml
Particular XML fragments in the plugin.xml file define a build style.
A build style is relatively simple -- it has the following attributes:
· A name that is shown to the workbench user whenever a build
style needs to be selected.
· A unique ID that will distinguish it from any other build
style installed in the workbench
· A priority that is used to determine the initial default for
the workbench and for ordering all the installed build styles in a list
· A class that can be instantiated by the workbench to provide
other information about the build style and which controls the gathering
of information for a particular project.
In addition to the build style itself, you need to define actions to
be taken by the build style. These are normal eclipse object actions
that are provided objects in the model provided by the com.ibm.etools.iseries.perspectives
plug-in. You should filter these actions by the type of object in
the model you want to operate on and also by the ActiveBuildStyle persistent
property of the project. Filtering actions by this property ensures
that your actions show up only on projects that have your build style.
Lastly, if you want to use the properties model of the iSeries Project
model to provide persistence for your attributes of your build style you
need to define these properties. Here is another example that shows
the properties defined by the IBM supplied build styles in com.ibm.etools.iseries.remotebuild.styles
These properties are implicitly qualified by the plugin id and when
you use them in the code you need to prefix them by the plugin id.
For example "BuildCommand" is really "com.ibm.etools.iseries.remotebuild.styles.BuildCommand".
Defining your client code
The code provided by your plugin must define the operations necessary to
carry out the actions you defined in your plugin.xml. You have to
implement these operations yourself, but IBM provides a set of APIs and
frameworks for you to use in building your build style. These APIs
and frameworks are defined in the package com.ibm.etools.iseries.remotebuild.
IBM uses these APIs and frameworks to build its own build styles.
Defining the server code
As stated earlier a build style will usually provide push and build operations.
Push operations can be done entirely from the client side -- although fancy
encodings or high-performance, high-volume pushes may require server assistance.
Only the simplest build operations, however, can be accomplished without
any server code. Indeed, IBM provided the implementation for this
simplest of build styles in the first release of WDS based on eclipse.
This style provided even less function than the current "Command" build
style of this release. It submitted a command and did no error feedback
or job tracking. It was assumed that the project had pushed all its
resources.
Anything more complex than a simple command submission requires a build
style server on the host system. IBM provides two build style servers
to complement the two build styles it provides in WDSc. Any provider
of a build style will have to write their own build style server to "catch"
build requests from the client. IBM provides an API for assisting
the development of build style servers. This API is located in the
service program QDEVTOOLS/QRBUTIL. This program provides API for
build style servers written either in C (the C API) or in other languages
such as CL or RPG (the Standard API). Both APIs accomplish the same
thing. The C API is more convenient to use with a build style servers
written in C because it understands null-terminated strings and provides
return values allocated on the C heap. Build style servers may be
written in Java as well, and may find it convenient to use the Standard
API, PCML, and the AS400 Toolbox for Java classes.