Modeling Project Releng

This document is directed to the Eclipse Modeling Framework Technologies (EMFT) [1] component owners and was created help them to set up and run their builds. It describes the existing procedures that all EMFT components are required to adopt, describing, for example, how the files should be organized, what the build files are, and the Integration and Milestone release process.

Note that many of the tips and tricks described herein apply to EMF, MDT, and M2T builds as well.

Throughout this document are references to releng (Release Engineering) files which need to be configured along the way. When a project is first starting, these steps are normally skipped until after all the plugin content is in CVS. Then, and only then, the Modeling Project Releng Module can be created for the new project, and builds can begin.

---

Overwhelmed yet?

Well, you're in luck. As of 2006-07-12, there is a new module template which can be used as a starting point. For more on creating and configuring a Modeling Project Releng Module, see Modeling Project Releng Module. Go there, start with that, then come back here for tips and tricks if necessary.

---

This is a live document! We will be enriching it as questions are raised.

Plugin and Feature Files

The contents of your features and plugins directories should mimic what is available in the EMF and UML2 projects. Although this section tries to summarize the important points, "learning by example" is the recommended approach.

Directory Structure

<example>

We will ask you to organize your files as we've done for EMF and UML2. Basically you will need to create the following directory structure for each subdirectory you own under the EMFT module:

OLD Style -- features intermixed			NEW Style -- features separated
Old EMFT project (/cvsroot/technology) emft/[subproject]/ plugins doc tests examples	- or -	New EMFT project (/cvsroot/modeling/) org.eclipse.*/org.eclipse.*.[subproject]/ plugins doc tests examples	Old EMFT project (/cvsroot/technology) emft/[subproject]/ plugins doc tests examples features	- or -	New EMFT project (/cvsroot/modeling/) org.eclipse.*/org.eclipse.*.[subproject]/ plugins doc tests examples features
plugins: the plugins that provide the function the features that include these plugins + the branding plugins for these features the SDK feature (to generate a bundle that includes source + the plugins) doc: the doc plugins (with the build scripts) the features that include these plugins + the branding plugins for these features tests: the test plugins (with the Eclipse test framework artifacts - such as this one) the features that include these plugins + the branding plugins for these features examples: any plugin you want to use as example the features that include these plugins + the branding plugins for these features			plugins: the plugins that provide the function doc: the doc plugins (with the build scripts) tests: the test plugins (with the Eclipse test framework artifacts - such as this one) examples: any plugin you want to use as example features: the SDK feature (to generate a bundle that includes source + the plugins) all main, source, test, doc, and example features

The directories containing features and fragments must be suffixed by -feature and -fragment respectively.

If you want source plugins and features, you will have to create them.

General Recommendations

• Each feature and plugin directory should be also an Eclipse project, containing all the necessary files such as, for example, .project.
• The .project must only refer to builders available to the open-source community. Also, since Eclipse 3M2, it should not refer to other plugin projects. <example>
• We use CVS to backup the files, so...
  • You can, and probably should, use the $Id$ CVS tag. For more details and other tags read the CVS documentation
  • Add a .cvsignore file to keep unnecessary files (such as the output directory) out of CVS. <example>
• Don't add unnecessary files to your plugins and features. If you use a "non-Eclipse standard" file, please ensure that it has a purpose and that that purpose is clear.
• All plugins should provide the following files:
  • META-INF/MANIFEST.MF <example>
  • plugin.xml <example>
  • plugin.properties <example>
  • build.properties <example>
  • about.html <example>
• The build.properties file is extremely important and must be accurate to allow PDE to build your plugins and features. Please review the EMF build.properties files for plugins with code, documentation and branding plugins, and features.

Features <example>

• The PDE build process is based on features, so all your plugins must be referenced by a feature.
• A feature directory can contain the definition of other features and plugins. As you can see in the example, we use this to define "derived" elements, like EMF's SDK feature, source feature and source plugin.
• A feature's build.properties file can specify that the source plugin and feature should be generated. In EMF, this is done in the SDK feature's build.properties.

Qualifiers (1.0.0.qualifier)

• To add qualifiers to features and plugins, you must have 4 pieces set up correctly.
  

1. Plugins <example>

• Append .qualifier as the 4th field of the plugin version in every MANIFEST.MF file.
  

2. Features <example>

• Append .qualifier as the 4th field of the feature version in every feature.xml file.
• Ensure that if you have comments before the <feature> tag, they do NOT include the word "feature". If they do, 1.0.0.qualifier will not be replaced by PDE with the build's timestamp/id. This is documented in bug 129868.
• Change the versions in all plugins included in feature.xml files to 0.0.0. PDE will replace 0.0.0 by the appropriate version during the build.
  

3. Doc

• Ensure that org.eclipse.[subproject].doc/build.xml uses ${pluginVersion}.${forceContextQualifier} instead of ${pluginVersion} or a hard-coded version like 1.0.0. You may need to add a new property. <example>

<property name="pluginVersion" value="1.0.0"/>

• Add these lines to the end of the gather.bin.parts target in org.eclipse.[subproject].doc/build.xml (line break added in path attribute). <example>

<eclipse.versionReplacer
  path="${destination.temp.folder}/org.eclipse.[subproject].doc_\
    ${pluginVersion}.${forceContextQualifier}"
  version="${pluginVersion}.${forceContextQualifier}"/>

4. Releng

• Add the following lines to the create.label.properties target of releng/[subproject]/buildAll.xml. <example>

<property name="forceContextQualifier" value="v${timestamp}"/>

<echo file="${buildDirectory}/label.properties" append="true" >
 forceContextQualifier=${forceContextQualifier}
</echo>

• OPTIONAL: If you would like your features' versions to be suffixed with a dash followed by a random string of letters and numbers, you must also add a line to your build.properties files. Why would you want this? It is apparently calculated from the CVS tags to ensure that the version for the features will change if the source changes in the build.
  

5. Releng

• Add generateFeatureVersionSuffix=true to all build.properties files in every releng/[subproject]/builder/ directory. <example>
• If available, add generateFeatureVersionSuffix=true to any build.properties.template files in releng/[subproject]/templateFiles/. <example>

Tip: due to property file parser limitations in Eclipse, it is recommended that you always leave an empty line at the end of .properties (and .properties.template) files.

• For more on plugin versioning, see http://www.eclipse.org/equinox/documents/plugin-versioning.html.

Branding Icon In About Eclipse Dialog

If you want to use the Eclipse Modeling icon in the About Eclipse dialog, you must reference it correctly in ALL your about.ini files, eg:

• org.eclipse.xsd.doc/about.ini
• org.eclipse.xsd/about.ini
• org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini

# Property "featureImage" contains path to feature image (32x32)
featureImage=modeling32.png

Note that the latest Eclipse Modeling icon is modeling32.png, as decided by bug 154906. You can copy this new icon from here: modeling32.png