Helios/Contributing to Helios Build

Contributing to Helios Build

These instructions are for the mechanics of specifying your content for the builder, or aggregater. See Buckminster_Galileo_Builder for using or running the builder itself.

The following steps are required to contribute your content to a Helios build or aggregation:

• Checkout the project org.eclipse.helios.build from /cvsroot/callisto. If you do not have write access to this repository location, contact the webmaster.
• Modify the content of your project/component build model to indicate the features, versions, contact info, and category information for your contribution. Below is an example of a build model:

<?xml version="1.0" encoding="ASCII"?>
<build:Contribution xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:build="http://www.eclipse.org/amalgam/2008/build" label="GMF">
  <contacts name="GMF Build Team" email="anthonyh@ca.ibm.com"/>
  <features id="org.eclipse.gmf.sdk" version="2.3.0.v20091216-1748-7C7N-BLxm_n5Jkwyjggm5crjDAL1" repo="//@repositories.0">
    <category href="helios.build#//@categories.0"/>
  </features>
  <repositories location="http://download.eclipse.org/modeling/gmf/updates/interim/" label="GMF interim"/>
</build:Contribution>

If you're not comfortable modifying EMF-based model instances in a text editor, download the latest DSL Toolkit, as it provides an EMF generated editor for build models. The editor allows each contribution to be maintained in its own file, so when creating a new Contribution within the helios.build model, use the right-click Control... menu to specify a new .build model. Model files can be opened individually, or you can open the main helios.build model to edit your contribution.

Repository elements are maintained within each contribution .build model, as are the list of contacts used to inform contributors of build breakage. A number of repositories may be listed in each contribution, as each feature/version references a specific repository location for installation during the build. Having multiple entries allows for easy switching between repositories.

A feature element has some properties that may require clarification:

• Category: used to indicate the category the feature will appear in when displayed in the p2 UI and update site manifest. Note that categories are specified in the main helios.build model and are not intended to be modified without agreement of the Planning Council. Mapping categories is best done within the build model editor provided by the DSL Toolkit, though can be done within a text editor if you're careful.
• InProduct: a flag to indicate whether or not the feature should be listed in the product file. Nested features need not be included explicitly.
• Repo: the Repository element reference that is used to install the feature from. Note that the Platform team need not set this element as the entire SDK is used as the basis for each build.

Note: Occasionally the your .build file may be changed by the buildmaster, so be sure to use the latest version when making your modifications and submissions. Changes might include insubstantial things like formatting and end-of-line characters (best to leave the same, but no absolute need) but will sometimes contain substantial changes such as the "category number" may change (which is substantial, and must be maintained).

Note: Order matters. If you contribute several features that should be installed into the build target in a particular order, please list them as such in the build model.

Note: Include all platform-specific bundles. Just as the platform provides a delta pack that contains those bundles required for each supported platform, each contributing project to Helios must include a feature that contains each platform-specific bundle, or specify each bundle using the proper entry in their build model. For an example, see the cdt.build model.

Note: For the email addresses, use an actual email address that goes to a person. You can give several, so messages are sent to several people. Do not use a "dev mailing list" at Eclipse, since those require a subscription and the builder that automatically sends emails about broken builds, etc. does not subscribe to the dev mailing lists at Eclipse.

Contributing non-categorized bundles or features to the central repository

It is occasionally desirable to add a feature or bundle to to repository without it being categorized. This might be the case for example if an EPP Package needs a feature or bundle, but that feature or bundle should not (normally) be installed by an end-user.

To do this with a feature, just leave out the category in your .build file. For example

   <features id="org.eclipse.wtp.jee.capabilities.feature" repo="//@repositories.0" version="3.2.0.v2010-Q" >
   </features>

In this case the feature would available or visible only if a user does not select to categorizes the features in the Install UI.

To have an "invisible" bundle in the repository, you can use the 'bundle' element in your .build file. For example,

  <bundles id="org.eclipse.wtp.jee.capabilities" version="" repo="//@repositories.1"/>

In this case, the bundle can not be "seen" by an end-user, in the normal Install UI, but it can be retrieved by EPP builds, or p2 mirror tasks. See WTP_Capabilities_Helios for examples.

Note difference from previous years: In the past, you could contribute a feature whose name ended with '.capabilities' and this was used as a special code word to treat that feature differently; its contents being collected into a special feature that contained "branding" and contributed capability bundles. This "building" by the aggregator was undesirable, was removed in Helios, and caused these '.capabilities' features to effectively be ignored. See bug 299344 and bug 306315 for more details and history. Thus, you can not contribute features whose name ends in '.capabilities' and would either need to change the name, or use the 'bundle' tag to contribute as bundles.

Automatically Updating Your .build File

If you use Athena to publish your builds, you can enable an optional task which will check out, update, and check in your .build file. See Common Build Infrastructure/Publishing/Helios for details.