Jump to: navigation, search

Difference between revisions of "Common Build Procedures, Tips + Tricks"

Redirect page
m (EMFT Procedures moved to Common Build Procedures, Tips + Tricks: useful for more than just EMFT builds now)
(page moved)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
This document is directed to the '''[[Eclipse Modeling Framework Technologies]]''' ('''EMFT''') [http://www.eclipse.org/emft/] technology project committers and was created help them to set up and work on their projects. It describes the existing procedures that all EMFT subprojects are supposed to adopt, describing, for example, how the files should be organized, what the build files are, and the Integration and Milestone release process.
+
#REDIRECT [[Modeling Project Releng]]
 
+
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 [[EMFT Releng Module]] can be created for the new project, and builds can begin.
+
 
+
 
+
----
+
 
+
 
+
<blockquote>
+
'''''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 an EMFT Releng Module, see [[EMFT Releng Module]]. Go there, start with that, then come back here for tips and tricks if necessary.
+
</blockquote>
+
 
+
 
+
----
+
 
+
 
+
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 [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/ EMF] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.uml2/ UML2] projects. Although this section tries to summarize the important points, "learning by example" is the recommended approach.
+
 
+
 
+
===Directory Structure===
+
 
+
<span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf example]></span>
+
 
+
We will ask you to organize your files as we've done for [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/ EMF] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.uml2/ UML2]. Basically you will need to create the following directory structure for each subdirectory you own under the EMFT module:
+
 
+
<table cellpadding="2" cellspacing="2" border="1"><tr><td colspan="3"><b style="color:darkred">OLD Style -- features intermixed</b></td><td colspan="3"><b style="color:darkgreen">NEW Style -- features separated</b></td></tr>
+
<tr valign="top"><td>
+
Old EMFT project (/cvsroot/technology)
+
emft/''[subproject]''/
+
  plugins
+
  doc
+
  tests
+
  examples
+
+
</td><td><br/><br/> - or -
+
</td><td>
+
New EMFT project (/cvsroot/modeling/)
+
org.eclipse.*/org.eclipse.*.''[subproject]''/
+
  plugins
+
  doc
+
  tests
+
  examples
+
+
</td><td>
+
Old EMFT project (/cvsroot/technology)
+
emft/''[subproject]''/
+
  plugins
+
  doc
+
  tests
+
  examples
+
  features
+
</td><td><br/><br/> - or -
+
</td><td>
+
New EMFT project (/cvsroot/modeling/)
+
org.eclipse.*/org.eclipse.*.''[subproject]''/
+
  plugins
+
  doc
+
  tests
+
  examples
+
  features
+
</td></tr>
+
<tr valign="top"><td colspan="3">
+
# 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  [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup 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
+
</td><td colspan="3">
+
# 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  [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/tests/org.eclipse.emf.test.core/test.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup 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
+
 
+
</td></tr></table>
+
 
+
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 [[#Source Plugin & Feature <example>|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. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.project?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* 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 [http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Keyword_substitution CVS documentation]
+
** Add a ''.cvsignore'' file to keep unnecessary files (such as the output directory) out of CVS. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/.cvsignore?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* 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 <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** plugin.xml <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/plugin.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** plugin.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/plugin.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** build.properties <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
** about.html <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/about.html?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* 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 <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature example]></span>====
+
 
+
* 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 [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature 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 [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature/org.eclipse.emf.sdk/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup 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.<br />
+
: 1. Plugins <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm/META-INF/MANIFEST.MF example]></span>
+
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the plugin version in every <tt style="color: DarkGreen">MANIFEST.MF</tt> file. <br />
+
: 2. Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/feature.xml example]></span>
+
::* Append <tt style="color: DarkGreen">.qualifier</tt> as the 4th field of the feature version in every <tt style="color: DarkGreen">feature.xml</tt> file.
+
::* Ensure that if you have comments before the <tt style="color: DarkGreen"><feature></tt> tag, they do NOT include the word "feature". If they do, <tt style="color: DarkGreen">1.0.0.qualifier</tt> will not be replaced by PDE with the build's timestamp/id. This is documented in '''[https://bugs.eclipse.org/bugs/show_bug.cgi?id=129868 bug 129868]'''.
+
::* Change the versions in all plugins included in <tt style="color: DarkGreen">feature.xml</tt> files to <tt style="color: DarkGreen">0.0.0</tt>. PDE will replace <tt style="color: DarkGreen">0.0.0</tt> by the appropriate version during the build. <br />
+
: 3. Doc
+
::* Ensure that <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> uses <tt style="color: DarkGreen">${pluginVersion}.${forceContextQualifier}</tt> instead of <tt style="color: DarkGreen">${pluginVersion}</tt> or a hard-coded version like <tt style="color: DarkGreen">1.0.0</tt>. You may need to add a new property. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml example]></span>
+
 
+
<property name="pluginVersion" value="1.0.0"/>
+
 
+
::* Add these lines to the end of the <tt style="color: DarkGreen">gather.bin.parts</tt> target in <tt style="color: DarkGreen">org.eclipse.''[subproject]''.doc/build.xml</tt> (line break added in path attribute). <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml example]></span>
+
 
+
<eclipse.versionReplacer
+
  path="${destination.temp.folder}/org.eclipse.''[subproject]''.doc_\
+
    ${pluginVersion}.${forceContextQualifier}"
+
  version="${pluginVersion}.${forceContextQualifier}"/>
+
 
+
: 4. Releng
+
::* Add the following lines to the <tt style="color: DarkGreen">create.label.properties</tt> target of <tt style="color: DarkGreen">releng/''[subproject]''/buildAll.xml</tt>. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/eodm/buildAll.xml example]></span>
+
 
+
<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 <tt style="color: DarkGreen">build.properties</tt> 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.<br />
+
: 5. Releng
+
::* Add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to all <tt style="color: DarkGreen">build.properties</tt> files in every <tt style="color: DarkGreen">releng/''[subproject]''/builder/</tt> directory. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/eodm/builder/sdk/build.properties example]></span>
+
::* If available, add <tt style="color: DarkGreen">generateFeatureVersionSuffix=true</tt> to any <tt style="color: DarkGreen">build.properties.template</tt> files in <tt style="color: DarkGreen">releng/''[subproject]''/templateFiles/</tt>. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/templateFiles/build.properties.template example]></span>
+
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:
+
 
+
* [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.xsd/doc/org.eclipse.xsd.doc/about.ini org.eclipse.xsd.doc/about.ini]
+
* [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.xsd/plugins/org.eclipse.xsd/about.ini org.eclipse.xsd/about.ini]
+
* [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.xsd/features/org.eclipse.xsd.sdk-feature/sourceTemplatePlugin/about.ini?root=Tools_Project&view=co 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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=154906 bug 154906]. You can copy this new icon from here:  [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.query/plugins/org.eclipse.emf.query.sdk-feature/modeling32.png?revision=1.1&root=Modeling_Project modeling32.png]
+
 
+
===Branding Plugin <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf example]></span>===
+
 
+
* The "branding plugin" is the plugin that provides specific files to describe a feature - check the example to see what these files are.
+
* It is recommended that the branding plugin be given the same name and id as the feature it describes.
+
* The "branding plugin" may also contain source, so you don't need to create an additional plugin just to hold the branding files.
+
 
+
===Core Plugins & Features <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore example]></span>===
+
 
+
====Core Plugins====
+
 
+
For plugins with code:
+
 
+
* The EMF artifacts and model specifications (XML schema, for example) should be located in a ''models'' directory in the root of the plugin. Don't forget to include the genmodel to allow users to regenerate your code.
+
* DO commit all generated code. This makes it easier to run your plugin from the workspace.
+
* The source files should be placed in "source folders" and each "source folder" should have a different "output folder".
+
* The plugins with code should be deployed as jarred plugins. In order to tip the PDE build to jar a plugin, you need to set the MANIFEST.MF's ''Bundle-ClassPath'' attribute to ''.'' and use ''.'' in the ''build.properties'' file. As an example, look at the ecore's [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/META-INF/MANIFEST.MF?rev=HEAD&content-type=text/vnd.viewcvs-markup manifest] and [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup build.properties] mentally replacing ''ecore.jar'' by ''.''.
+
Right now you are probably asking yourself why the ecore files are declaring a jar instead of using ''.''. To make a long story short, this is necessary for EMF to bootstrap itself during development (required when you use EMF to develop EMF). When developing, we can easily zip the contents of the output folder into the appropriate jar and restart Eclipse. Our build "fixes" the files before the plugins are packaged.
+
Btw, to jar your plugin, you will also need to add ''unpack="false"'' to the plugin reference in your feature. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature/feature.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
* Almost all files should have a copyright. This is what is used for the Java files in EMF (please check the other types of files in the example):
+
 
+
<pre>
+
/**
+
* &lt;copyright>
+
*
+
* Copyright (c) 2005 IBM Corporation and others.
+
* All rights reserved.  This program and the accompanying materials
+
* are made available under the terms of the Eclipse Public License v1.0
+
* which accompanies this distribution, and is available at
+
* http://www.eclipse.org/legal/epl-v10.html
+
*
+
* Contributors:
+
*  IBM - Initial API and implementation
+
*
+
* &lt;/copyright>
+
*/
+
</pre>
+
 
+
* The ''META-INF/MANIFEST.MF'' must end with an empty line. Also, don't forget to add the following line to the manifest to ensure the plugin classes are properly initialized:
+
+
Eclipse-LazyStart: true
+
* The ''.classpath'' files should only contain references to the JDK and PDE container and the definition of the source and output folders.
+
* In order to ensure that your ''plugin.properties'' files can be translated, you will need to add the following "directives" to them. All strings after a given directive are supposed to conform to its rules:
+
{| cellpadding="2" border="1" style="border: 1px black"
+
| valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_ALL</tt>
+
| <nowiki>Each string is assumed to be processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes '').</nowiki>
+
|-
+
| valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_NONE</tt>
+
| All strings are assumed to NOT be processed by the MessageFormat class (single quote must be coded as 1 single quote ').
+
|-
+
| valign="top" | <tt style="color: DarkGreen">NLS_MESSAGEFORMAT_VAR</tt>
+
| <nowiki>Strings which contain replacement variables are processed by the MessageFormat class (single quote must be coded as 2 consecutive single quotes ''). Strings which do NOT contain replacement variables are NOT processed by the MessageFormat class (single quote must be coded as 1 single quote ').</nowiki>
+
|}
+
* Add a schema for each extension point you define in your plugin. <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf.ecore/schema/generated_package.exsd?rev=HEAD&content-type=text/vnd.viewcvs-markup example]></span>
+
 
+
====Core Features====
+
 
+
''This is a stub. Contribute to this wiki by adding content here.''
+
 
+
 
+
===Documentation Plugin & Feature <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc example]></span>===
+
 
+
* While the PDE build is able to automatically create the Ant build script for the plugins with source code, you will need to hard code and maintain the script for the documentation plugins. The easiest way of creating the script (called ''build.xml'') is:
+
*# After adding all the files to the plugin directory and configuring the ''build.properties'' file, right click the ''plugin.xml'' file and select ''PDE Tools->Create Ant Build File''.
+
*# Open the ''build.xml'' file and delete the tasks in the ''gather.bin.parts''<nowiki>; target.</nowiki>
+
*# In the ''build.jars'', use the ''zip'' ant tasks to zip up the content of the plugin - this is required since Eclipse expects the documentation files to be in an archive file.
+
*# Open the ''build.properties'' editor and select the "Custom Build" check box at the top of the page
+
*# Every time you start code a new release, you will need to manually update this build script. See the "[[#Release Process|Release Process]]" section for more details on new releases.
+
 
+
====Javadoc <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc example]></span>====
+
 
+
* Creating javadoc in your plugin requires a number of files &amp; folders:
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.xml build.xml] (including all source), or<br />[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/jet/doc/org.eclipse.jet.doc/build.xml build.xml] (excluding internal packages &amp; classes)
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/plugin.xml plugin.xml]
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/toc.xml toc.xml] (table of contents)
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build.properties build.properties]
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/antJavadoc.sh build/antJavadoc.sh]
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/javadoc.xml.template build/javadoc.xml.template]
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/build/overview.html build/overview.html]
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/images/ images/] (folder, ref'd in build.xml#build.jars)
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/references/ references/] (folder, ref'd in build.xml#build.jars)
+
*# [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/tutorials/ tutorials/] (folder, ref'd in build.xml#build.jars)
+
<br />
+
* Note that unless you have images, references, or tutorials at the time you're creating these files, you'll have to toss a placeholder into them so they won't be pruned (ignored) when extracting from CVS. A simple (blank) [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/doc/org.eclipse.eodm.doc/references/.cvsignore .cvsignore] file will do nicely.
+
 
+
====Javadoc Indexed By Eclipse Help====
+
 
+
To get Eclipse to index your javadoc in the Help system, you must revise the following files (see also [https://bugs.eclipse.org/bugs/show_bug.cgi?id=142558 bug 142558]):
+
 
+
1. Specify where extra topics_*.xml files are attached to the main table of contents entry: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/toc.xml toc.xml]
+
<topic label="Reference">
+
  <link toc="'''topics_Reference.xml'''"/>
+
</topic>
+
 
+
2. Specify which files to include in the doc plugin (custom build script, not PDE-generated): [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/build.xml build.xml]
+
  <target name="gather.bin.parts" depends="init" if="destination.temp.folder">
+
    ...
+
    <fileset dir="${build.result.folder}"
+
      includes="about.*,eclipse*.gif,eclipse*.png,eclipse*.jpg,plugin.*,toc*.xml,'''topics_*.xml''',doc.zip,index/**,META-INF/**"/>
+
    ...
+
  </target>
+
 
+
3. '''UPDATED''' Configure [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/build/javadoc.xml.template javadoc.xml.template], if required. Doclet is no longer used; instead, generation is done simply in [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/doc/org.eclipse.emf.doc/build/antJavadoc.sh?content-type=text%2Fplain antJavadoc.sh]
+
<target name="javadoc" depends="extractPlatformJavadoc">
+
...
+
<javadoc ...>
+
  <arg value="-J-Xmx256m"/>
+
  ...
+
</javadoc>
+
...
+
 
+
4. Define extension points to allow extra topics_*.xml files to be seen in Eclipse Help: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/doc/org.eclipse.emf.doc/plugin.xml plugin.xml]
+
  &lt;!-- ============================= -->
+
  &lt;!-- Define TOCs                  -->
+
  &lt;!-- ============================= -->
+
+
  <extension point="org.eclipse.help.toc">
+
    <toc file="'''topics_Reference.xml'''" />
+
  </extension>
+
+
  &lt;!-- ============================= -->
+
  &lt;!-- Define Javadoc locations      -->
+
  &lt;!-- ============================= -->
+
  <extension point="org.eclipse.pde.core.javadoc">
+
      <javadoc path="'''references/javadoc'''"> &lt;!-- defaults to reference/api -->
+
      </javadoc>
+
  </extension>
+
 
+
===Tests Plugin & Feature===
+
 
+
''This is a stub. Contribute to this wiki by adding content here.''
+
 
+
 
+
===Examples Plugin & Feature===
+
 
+
''This is a stub. Contribute to this wiki by adding content here.''
+
 
+
 
+
===SDK Feature===
+
 
+
''This is a stub. Contribute to this wiki by adding content here.''
+
 
+
 
+
===Source Plugin &amp; Feature <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature example]></span>===
+
 
+
* To create a source plugin and feature, you must have '''5''' pieces set up correctly.<br />
+
: 1. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/feature.xml example]></span>
+
:: This will define which *src.zip files will be created - one per plugin include in the feature. If you want source for your examples, do the same in your ''[subproject]''.examples-feature.
+
 
+
:: [update] '''NOTE:''' you must include your branding plugin (eg., org.eclipse.net4j) in your branding feature (eg., [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/net4j/plugins/org.eclipse.net4j-feature/feature.xml org.eclipse.net4j-feature/feature.xml]), even if it contains NO source, in order to properly suppress unpacking src/* in the .source plugin. Ensure that you've set that plugin to be unpack="false":
+
 
+
<plugin
+
  id="org.eclipse.net4j"
+
  download-size="0"
+
  install-size="0"
+
  version="0.0.0"
+
  '''unpack="false"'''/>
+
 
+
: 2. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplateFeature/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/sourceTemplateFeature example]></span>
+
: 3. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">sourceTemplatePlugin/*</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/sourceTemplatePlugin example]></span>
+
:: These define the contents that will go into your source feature(s) and plugin(s).
+
: 4. org.eclipse.''[subproject]''-feature/<tt style="color: DarkGreen">org.eclipse.''[subproject]''.sdk/feature.xml</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm-feature/org.eclipse.eodm.sdk/feature.xml example]></span>
+
+
<includes
+
  id="org.eclipse.''[subproject]''.source"
+
  version="1.0.0"
+
  match="[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html%3Fresultof%3D%22compatible%22%20%22matching%20rule%22 compatible]"/>
+
 
+
:: This connects your SDK to your .source plugins/features so that they will be included in the SDK. For more on match rules, see [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/feature_manifest.html%3Fresultof%3D%22matching%20rule%22 Matching Rules].
+
: 5. org.eclipse.''[subproject]''.*/<tt style="color: DarkGreen">build.properties</tt> (for '''ALL''' applicable plugins) <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm.editor/build.properties example]></span>
+
 
+
<blockquote>
+
<table>
+
<tr><td>
+
====Bundle-ClassPath With Dot====
+
<b style="color: DarkGreen">RECOMMENDED:</b> ''jarred plugins w/ org/eclipse/.../*.class files''
+
</td>
+
<td>&#160; &#160;</td><td>
+
====Bundle-ClassPath With Jar====
+
<b style="color: Orange">NOT RECOMMENDED:</b> ''jarred plugins with nested jars''
+
</td></tr>
+
<tr><td>
+
# NLS_MESSAGEFORMAT_VAR
+
source.. = src/
+
output.. = bin/
+
 
+
src.includes = about.html
+
bin.includes = plugin.xml,\
+
                plugin.properties,\
+
                icons/,\
+
                .,\
+
                META-INF/
+
 
+
Use <tt style="color: DarkGreen">.</tt> instead of a jar name; repeat in MANIFEST.MF files:
+
+
Bundle-ClassPath: .
+
</td><td>&#160; &#160;</td><td>
+
# NLS_MESSAGEFORMAT_VAR
+
source.''[Bundle-ClassPath]'' = src/
+
output.''[Bundle-ClassPath]'' = bin/
+
 
+
src.includes = about.html
+
bin.includes = plugin.xml,\
+
                plugin.properties,\
+
                icons/,\
+
                ''[Bundle-ClassPath]'',\
+
                META-INF/
+
 
+
Note that <tt style="color: DarkGreen">''[Bundle-ClassPath]''</tt> is the jar name defined in the matching [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/eodm/plugins/org.eclipse.eodm.editor/META-INF/MANIFEST.MF MANIFEST.MF], such as:
+
+
Bundle-ClassPath: eodmeditor.jar
+
</td></tr></table>
+
</blockquote>
+
 
+
These define what gets packaged in the *src.zip files. You should NOT use <tt style="color: DarkGreen">src.includes = src/</tt> unless you want your source plugin to include BOTH a *src.zip (containing *.java source files) and the unpacked *.java source files themselves.
+
 
+
==== Multiple Namespaces ====
+
 
+
* If you want to contribute sources to your SDK, you must create a source plugin and feature for every feature that will contribute source. If you only have one main feature, eg, org.eclipse.emf.''[subproject]''-feature, there will be one src.zip created for every plugin listed in that feature's feature.xml. If you have more than one, as in the case with [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/transaction/plugins/ org.eclipse.emf.transaction], containing both org.eclipse.emf.transaction-feature and org.eclipse.emf.workspace-feature, each must contain its own sourceTemplateFeature and sourceTemplatePlugin. ''(???)''
+
 
+
* You can also use the generate.feature directive in your SDK's  [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/transaction/plugins/org.eclipse.emf.transaction-feature/org.eclipse.emf.transaction.sdk/build.properties build.properties], if you have source for more than one namespace. ''(???)''
+
 
+
==Building Zips & Jars==
+
 
+
* We use the Eclipse build process which relies on PDE. See this [http://www.eclipse.org/articles/Article-PDE-Automation/automation.html article] if you are interested in the details. It also covers the JUnit automated tests that can be run during the build.
+
* You can use PDE to configure what will appear in your zips.
+
 
+
 
+
===Incubation Status===
+
 
+
In order to comply with [http://www.eclipse.org/projects/dev_process/incubation-conforming.php Eclipse.org's Incubation Rules], EMFT components must adhere to these 3 rules.
+
 
+
For example, here are the changes required to make EMF Compare compliant: [http://www.eclipse.org/modeling/emf/searchcvs.php?q=197820+file%3A+%2Fcvsroot%2Fmodeling%2Forg.eclipse.emf%2Forg.eclipse.emf.compare&project=0&fullpath Search CVS results]
+
 
+
: 1. ''All downloadable zip files for builds and milestones must include the word <code>incubation</code> in the filename. For example, <code>emft-compare-SDK-incubation-N200708031343.zip</code>. The jar files in the download zip file are NOT required ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=178944 bug 178944]) to contain the word <code>incubation</code> in the filename.''
+
 
+
: To change your build to provide <code>-incubation</code> in the zip names, search your .releng project for "<code>.zip</code>" and fix all files accordingly. [http://www.eclipse.org/modeling/emf/searchcvs.php?q=197820+file%3A+%2Fcvsroot%2Fmodeling%2Forg.eclipse.emf%2Forg.eclipse.emf.compare.releng&project=0&fullpath Releng Example]
+
 
+
::* Building: customTargets.xml (all versions of this file)
+
::* Testing: relengbuildgtk.sh, testManifest.xml, testManifest.xml.template, testing.properties, readme.html
+
::* Promoting: promoteToEclipse.*.properties
+
 
+
: 2. ''All <code>Bundle-Name</code>s must include the world <code>incubation</code>. Note that <code>Bundle-SymbolicName</code>s should not include <code>incubation</code> because the Bundle-SymbolicName is a technical namespace, not a user namespace. For example, <code>Bundle-Name: Foo Plug-in (Incubation)</code>.''
+
 
+
: Update all your component's MANIFEST.MF and/or plugin.properties files, including tests, examples, and doc (which file to edit depends on where "Bundle-Name" strings are located). [http://www.eclipse.org/modeling/emf/searchcvs.php?q=197820+file%3A+%2Fcvsroot%2Fmodeling%2Forg.eclipse.emf%2Forg.eclipse.emf.compare%2F%25%2FMANIFEST.MF&project=0&fullpath MANIFEST.MF Example]
+
 
+
Bundle-Name: %pluginName '''(Incubation)''' [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare/plugins/org.eclipse.emf.compare/META-INF/MANIFEST.MF?root=Modeling_Project&view=co]
+
 
+
: 3. ''The names for update manager features must include the word <code>incubation</code>. For example, <code>EMF Compare Documentation (Incubation)</code>.''
+
 
+
: Update all your component's feature.xml and/or feature.properties files, including tests, examples, doc, and SDK features. Add <code> (Incubation)</code> to both the feature label and the feature description. [http://www.eclipse.org/modeling/emf/searchcvs.php?q=197820+file%3A+%2Fcvsroot%2Fmodeling%2Forg.eclipse.emf%2Forg.eclipse.emf.compare%2F%25%2Ffeature.&project=0&fullpath Feature.* Example]
+
 
+
<feature
+
      id="org.eclipse.emf.compare.sdk"
+
      label="EMF Compare SDK '''(Incubation)'''"
+
      version="0.7.0.qualifier"
+
      provider-name="Eclipse.org">
+
 
+
  <description>
+
      EMF Compare SDK includes runtime, source, and documentation '''(Incubation)'''
+
  </description> [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare/plugins/org.eclipse.emf.compare.sdk-feature/feature.xml?root=Modeling_Project&view=co]
+
 
+
When a project exits incubation, above changes should be reversed to remove the <code>incubation</code> identifiers from features, plugins, and zip file names.
+
 
+
===Customizing Zip Bundles===
+
 
+
In the event that you have plugins or features that PDE will not normally bundle together, such as .ui plugins in the runtime zip, you will need to adjust the way PDE behaves in order to ensure all your plugins/features appear in your zips as you need them. If you need a custom zip, like EMF has for Models or Standalone, this is also how you can accomplish this.
+
 
+
There's two ways to customize what gets put into a zip bundle by PDE: the correct way (a) and the shortcut (b)
+
 
+
====Option A====
+
 
+
The first method involves creating a feature which sets up the included features/plugins that have to be in there, as with .sdk features in the EMFT subprojects (ocl, query, validation, transaction). See details in [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft CVS]. An example of this is [http://dev.eclipse.org/viewcvs/indextools.cgi/org.eclipse.emf/plugins/org.eclipse.emf-feature/org.eclipse.emf.sdk org.eclipse.emf-feature/org.eclipse.emf.sdk]. It is nested (rather than being its own <tt style="color: DarkGreen">org.eclipse.emf.''[subproject]''.''[bundlename]''-feature</tt>) for cosmetic reasons (it looks in the file system).
+
 
+
When creating a new <tt style="color: DarkGreen">org.eclipse.emf.''[subproject]''-feature/org.eclipse.emf.''[subproject]''.''[bundlename]''</tt> (or <tt style="color: DarkGreen">org.eclipse.emf.''[subproject]''.''[bundlename]''-feature</tt>), you will need to ensure it's properly connected to the build harness in 3 ways:
+
 
+
: 1. First, you'll need a folder under your builder/ directory for the feature build, such as:
+
org.eclipse.emft/releng/validation/builder/sdk/
+
Into this folder must go a <tt style="color: DarkGreen">customTargets.xml</tt> and a <tt style="color: DarkGreen">build.properties</tt> file. Then make sure that <tt style="color: DarkGreen">customTargets.xml</tt> refers to the feature correctly, as in [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/validation/builder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml <tt style="color: DarkGreen">customTargets.xml</tt>]. (Search for "sdk" on lines 9, 20, 187.)
+
 
+
: 2. Then, the <tt style="color: DarkGreen">buildAll.xml</tt> script must be told how to build the new zip, eg, [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/validation/buildAll.xml?rev=HEAD&content-type=text/xml <tt style="color: DarkGreen">buildAll.xml</tt>] (line 139):
+
<target name="buildAll" depends="init">
+
  <ant antfile="build.xml" target="main">
+
    <property name="component" value="builder/sdk"/>
+
  </ant>
+
  ...
+
</target>
+
 
+
: 3. And finally, you need to add the custom feature to the mapfile &amp; mapfile template, since it won't be generated by PDE into the mapfile automagically. Examples: [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/validation/maps/validation.map?rev=HEAD&content-type=text/plain <tt style="color: DarkGreen">org.eclipse.emft/releng/validation/maps/validation.map</tt>]<br />[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/validation/templateFiles/validation.map.template?rev=HEAD&content-type=text/plain <tt style="color: DarkGreen">org.eclipse.emft/releng/validation/templateFiles/validation.map.template</tt>]<br /><br /> Add an entry such as (line break added for clarity):<br /><tt style="color: DarkGreen">feature@org.eclipse.emf.validation.sdk=@cvsTag@,@cvsRoot1@,,org.eclipse.emft/validation/plugins/ org.eclipse.emf.validation-feature/org.eclipse.emf.validation.sdk</tt><br /><br />
+
 
+
====Option B (or adding an optional dependency)====
+
 
+
The second method is faster (and, arguably, more hackish). This is also a valid method for adding an optional dependency, like for example adding optional support for OCL.
+
 
+
Instead of one feature per zip, as above, you can have custom instructions/rules in the <tt style="color: DarkGreen">buildAll.xml</tt> script which allow you to copy extra files that would normally be excluded from the zip to clean up missing content. These instructions are kept in one place (ie., only one ant script), so maintenance is easier, but this solution should only be used to add files to existing bundles, not to create new, custom ones.
+
 
+
For example, there's a [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/validation/plugins <tt style="color: DarkGreen">validation.ocl</tt>] plugin which must be included in the [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/validation/plugins <tt style="color: DarkGreen">validation</tt>] runtime, but since the <tt style="color: DarkGreen">validation-feature</tt> makes no mention of it, it's excluded. So, to work around this, once the SDK is built, copy the <tt style="color: DarkGreen">validaton.ocl</tt> plugin &amp; feature from the SDK zip to the runtime zip after its assembly. This is done in the [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/validation/buildAll.xml?rev=HEAD&content-type=text/xml <tt style="color: DarkGreen">org.eclipse.emft/releng/validation/buildAll.xml</tt>] script:
+
<target name="buildAll" depends="init">
+
  <ant antfile="build.xml" target="main">
+
    <property name="component" value="builder/sdk" />
+
  </ant>
+
 
+
  <ant antfile="build.xml" target="main">
+
    <property name="component" value="builder/runtime" />
+
  </ant>
+
  ...
+
 
+
  &lt;!-- add .ocl feature + plugin from SDK to runtime -->
+
  <zip update="true"
+
    destfile="${buildDirectory}/${buildLabel}/emft-${subprojectName}-runtime-${buildAlias}.zip">
+
    <zipfileset
+
      src="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip">
+
      <include name="**/org.eclipse.emf.${subprojectName}.ocl*"/>
+
      <include name="**/org.eclipse.emf.${subprojectName}.ocl*/*"/>
+
    </zipfileset>
+
  </zip>
+
  ...
+
</target>
+
 
+
Bear in mind that you must ensure that everything you need to compile is available. You will need to edit all the [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/query/builder/sdk/customTargets.xml <tt style="color: DarkGreen">customTargets.xml</tt>] files that are used to build code which depends on the new reqiurement. See target "postSetup".
+
 
+
<ant target="getDependency" antfile="${getDeps.xml}">
+
    <property name="url" value="${oclURL}"/>
+
    <property name="file" value="${oclFile}"/>
+
    <property name="isUnpackedFile" value="${buildDirectory}/plugins/org.eclipse.emf.ocl/plugin.xml"/>
+
</ant>
+
 
+
If your tests require addtional plugins in order to compile or run, be sure to add them to your [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/transaction/builder/tests/scripts/test.xml <tt style="color: DarkGreen">test.xml</tt>] file. See target "setup".
+
 
+
===Using Third Party Jars===
+
 
+
You want to use third party jars during your build, but don't want to ship them due to licensing or other reasons? Here's how:
+
 
+
* First, add the jars to your build or test environment. [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/cdo/builder/tests/customTargets.xml?rev=HEAD&content-type=text/xml org.eclipse.emft/releng/cdo/builder/tests/customTargets.xml]
+
 
+
<target name="postFetch">
+
  <replace dir="${buildDirectory}/plugins" value="${timestamp}" token="@buildid@">
+
    <include name="**/about.mappings" />
+
  </replace>
+
+
  <echo message="Copy hsqldb.jar into plugins/org.eclipse.emf.cdo.jdbc.hsqldb/lib ..."/>
+
  <copy
+
    todir="${buildDirectory}/plugins/org.eclipse.emf.cdo.jdbc.hsqldb/lib"
+
    file="${buildDirectory}/../../../../../../../downloads/hsqldb.jar" failonerror="true"/>
+
+
  <echo message="Copy mysql-connector-java-3.1.12-bin.jar into plugins/org.eclipse.emf.cdo.jdbc.mysql/lib ..."/>
+
  <copy
+
    todir="${buildDirectory}/plugins/org.eclipse.emf.cdo.jdbc.mysql/lib"
+
    file="${buildDirectory}/../../../../../../../downloads/mysql-connector-java-3.1.12-bin.jar" failonerror="true"/>
+
</target>
+
 
+
* Then, remove the jars from your SDK, Runtime, or test zips if they were added by PDE. [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/cdo/buildAll.xml?rev=HEAD&content-type=text/xml org.eclipse.emft/releng/cdo/buildAll.xml]
+
 
+
<echo message="Repack zip w/ exclusion filter"/>
+
<zip destfile="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip_" update="true">
+
  <zipfileset src="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip">
+
    <exclude name="**/lib/hsqldb.jar"/>
+
    <exclude name="**/lib/mysql-connector-java-3.1.12-bin.jar"/>
+
  </zipfileset>
+
</zip>
+
+
<echo message="Remove orig. zip and rename new one"/>
+
<delete file="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip"/>
+
<move file="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip_"
+
  tofile="${buildDirectory}/${buildLabel}/emft-${subprojectName}-SDK-${buildAlias}.zip"/>
+
 
+
===Standalone Zip Bundles===
+
 
+
Building a Standalone Zip allows you to provide code for use outside Eclipse. This is not very well documented (yet), but to get a feel for how to build a Standalone bundle, have a look at the following EMF examples:
+
 
+
'''Build'''
+
 
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/zips/standalone/ org.eclipse.emf.releng.build/zips/standalone/]
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/buildAll.xml?rev=HEAD&content-type=text/xml org.eclipse.emf.releng.build/buildAll.xml]
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/zips/build.xml?rev=HEAD&content-type=text/xml org.eclipse.emf.releng.build/zips/build.xml]
+
  (line 14, target "standalone")
+
 
+
'''Test'''
+
 
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/testManifest.xml?rev=HEAD&content-type=text/xml org.eclipse.emf.releng.build/testManifest.xml]
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/templateFiles/testManifest.xml.template?rev=HEAD-type=text/xml org.eclipse.emf.releng.build/templateFiles/testManifest.xml.template]
+
[http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/tests/configs/local/customTest.xml?rev=HEAD&content-type=text/xml org.eclipse.emf.releng.build/tests/configs/local/customTest.xml]
+
 
+
 
+
===Build Server Directory Structure===
+
 
+
Here's a quick snapshot of the directory structure used on the emft build server, so that you can reproduce it elsewhere.<br /><br /> The emft build server (emf.torolab) is running Debian 3.0 (Woody), kernel 2.4.25, with dual 2G AMD Opteron processors, 3G RAM, 1.5G swap, and 33G HD.<br /><br />
+
 
+
{| border="1" cellpadding="2"
+
| '''Path'''
+
| '''Purpose/Description'''
+
|- valign="top"
+
| /var/www/emft/
+
| internal web paths (build.php)
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /var/www/technology/emft/
+
| external web path mirrored to download.eclipse (downloads, etc.)
+
|- valign="top"
+
| /var/www/technology/emft/build.options.txt
+
| file used by both build.php and downloads/index.php to display only those builds specified
+
|- valign="top"
+
| /var/www/technology/emft/downloads/index.php
+
| where to download project zips
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /var/www/technology/emft/''[subproject]''/downloads/
+
| symlink to /home/www-data/build/emft/''[subproject]''/downloads/ (so that the downloads page can find the zips)
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /home/www-data/build/emft/scripts/
+
| build path to where shell scripts are initiated by the web (the apache1.3 user is www-data)
+
|- valign="top"
+
| /home/www-data/build/emft/requests/
+
| build path to where build.php's data (URLs and log of requests for builds) is stored
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /home/www-data/build/emft/''[subproject]''/downloads/
+
| where required .zips are downloaded prior to building (eg., Eclipse SDK, EMF SDK)
+
|- valign="top"
+
| /home/www-data/build/emft/''[subproject]''/downloads/drops/
+
| where ''[subproject]'' is built (all versions here, including any NLS zip, once available (if any))
+
|- valign="top"
+
| /home/www-data/build/emft/''[subproject]''/downloads/drops/1.0.0/
+
| where ''[subproject]'' v1.0.0 is built
+
|- valign="top"
+
| /home/www-data/build/emft/''[subproject]''/downloads/drops/1.0.0/ [type][yyyymmddHHMM]/
+
| a specific build's folder, including zips, test results, docs
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /opt/ibm-java2-1.4 -> /opt/ibm-java2-ws-sdk-pj9xia32142-20050609
+
| default build JDK / used for JUnit tests
+
|- valign="top"
+
| /opt/sun-java2-1.4 -> /opt/j2sdk1.4.2_03
+
| optional build JDK / used for EMF JDK tests
+
|- valign="top"
+
| /opt/sun-java2-5.0 -> /opt/jdk1.5.0_03
+
| optional build JDK / used for EMF JDK tests
+
|- valign="top"
+
| /opt/ibm-java2-1.3 -> /opt/IBMJava2-131
+
| used to test EMF 2.0.x ONLY
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /opt/apache-ant-1.6.1 (or newer)
+
| build &amp; utility scripts
+
|- valign="top"
+
| colspan="2" |
+
|- valign="top"
+
| /usr/bin/php4 (4.1.2 or newer)
+
| both Apache module and CLI (command line interface) modules required
+
|}
+
 
+
 
+
===Testing &amp; Diagnosing Builds===
+
 
+
To determine what's wrong with your build, make sure you're building in debug mode. eg., [http://emft.eclipse.org/emft/build.php?debug=true] or [http://emf.torolab.ibm.com/emft/build.php?debug=true]. Then set the following parameters:
+
 
+
  Build Type: N (Nightly)
+
  Tag Build: No
+
  Run Tests: JUnit
+
  debug java home: /opt/ibm-java2-ws-sdk-pj9xia32142-20050609
+
  debug noclean: Y
+
Then, you can use the following shell commands:
+
 
+
<pre>
+
# shortcut to builds folder
+
alias odd=' cd /home/www-data/build/emft/ocl/downloads/drops/1.0.0'
+
 
+
# shortcut to LATEST build folder
+
alias lastfolder='cd `find . -maxdepth 1 -type d -not -name \
+
  "." -exec date -r {} +%s\ {} \; | sort | tail -1 | \
+
  sed -e "s/[0-9]\+\ \.\///g"`'
+
 
+
alias oddl='odd; lastfolder'
+
 
+
# check build log
+
oddl; tail -60 buildlog.txt
+
 
+
# check JUnit test console log
+
oddl; cd testing/*/testing/; tail linux.gtk_consolelog.txt
+
 
+
# check JUnit test eclipse workspace error log
+
oddl; cd testing/*/testing/eclipse/workspace/.metadata/; less .log
+
</pre>
+
 
+
 
+
===Suppressing Compiler Warnings===
+
 
+
After 3.2M6, PDE will now report compilation warnings in its JUnit test results page.
+
 
+
You can either fix your code to remove these warnings, or suppress the warnings themselves. See [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/jet/buildAll.xml?rev=HEAD&content-type=text/xml /org.eclipse.emft/releng/jet/buildAll.xml], for an example of how to suppress these warnings.
+
 
+
<echo message="Set compilerArgs = '-enableJavadoc -encoding ISO-8859-1 -warn:-serial'"/>
+
<property name="compilerArg" value="-enableJavadoc -encoding ISO-8859-1 -warn:-serial" />
+
 
+
For a complete list of supported warning flags in 3.1 - 3.3, go here: [http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_api_compile.htm http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_api_compile.htm] (see Warning Options).
+
 
+
You can also bring up that same help page in Eclipse's built-in help (<tt style="color:DarkGreen">JDT Plug-in Developer Guide > Programmer's Guide > JDT Core > Compiling Java code</tt>) for the 3.2 version, which adds a couple other options to the list.
+
 
+
===Heterogeneous Compiler Source/Target Levels===
+
 
+
If your project has plug-ins that have different requirements for the compiler source and target compliance level, the PDE's
+
<tt style="color:DarkGreen">build.properties</tt> file can be used to specify these on a plug-in by plug-in basis.  For a plug-in that supports
+
J2SE 1.4 and above, just add:
+
 
+
javacSource = 1.4
+
javacTarget = 1.4
+
 
+
in that plug-in's <tt style="color:DarkGreen">build.properties</tt>.  For a plug-in that uses J2SE 5.0 language capabilities, just add:
+
 
+
javacSource = 1.5
+
javacTarget = 1.5
+
 
+
and similarly for 6.0, 7.0, ...  For an example, see the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/validation/plugins/org.eclipse.emf.validation.ocl/build.properties?view=markup validation.ocl plug-in], which differs from the other validation plug-ins in requiring J2SE 5.0.
+
 
+
You may already have an EMFT releng system that forces 1.4 source and target in the <tt style="color:DarkGreen">buildAll.xml</tt> file.
+
Simply remove that and the <tt style="color:DarkGreen">javacSource=1.4</tt> entries from the <tt style="color:DarkGreen">build.properties</tt> files in each <tt style="color:DarkGreen">builder/*</tt> folder.  For example, see in the Query component's releng:
+
 
+
* before &amp; after [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/releng/query/buildAll.xml?r1=1.24&r2=1.25&diff_format=l buildAll.xml]
+
* before &amp; after [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/releng/query/builder/sdk/build.properties?r1=1.5&r2=1.6&diff_format=l builder/sdk/build.properties].
+
 
+
===Build Problems &amp; Solutions===
+
 
+
In no particular order, here are some lessons learned from setting up the various EMFT builds:<br /><br />
+
 
+
{| border="1" cellpadding="2"
+
| '''Error Message'''
+
| '''Fix'''
+
|- valign="top"
+
|
+
eclipse/test.assembly/eclipse/
+
plugins/${org.eclipse.test} not found.
+
|
+
Add the "org.eclipse.test" and "org.eclipse.ant.optional.junit" plugins to each test feature. The task creates one property for each test plugin (the property name is the plugin name minus the version). Only plugins referenced by features are downloaded, and, if a plugin has to be downloaded, the map file has to describe how to do it. Thus this information must appear in two places: [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf.releng.build/tests/customTargets.xml?rev=HEAD&content-type=text/xml tests/customTargets.xml] and [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/tests/org.eclipse.emf.tests-feature/feature.xml?rev=HEAD&content-type=text/xml <nowiki>*.tests-feature/feature.xml</nowiki>]. Since "org.eclipse.test" is not listed on the tests feature, it is not being downloaded - regardless of it being listed in the map file.<br/><br/>If you have added this to your mapfile and features, and you're still having problems, verify your mapfile has the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare.releng/templateFiles/compare.map.template?revision=1.2&root=Modeling_Project right tag for org.eclipse.test].
+
 
+
If you have checked all these conditions and still get an error, make sure [https://bugs.eclipse.org/bugs/show_bug.cgi?id=192231 your test feature specifies version="0.0.0"] for the org.eclipse.test plugin so that PDE can calculate the version for you. This problem manifests with releng.basebuilder versions after M4_33, as discussed in bugs [https://bugs.eclipse.org/bugs/show_bug.cgi?id=190834 190834] and [https://bugs.eclipse.org/bugs/show_bug.cgi?id=192231 192231].
+
 
+
Additionally, good hygiene suggests that all your features should have the correct builder/nature in their .project files. This will ensure that when you're manipulating your features in Eclipse, PDE will report problems (eg., typos) as they happen rather than during a build.
+
 
+
<buildSpec>
+
  <buildCommand>
+
    <name>org.eclipse.pde.FeatureBuilder</name>
+
    <arguments/>
+
  </buildCommand>
+
</buildSpec>
+
<natures>
+
  <nature>org.eclipse.pde.FeatureNature</nature>
+
</natures>
+
 
+
|- valign="top"
+
| SomeBundleOrClass cannot be resolved (compilation failed).
+
|
+
Check your [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.ocl/coordinated/org.eclipse.ocl.all-feature/feature.xml?root=Modeling_Project&r1=1.1&r2=1.2 feature.xml] [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.ocl/coordinated/org.eclipse.ocl.all.sdk-feature/feature.xml?root=Modeling_Project&r1=1.2&r2=1.3 files]. PDE will build features in the order they're listed. See also bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=140745 140745].
+
|- valign="top"
+
|
+
[exec]  -cp  org.eclipse.equinox.launcher.Main
+
                    ...
+
[exec] Unrecognized option: -ws
+
[exec] Could not create the Java virtual machine.
+
|
+
Check [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.compare.releng/builder/tests/configs/local/relengbuildgtk.sh?root=Modeling_Project relengbuildgtk.sh], and make sure the <code>$cp</code> or <code>$cpAndMain</code> variable is being set correctly. Also, make sure that if you're building with Eclipse 3.2 you use <code>org.eclipse.'''core'''.launcher.Main</code> instead of Eclipse 3.3's <code>org.eclipse.'''equinox'''.launcher.Main</code>. See also [[FAQ How do I run Eclipse? | Running Eclipse]] and [[Automated_PDE_JUnit_Testing_With_Eclipse_3.3M5 | PDE JUnit Testing]].
+
|- valign="top"
+
| org.eclipse.emft.ocl.releng/ builder/sdk/customTargets.xml -> eclipse/assemble.org.eclipse.emf.ocl.sdk.xml -> eclipse/tmp/eclipse/plugins/ org.eclipse.emf.ocl.doc_1.0.0.200602231606 not found
+
|
+
This could be a number of problems, but the most likely is that [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/ocl/doc/org.eclipse.emf.ocl.doc/build.xml <tt style="color: DarkGreen">org.eclipse.emft/ocl/doc/org.eclipse.emf.ocl.doc/build.xml</tt>] needs to have the correct value for <tt style="color: DarkGreen">pluginVersion</tt> set or is missing this property entirely.<br /><br /><tt style="color: DarkGreen"> <property name="pluginVersion" value="1.0.0"/></tt><br /><br /> If that doesn't solve the problem, run a debug build with the <tt style="color: DarkGreen">-noclean</tt> flag checked to see what's in the <tt style="color: DarkGreen">eclipse/tmp/eclipse/plugins/</tt> folder. For the case of the above build, the folder created was called <tt style="color: DarkGreen">org.eclipse.emf.ocl.doc_${pluginVersion}.200602231617</tt> instead of <tt style="color: DarkGreen">org.eclipse.emf.ocl.doc_1.0.0.200602231617</tt>, since the property was not defined. <br />
+
|- valign="top"
+
| java.io.FileNotFoundException: testing/target/eclipse/ plugins/org.eclipse.emf.ocl.tests_1.0.0/ (Plugin is a jar, not a folder)
+
|
+
If your test plugin is compiled as a jar, not a folder, you need to fix your feature.xml. Remove the attribute <tt style="color: DarkGreen">unpack="false"</tt> from the [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/tests/org.eclipse.emf.tests-feature/feature.xml?rev=HEAD&content-type=text/xml org.eclipse.emf.*.tests] plugin: <br /><tt style="color: DarkGreen"><plugin id="org.eclipse.emf.ocl.tests" download-size="0" install-size="0" <strike>unpack="false"</strike> version="1.0.0"/></tt>
+
|- valign="top"
+
| java.io.FileNotFoundException: testing/target/eclipse/ plugins/org.eclipse.emf.ocl.tests_1.0.0/ test.xml (No such file or directory)
+
|
+
Add a "test.xml" script to each test plugin, in [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/org.eclipse.emf/tests/org.eclipse.emf.test.build/test.xml?rev=HEAD&content-type=text/xml tests/org.eclipse.emf.*/test.xml].<br/><br/>If this file already exists, verify in <tt style="color: DarkGreen">releng/ ''[subproject]''/ builder/ tests/ scripts/ [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/net4j/builder/tests/scripts/test.xml?rev=HEAD&content-type=text/xml test.xml]</tt> that target <tt style="color: DarkGreen">runtests</tt> knows whether your tests plugin is jarred or not. Comment/uncomment out test.xml script accordingly.
+
|- valign="top"
+
| java.io.FileNotFoundException: eclipse/fetch_org.eclipse.emft.ocl.sdk.xml (No such file or directory)
+
| Either the feature doesn't exist (and must be added), or the feature is misreferenced. Make sure that you do not have any scripts referring to, say, plugins or features called <tt style="color: DarkGreen">org.eclipse.'''emft'''.ocl.sdk</tt>, but rather <tt style="color: DarkGreen">org.eclipse.'''emf'''.ocl.sdk</tt>. The <tt style="color: DarkGreen">org.eclipse.emft</tt> namespace is only for the CVS module; everywhere else, you should use <tt style="color: DarkGreen">org.eclipse.emf</tt> when referencing plugins and features.
+
|- valign="top"
+
| JUnits tests not appearing on testResults.php page
+
|
+
Add an entry for the missing tests into <tt style="color: DarkGreen">org.eclipse.emft/releng/''[subproject]''/ templateFiles/testManifest.xml.template</tt> and <tt style="color: DarkGreen">org.eclipse.emft/releng/''[subproject]''/ testManifest.xml, eg:</tt>
+
 
+
<logFile
+
  name="org.eclipse.emf.query.ocl.tests_linux.gtk.xml">
+
<effectedFile id="SDK"></effectedFile>
+
<effectedFile id="projRUN"></effectedFile>
+
</logFile>
+
|- valign="top"
+
| Failure to download and unzip one of the SDKs that your project depends on
+
|
+
You probably have a typo in the URL that you entered into the "New URLs" field. Try the following to get the correct URL every time:
+
 
+
# Surf to your dependency's downloads page on eclipse.org.
+
# Navigate to the build that you need.
+
# Click the download link for the all-encompassing SDK ZIP.
+
# When the "blah now downloading, if it doesn't start immediately, <u>click here</u>" message appears, right-click on the "click here" link and select "Copy Link Location" (or the equivalent action in your browser or choice).
+
# You now have in your cut buffer the exact link to the file that you need.
+
 
+
Depending on your configuration, you may have an extra navigation to a mirror site in the above sequence.
+
|- valign="top"
+
| Build is ok, everything compiles, but plugins are missing from the SDK!
+
|
+
* Check the [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/cdo/plugins/org.eclipse.emf.cdo.utilities.migrator/META-INF/MANIFEST.MF.diff?r1=text&tr1=1.3&r2=text&tr2=1.2&diff_format=h MANIFEST.MF] for the plugins that aren't appearing.
+
* Ensure all properties files and MANIFEST.MF files have a trailing newline at the end of the file.
+
* Ensure all plugins are contained in some feature or other, and that those containing features are themselves contained in your SDK feature or other composite feature (like tests or examples). Eg., plugin [http://dev.eclipse.org/viewcvs/indextech.cgi/org.eclipse.emft/cdo/plugins/org.eclipse.emf.cdo.utilities.migrator/ org.eclipse.emf.cdo.utilities.migrator] is included in [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/cdo/plugins/org.eclipse.emf.cdo.utilities-feature/feature.xml org.eclipse.emf.cdo.utilities-feature/feature.xml], which is included in [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/cdo/plugins/org.eclipse.emf.cdo-feature/org.eclipse.emf.cdo.sdk/feature.xml org.eclipse.emf.cdo-feature/org.eclipse.emf.cdo.sdk/feature.xml]
+
 
+
|- valign="top"
+
| Build is ok, everything compiles, but SDK includes '''BOTH''' unpacked source files and packed src.zip files.
+
|
+
Verify that you have included your branding plugin (eg., org.eclipse.net4j) in your branding feature (eg., [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/net4j/plugins/org.eclipse.net4j-feature/feature.xml org.eclipse.net4j-feature/feature.xml]), even if it contains NO source and that you've set that plugin to be unpack="false":
+
 
+
<plugin
+
  id="org.eclipse.net4j"
+
  download-size="0"
+
  install-size="0"
+
  version="0.0.0"
+
  '''unpack="false"'''/>
+
 
+
|
+
|- valign="top"
+
| '''[[https://bugs.eclipse.org/bugs/show_bug.cgi?id=185001 185001]]''' Plugin jars contain nested jars instead of class files.
+
|
+
See [[#Bundle-ClassPath_With_Dot | Bundle-ClassPath With Dot]].
+
 
+
|
+
|- valign="top"
+
| External jar files (like log4j) are not included in the plugin when building and zipping the plugins
+
|
+
Ensure that the Bundle-ClassPath in the MANIFEST.MF contains the dot (.) for example:
+
 
+
Bundle-ClassPath: .,commons-logging.jar,log4j-1.2.8.jar
+
 
+
|
+
|- valign="top"
+
| publish.xml fails to generate build artefacts!
+
|
+
This has been deprecated in the latest org.eclipse.releng.basebuilder. For the solution, see details in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=165698 bug 165698].
+
 
+
|- valign="top"
+
| Need to update your build to EMF 2.3 and J2SDK 5.0.
+
|
+
That's a pretty big subject.  See [[EMF 2.3 Adoption]] for details.
+
 
+
|- valign="top"
+
| java.lang.NoClassDefFoundError: org/eclipse/core/launcher/Main
+
|
+
You need to upgrade to the [[Equinox Launcher]]. See [[Automated PDE JUnit Testing With Eclipse 3.3M5 | Automated PDE JUnit Testing With Eclipse]] for details on how to fix this problem.
+
|}
+
 
+
== Branching ==
+
 
+
To support both a HEAD and an Rx_y_maintenance branch, you need to branch your cvs repository. This is accomplished easily using Eclipse or commandline CVS.
+
 
+
In Eclipse, select your plugins, then right-click and do Team > Branch...
+
 
+
If you're following the usual convention, you'd do your Eclipse 3.3 compatible work in HEAD and your Eclipse 3.2 work in a maintenance branch. Taking the JET Editor project as an example, you'd do something like this:
+
 
+
# build a 0.7.0 R build. Use type "R" (Release), then set the build alias field on the build page to "0.7.0".
+
# create a branch called R0_7_maintenance, with root R0_7_0. (You'll create a redundant, but potentially handy tag for your 0.7.0 release.)
+
# begin doing "R0_7_maintenance | 0.7.1" builds from your build page at /emft/build/?project=jeteditor. Pick Eclipse 3.2 driver from the list (they'll have M or R).
+
# at the same time, start on your Eclipse 3.3 development, then kick builds using "HEAD | 0.8.0" from the picker on the build page. Select an Eclipse 3.3 driver (they have I or S or R). You can get these from here: http://download.eclipse.org/eclipse/downloads/
+
 
+
'''NOTE:''' be sure to copy just the http path to the tar.gz file, without ?file= querystring stuff in it. For example:
+
 
+
* http://download.eclipse.org/eclipse/downloads/drops/S-3.3M2-200609220010/eclipse-SDK-3.3M2-linux-gtk.tar.gz
+
* http://download.eclipse.org/downloads/drops/I20060926-0935/eclipse-SDK-I20060926-0935-linux-gtk.tar.gz
+
 
+
The [[Platform-releng-basebuilder|recommended list of tags for use with org.eclipse.releng.basebuilder is located here]] and updated when new tags are added (usually once a miletone).
+
 
+
 
+
 
+
{| border="1" cellpadding="2"
+
| '''Problem'''
+
| '''Solution'''
+
|- valign="top"
+
| I choosed to build my maintenance branch from the web ui, but the built plugins are coming from HEAD.
+
| Check that your map file of your maintenance branch releng plugin refers to the branched plugin and not to HEAD.
+
|}
+
 
+
==Release Process==
+
 
+
All the EMFT subprojects are requested to follow this release schedule:
+
 
+
* Wednesday night:
+
** Your code in CVS must be "compile error free". Feel free to run N builds that afternoon to verify this.
+
* Thusrday morning:
+
** One Integration (I) build from your main branch (HEAD), and/or
+
** One Maintenance (M) build from your maintenance branch (eg., R1_0_maintenance).
+
 
+
===Renaming a Build / Releasing Your GM Build===
+
 
+
* When releasing your final build, you may decide to rename an RC build if nothing bad has happened since that build was released. For example, you might plan to release your final build on Sept. 28, so you'd do an RC1 build two weeks before. If any stop-ship bugs were found, you'd spin an RC2 build the week after, on the 21st. Then, if no more bugs were found, you'd be able to promote that build as your GM (Golden Master) on Sept. 28 - however, you'd have to rename the zips, md5 files, dependencies listed in build.cfg, etc.
+
 
+
* The good news is that there's an easy way to do this - [http://dev.eclipse.org/viewcvs/indextools.cgi/*checkout*/emf-home/emf-build/scripts/renameBuild.sh?content-type=text/plain renameBuild.sh]. This script contains detailed instructions and examples of usage; just run it from the commandline w/o options to see. Additionally, here's an example showing a rename of JET from 0.7.1RC2 to 0.7.1:
+
 
+
sudo -u www-data ./renameBuild.sh -proj jet -verbose -branch 0.7.1 \
+
-buildID S200609210820=R200609210820 -buildAlias 0.7.1RC2=0.7.1 \
+
eclipse-SDK-M20060919-1045-linux-gtk.tar.gz=eclipse-SDK-3.2.1-linux-gtk.tar.gz \
+
M20060919-1045=R-3.2.1-200609210945 \
+
S200609210005=R200609210005 \
+
2.2.1RC2=2.2.1 \
+
fullmoon.torolab.ibm.com=download.eclipse.org \
+
emf.torolab.ibm.com=download.eclipse.org
+
 
+
* When you're done renaming, you can simply promote the new build as you did the previous week (<tt style="color:DarkGreen">-buildID S200609210820</tt>), using the new ID (<tt style="color:DarkGreen">-buildID R200609210820</tt>), and you'll have your GM build published.
+
 
+
* After releasing the final build of a given version, you need to remember to upgrade the version of the plugins you change. In other words, if a plugin is not changed then its version remains the same. After upgrading the version of a plugin, you need to ensure that the version of the appropriate features and branding plugins are also upgraded, and that the feature is referring to the new versions of the plugins. Also, if you change a plugin with source code, you may need to upgrade the appropriate documentation plugin (and documentation feature and branding plugin) if the build is adding Javadoc to it.
+
 
+
===Promoting A Build===
+
 
+
Adding new builds or even new subprojects is relatively simple. The hands-on manual approach is to use scp to copy you new build's folder from where it was built, eg., <tt style="color: DarkGreen">/home/www-data/build/emft/transaction/downloads/drops/1.0.0/I200601111814</tt> to its destination on <tt style="color: DarkGreen">download1.eclipse.org</tt>, eg., <tt style="color: DarkGreen">/home/data/httpd/download.eclipse.org/technology/emft/transaction/downloads/drops/1.0.0/I200601111814</tt>. From there, [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/public_html/technology/emft/downloads/index.php?rev=HEAD&content-type=text/vnd.viewcvs-markup <tt style="color: DarkGreen">/home/data/httpd/download.eclipse.org/technology/emft/downloads/index.php</tt>] will find &amp; display it automatically.
+
 
+
You can modify the way the downloads page appears in two simple ways by editing [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/public_html/technology/emft/build.options.txt <tt style="color: DarkGreen">build.options.txt</tt>], which is used to both [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/private_html/emft/build.php?rev=HEAD&content-type=text/vnd.viewcvs-markup create builds] and display them for downloading:
+
 
+
* you can add/remove branches from display, by adding entries under the <tt style="color: DarkGreen">[Branch]</tt> entry. Display entries are in the form <tt style="color: DarkGreen">-=1.0.0</tt>, whereas build instruction entries are in the form <tt style="color: DarkGreen">1.0.1=R1_0_maintenance</tt>.
+
* you can reorder the way build types are displayed by resequencing the values under the <tt style="color: DarkGreen">[BuildType]</tt> entry. The remaining entries are used when building.
+
 
+
The above process ONLY adds the build to the downloads page; it does not fix permissions or group ownership of files, nor update any map files, news files, release notes, or other meta information. As such, the full process for promoting a build is rather lengthy, and thus has been simplified into a script, [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/promoteToEclipse.sh?rev=HEAD&content-type=text/vnd.viewcvs-markup <tt style="color: DarkGreen">promoteToEclipse.sh</tt>] and its accompanying property file, [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/promoteToEclipse.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup <tt style="color: DarkGreen">promoteToEclipse.properties</tt>].
+
 
+
:'''''UPDATE''''': You can also use the [http://emft.eclipse.org/modeling/emft/compare/build/promo.php promo.php] script for your project. Contact [[User:nickb]] for username/password access.
+
 
+
The simplest way to learn how to use this script is to first run it without options to see the inline help, or to read the help within the script itself. From there, running it is straightforward, but certain [[#SSH Key Setup|SSH permisions]] must be set in order for things to work as expected.
+
 
+
To make CVS happy when promoting a build, ensure the existence of a .cvspass file in your home directory:
+
 
+
touch ~/.cvspass
+
 
+
As an example, here's how an EMFT Transaction build is promoted:
+
 
+
cd /home/www-data/build/emft/scripts;
+
./promoteToEclipse.sh -sub transaction -branch 1.0.0 -buildID I200601111814 -Q \
+
  -announce 2&gt;&amp;1 | tee ~/promo_`date +%Y%m%d_%H%M%S`.txt
+
 
+
The -Q argument suppresses noisy CVS checkout messages and -announce posts an announcement of the build availability to the EMFT newsgroup.
+
 
+
===Update Manager Sites &amp; Build Types===
+
 
+
If you go to http://www.eclipse.org/emft/updates/, you'll see a note about two different UM sites. These two sites are there to split final, release builds from interim builds, so that the two types of users can benefit from the two types of releases.
+
 
+
A release build (R) is anything that's done as a final GM (aka ''Golden Master'') release, eg., 0.7.0, 0.7.1, 1.0.0, 1.0.1.
+
Everything else is considered "interim" - Nightly, Integration, Maintenance, Stable (N, I, M, S).
+
 
+
So, for example, when you publish an I build (eg., 0.7.5 I200610050000), it gets added to [http://download.eclipse.org/technology/emft/updates/site-interim.xml site-interim.xml]. When you do your final build for that stream, (eg., 0.7.5 R200612020000), it will be added to [http://download.eclipse.org/technology/emft/updates/site.xml site.xml].
+
 
+
Note also that the URL to give to Update Manager (or to put in your features) is NOT http://www.eclipse.org/emft/updates/, but download.eclipse.org. www.eclipse.org stores website content only, and provides a location for extracting, updating, and committing changes to the site.xml and site-interim.xml files, in order to provide CVS versioning &amp; history. The actual site is [http://download.eclipse.org/technology/emft/updates/ http://download.eclipse.org/technology/emft/updates/site*.xml], which is also benefitted by the fact that it's mirrored (unlike www.eclipse.org).
+
 
+
* For more on build types, see http://www.eclipse.org/emf/downloads/build-types.php.
+
 
+
====Generating Update Manager Site Jars====
+
 
+
* For details on generating Update Manager site XML and jars, see: [[Update_Manager_Site_Generation|Update Manager Site Generation]].
+
 
+
===Generating Release Notes===
+
 
+
Generating release notes is easy - [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/promoteToEclipse.sh?rev=HEAD&content-type=text/vnd.viewcvs-markup <tt style="color: DarkGreen">promoteToEclipse.sh</tt>] does it for you! However, there are a few simple steps to follow to ensure the generated content is accurate &amp; non-duplicative. Here's the general process for closing a bug and using Bugzilla &amp; CVS to provide the information required to generate release notes.
+
 
+
* Working in Eclipse, fix your code. Test is as much as possible before committing it to CVS.
+
* Commit your change(s) to CVS, using the bug's number in square brackets to begin your commit comment, eg:
+
 
+
[127509] javadocs now available
+
 
+
* Note that you can include multiple bugs (each number on its own line) and comments are not required. The information that will appear in the release notes comes from the bug's <tt style="color: DarkGreen">Summary</tt> field, not your CVS comments.
+
* Browse to the bug's webpage, and assign it the status <tt style="color: DarkGreen">Assigned</tt>. Your bugzilla comment could be something like:
+
 
+
Committed to CVS
+
 
+
* Tip: to save time, you can create &amp; save a named Bugzilla query for [https://bugs.eclipse.org/bugs/colchange.cgi?rememberedquery=product%3DEMFT%26bug_status%3DASSIGNED%26order%3Dbugs.bug_id%26query_format%3Dadvanced&amp;column_changeddate=on&amp;column_bug_severity=on&amp;column_priority=on&amp;column_rep_platform=on&amp;column_bug_status=on&amp;column_product=on&amp;column_component=on&amp;column_version=on&amp;column_target_milestone=on&amp;column_short_short_desc=on&amp;splitheader=0 <tt style="color: DarkGreen">All Assigned</tt>], in order to quickly [https://bugs.eclipse.org/bugs/colchange.cgi?rememberedquery=product%3DEMFT%26bug_status%3DASSIGNED%26order%3Dbugs.bug_id%26query_format%3Dadvanced%26tweak%3D=1&amp;column_changeddate=on&amp;column_bug_severity=on&amp;column_priority=on&amp;column_rep_platform=on&amp;column_bug_status=on&amp;column_product=on&amp;column_component=on&amp;column_version=on&amp;column_target_milestone=on&amp;column_short_short_desc=on&amp;splitheader=0 <tt style="color: DarkGreen">Change Several Bugs At Once</tt>].
+
 
+
* Produce a build, and promote it. Unless you use the <tt style="color: DarkGreen">-norss</tt> flag:
+
** Your [http://dev.eclipse.org/viewcvs/index.cgi/www/emft/feeds/?root=Eclipse_Website RSS feed] will be updated,
+
** The Modeling database will see that new entry,
+
** A corresponding entry will be added to the Releases table, and
+
** A refresh of the [http://www.eclipse.org/modeling/emft/news/ release notes] will now show that new entry.
+
 
+
====Troubleshooting====
+
 
+
=====My new build isn't listed on the website!=====
+
 
+
Mirror replication takes time. Please try again in 30 mins, or re-read your promote log to verify everything went OK.
+
 
+
=====My new build isn't listed in the Release Notes!=====
+
 
+
First, check your RSS feed file to ensure it's been updated. If it hasn't, check your promote log for failures in updating the feed. If it has, please be patient and wait for the next database update. Your RSS feed file controls the list of releases that are imported into the Releases table of the Search CVS database, and thus appear on the Release Notes page.
+
 
+
=====There are errors in my release notes! How do I edit?=====
+
 
+
If you want to remove or edit values in your RSS feed and flush old/incorrect values from the database, please edit the file /cvsroot/org.eclipse/www/modeling/''projectName''/feeds/builds-''componentName''.xml (eg., ''projectName'' = emft; ''componentName'' = teneo). When done, send an email to [[User:nickb]] requesting a database flush for your component's releases.
+
 
+
=====Bugs are missing from the Release Notes!=====
+
 
+
Database updates can take a while. If it's been 24hrs and you '''*still*''' are missing data, contact [[User:nickb]].
+
 
+
=====RSS Update Errors When Promoting=====
+
 
+
{| border="1" align="center" cellpadding="3" cellspacing="1"
+
! Problem !! Solution
+
|-valign="top"
+
|
+
addEntry:
+
  [AddEntry] [Fatal Error] builds-teneo.xml:13:2:
+
    The content of elements must consist of
+
    well-formed character data or markup.
+
  [AddEntry] org.xml.sax.SAXParseException:
+
    The content of elements must consist of
+
    well-formed character data or markup.
+
 
+
|| Check the file on the build server in [http://emft.eclipse.org/emft/feeds/ /var/www/html/emft/feeds/]. Is it corrupt? Is it full of invalid XML due to a CVS update/merge? If so, so the following:
+
cd /var/www/html/emft/feeds/; \
+
rm -f builds-<tt style="color: DarkGreen">projectName</tt>.xml; \
+
cvs up -Pd; \
+
chmod 664 builds-<tt style="color: DarkGreen">projectName</tt>.xml; \
+
chgrp www builds-<tt style="color: DarkGreen">projectName</tt>.xml;
+
Then rerun your promote using the <tt style="color: DarkGreen">-rssonly</tt> flag to redo that single step. After that, you can force an update of the database - including loading any new CVS commits - with the <tt style="color: DarkGreen">-searchcvsonly</tt> flag. If you don't need to refresh commits, just the Releases table, you can run this (on emft.eclipse.org only):
+
cd /shared/modeling/searchcvs; \
+
php relupdate.php -noheat
+
|-valign="top"
+
|
+
Permission denied
+
 
+
|| Check the file on the build server in [http://emft.eclipse.org/emft/feeds/ /var/www/html/emft/feeds/]. Is it writable by you or one of the groups of which you're a member? Try this:
+
cd /var/www/html/emft/feeds/; \
+
ls -la; groups; \
+
chmod 664 *; chgrp www *;
+
Then rerun your promote using the <tt style="color: DarkGreen">-rssonly</tt> flag to redo that single step. After that, you can force an update of the database - including loading any new CVS commits - with the <tt style="color: DarkGreen">-searchcvsonly</tt> flag. If you don't need to refresh commits, just the Releases table, you can run this (on emft.eclipse.org only):
+
cd /shared/modeling/searchcvs; \
+
php relupdate.php -noheat
+
|}
+
 
+
=== Automatically Fixing Assigned Bugs ===
+
 
+
As of 2007-08-29, you can use [http://emft.eclipse.org/modeling/emft/compare/build/promo.php promo.php] or the <tt style="color: DarkGreen">-bugzonly</tt> flag to automatically move your ASSIGNED bugs to FIXED, and place a comment stating in which build the bug was fixed.
+
 
+
====Setup / Troubleshooting====
+
 
+
The first time you use this option, or if your bugzilla cookie expires, you will receive an error like this:
+
 
+
[promote] ERROR: login cannot be read from ~/.ssh/UpdateBugStateTask.properties.
+
 
+
To regenerate credentials / cookie information, log in to the build server and run:
+
 
+
cd /home/www-data/build/modeling/scripts;
+
./bugzillaLogin.sh 2> ~/.ssh/UpdateBugStateTask.properties
+
 
+
===Newsgroup Announcement Setup===
+
 
+
Setup for posting automatically to the newsgroup to announce new builds is easy.
+
 
+
: 1. Copy <tt style="color: DarkGreen">newsgroup-post.txt</tt> into your <tt style="color: DarkGreen">~/.ssh</tt> folder.
+
 
+
<tt style="color: #990000; background-color: #FFFFCC;">''build_id''@''build_server'':~ $</tt> <tt style="color: DarkGreen">mkdir -p ~/.ssh; cp /home/nickb/newsgroup-post/newsgroup-post.txt ~/.ssh</tt>
+
 
+
You are now set up to post automatically to the newsgroup while promoting a build. If you want to post as a specific person, rather than the [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/promoteToEclipse.properties default name &amp; email], there are two additional steps.
+
 
+
: 2. Edit <tt style="color: DarkGreen">org.eclipse.emft/releng/''[subproject]''/promoteToEclipse.''[subproject]''.properties</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/jet/promoteToEclipse.jet.properties example]></span>, placing the correct name and email address for the person whose name will appear on newsgroup posts. This step - and the next one - is '''ONLY''' required if the name &amp; email are not the same as the default value recorded [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/promoteToEclipse.properties here].
+
 
+
newsgroupPublisherEmail="John Q. Committer <john_q_emft_committer_guy@eclipse.org>"
+
 
+
: 3. Copy <tt style="color: DarkGreen">org.eclipse.emft/releng/''[subproject]''/promoteToEclipse.''[subproject]''.properties</tt> <span style="font-size: 9pt"><[http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/jet/promoteToEclipse.jet.properties example]></span> into <tt style="color: DarkGreen">/home/www-data/build/emft/scripts</tt>.
+
 
+
To announce a build that's already been built, you can use the <tt style="color: DarkGreen">-announceonly</tt> flag to skip all other steps and ONLY post to the newsgroup. Otherwise, adding <tt style="color: DarkGreen">-announce</tt> when promoting will add the extra step of posting a quick note to the newsgroup.
+
 
+
====Newsgroup Post Threading====
+
 
+
Should you want to thread your announcements so that they can be hidden or categorized, here's how you can do so:
+
 
+
# create the parent thread into which subsequent posts will go (just post a message to the newsgroup), then
+
# get the post's <tt style="color:DarkGreen">Message-ID</tt> (using Thunderbird, just turn on all headers to see this), and
+
# update the appropriate entry in your <tt style="color:DarkGreen">/home/www-data/build/emft/scripts/promoteToEclipse.*.properties</tt> file on your build server (emf.torolab or emft.eclipse).
+
 
+
Looking at promoteToEclipse.jet.properties as an example:
+
 
+
# publisher of newsgroup announcements
+
newsgroupPublisherEmail="John Q. Committer <john_q_emft_committer_guy@eclipse.org>"
+
newsgroup=eclipse.technology.emft
+
# to thread posts under an existing post (or posts) enter the slash-escaped Message-ID for which this is a reply,
+
# eg: <e0i2gc\$an5\$1@utils.eclipse.org>
+
<tt style="color:DarkGreen">newsgroupThreadReferences</tt>=""
+
 
+
If you put the <tt style="color:DarkGreen">Message-ID</tt> in the <tt style="color:DarkGreen">newsgroupThreadReferences</tt> property, announcements about builds will be nested under that existing message.
+
 
+
Note that to edit this file you must sudo to the web user:
+
 
+
* On emf.toro: <tt style="color:DarkGreen">sudo -u '''www-data''' vi promoteToEclipse.jet.properties</tt>
+
* On emft.eclipse: <tt style="color:DarkGreen">sudo -u '''apache''' vi promoteToEclipse.cdo.properties</tt>
+
 
+
If you'd like to store a copy of your changes in CVS, please contact your releng manager so that your changes can be committed into your releng module for safekeeping/versioning.
+
 
+
===SSH Key Setup===
+
 
+
You must have ssh access to your build server, download1.eclipse.org, and dev.eclipse.org. If you do not have access, please the administrators of these servers to gain access. Once you have ssh access, you need to set up '''limited''' ssh key access between your build server and the eclipse.org download and cvs servers. This will allow you to run the promote script without being prompted for a password periodically.
+
 
+
To grant yourself ssh access from your build server to eclipse.org, ssh to the build server normally.
+
 
+
Under windows, you can use [http://www.cygwin.com/ cygwin] or [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY]. Under Linux, open a shell and type `ssh`.
+
 
+
If you don't already have an ssh key pair created, you will need to generate one.
+
 
+
<tt style="color: #990000; background-color: #FFFFCC;">''build_id''@''build_server'':~ $</tt> <tt style="color: DarkGreen">mkdir -p ~/.ssh; chmod 700 ~/.ssh; cd ~/.ssh; ssh-keygen -b 2048 -t rsa</tt>
+
 
+
When prompted for a passphrase, hit enter to skip. Having a passphrase, while more secure than having no passphrase, prevents automated login.
+
 
+
Save your public key in <tt style="color: DarkGreen">~/.ssh/id_rsa.pub</tt> (or some other file).
+
 
+
Connect to the following systems, replacing <tt style="color: DarkGreen">''build_id''</tt> and <tt style="color: DarkGreen">''eclipse_id''</tt> with your actual system login for that machine (which '''MUST''' be the same). Replace <tt style="color: DarkGreen">''build_server''</tt> and <tt style="color: DarkGreen">''FQDN''</tt> with the actual values for your build server's hostname and fully-qualified domain name.
+
 
+
* <tt style="color: DarkGreen">''build_id''@''build_server''</tt>
+
* <tt style="color: DarkGreen">''build_id''@''FQDN''</tt>
+
* <tt style="color: DarkGreen">''build_id''@localhost</tt>
+
* <tt style="color: DarkGreen">''eclipse_id''@download1.eclipse.org</tt>
+
* <tt style="color: DarkGreen">''eclipse_id''@dev.eclipse.org</tt>
+
 
+
Get yourself added to the "www" group (or whatever is the user group that can update the website) on your build machine. This normally must be done by an administrator (root) of that machine.
+
 
+
All of those should work without being prompted for a password. If you are prompted, you need to set an ssh key in your <tt style="color: DarkGreen">~/.ssh/authorized_keys</tt> file for each user &amp; hostname pair to which you want to connect. The first time you try each of these connections, you should be be prompted to add the host's fingerprint to your <tt style="color: DarkGreen">~/.ssh/known_hosts</tt> file. This is also required.
+
 
+
To copy your local public key to the remote machine, you will need to scp (secure copy) the file. From the build server, copy the file to the remote server, then ssh to that server and combine the new key with the any existing keys in the authorized_keys file:
+
 
+
: <tt style="color: #990000; background-color: #FFFFCC;">''build_id''@''build_server'':~/.ssh $</tt> <tt style="color: DarkGreen">scp id_rsa.pub ''eclipse_id''@dev.eclipse.org:~/.ssh/''eclipse_id''.temp</tt>
+
: <tt style="color: #990000; background-color: #FFFFCC;">''build_id''@''build_server'':~/.ssh $</tt> <tt style="color: DarkGreen">ssh ''eclipse_id''@dev.eclipse.org</tt>
+
::: ''(you will still be prompted for a password when connecting)''
+
 
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~ $</tt> <tt style="color: DarkGreen">cd ~/.ssh; </tt>
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">touch ~/.ssh/authorized_keys; </tt>
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys_old; # backup</tt>
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">cat ~/.ssh/''eclipse_id''.temp ~/.ssh/authorized_keys_old > ~/.ssh/authorized_keys; # prepend new key into old file; save as new file</tt>
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">rm -fr ~/.ssh/''eclipse_id''.temp ~/.ssh/authorized_keys_old;</tt>
+
:: 
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">chmod 644 authorized_keys id_rsa.pub known_hosts; chmod 600 id_rsa; # fix perms</tt>
+
::
+
:: <tt style="color: #990000; background-color: #FFFFCC;">''eclipse_id''@dev.eclipse.org:~/.ssh $</tt> <tt style="color: DarkGreen">exit</tt>
+
 
+
: <tt style="color: #990000; background-color: #FFFFCC;">''build_id''@''build_server'':~/.ssh $</tt> <tt style="color: DarkGreen">ssh ''eclipse_id''@dev.eclipse.org</tt>
+
::: ''(this time you should get in using your key instead of needing a password)''
+
 
+
Once you have <tt style="color: DarkGreen">~/.ssh/authorized_keys</tt> and <tt style="color: DarkGreen">~/.ssh/known_hosts</tt> updated with your public key and server fingerprint(s) (respectively), you should be able to connect to these systems without being prompted, and the promote script should be good to go unassisted.
+
 
+
If you require further assistance setting up key access, try here: http://cfm.gs.washington.edu/security/ssh/client-pkauth/.
+
 
+
===Promotion Problems (CVS Errors, SCP Errors, Artifacts Not Created...)===
+
 
+
Please check your promote logs for errors or transient glitches, like CVS disconnects or SCP problems. Sometimes one problem can manifest as several problems, as in the case of this EMFT Validation build's UM jar creation, which threw four warnings that something had gone wrong, all starting from a transient CVS checkout problem (bandwidth overload or connection reset).
+
 
+
[promote] [9] [13:53:18] Create &amp; promote [[Update_Manager_Site_Generation|Update Manager]] jars:
+
[promote] Running buildUpdate.sh:
+
 
+
[umj-co] [1] Checking out org.eclipse.releng.basebuilder from dev
+
  using HEAD
+
cvs checkout: failed to open /home/vramaswamy/.cvspass for reading:
+
  No such file or directory
+
'''cvs [checkout aborted]: recv() from server dev.eclipse.org:
+
  Connection reset by peer'''
+
 
+
'''The java class is not found: org/eclipse/core/launcher/Main
+
features/*.jar: No such file or directory
+
plugins/*.jar: No such file or directory'''
+
 
+
[umj] [7d] [13:54:47] Comparing local and remote folders MD5 sums
+
  to ensure SCP completeness...
+
 
+
[compare] Compare md5sums...
+
'''[compare] MD5s do not match! Compare failed.'''
+
 
+
[umj] [13:54:52] '''ERROR! Script exiting from compareFolders.sh'''
+
[promote] [9] [13:54:52] Create &amp; promote [[Update_Manager_Site_Generation|Update Manager]] jars done.
+
 
+
In this case, the problems were:
+
 
+
* CVS disconnected while checking out required builder code
+
* Build failed looking for Eclipse Main, so no build occurred
+
* Copying files from temp to /var/www/technology/emft/updates/ failed as they were not created
+
* MD5 check failed as nothing was copied to download1.eclipse.org
+
 
+
In this case, the solution was to:
+
 
+
# Verify that nothing had been produced on either the build server or download1.eclipse.org.
+
# Confirm that site*.xml had not been changed in CVS, and rollback any changes for this build's ID (if any).
+
# Re-run the promote using the <tt style="color: DarkGreen">-jarsonly</tt> flag in order to bypass all the steps that completed successfully and ONLY do the UM jar creation step.
+
 
+
==Maintenance Processes==
+
 
+
By following a few simple rules, you can ensure that you never run out of memory or hard disc space when building, and that your neighbours on the server are similarly unaffected.
+
 
+
* Release builds should be kept at all times.
+
* Stable builds should be kept until they are considered stale, eg., M1 need not be kept once M4 or M5 is available. This is subject to your discretion or customer needs.
+
* Interim builds should be purged after every Milestone build so that you never have more than a few weeks of Interim builds listed.
+
* Nightly builds should be scrubbed every week or so in order to save space and keep your build server's downloads page clean.
+
 
+
 
+
===Removing CVS Tags===
+
 
+
To remove CVS tags, you can run the following commands (from any machine that can connect to dev.eclipse.org via ssh):
+
 
+
cvs -d ''[eclipse_id]''@dev.eclipse.org:/cvsroot/technology -q rtag -d ''[build_tag]'' org.eclipse.emft/''[subproject]'';
+
cvs -d ''[eclipse_id]''@dev.eclipse.org:/cvsroot/technology -q rtag -d ''[build_tag]'' org.eclipse.emft/releng/''[subproject]'';
+
 
+
where:
+
 
+
* <tt style="color:DarkGreen">''eclipse_id''</tt> is your cvs username for dev.eclipse.org
+
* <tt style="color:DarkGreen">''build_timestamp''</tt> is "build_" plus the timestamp of the build for which you want to remove its tag from CVS. For example, for a milestone build <tt style="color:DarkGreen">1.0.0M6a (S200604131352)</tt> (RC1, use <tt style="color:DarkGreen">build_200604131352</tt>.
+
 
+
Note that in order to remove tags from within <tt style="color:DarkGreen">org.eclipse.emft/releng</tt> you must be a member of the <tt style="color:DarkGreen">emft-releng</tt> group on dev.eclipse.org, or have similar write access via ACL.
+
 
+
 
+
===Removing Old Builds===
+
 
+
The simplest way to remove old builds is simply to delete them, both from the build server and from the public download1.eclipse.org server. Doing so will also (eventually) cause them to be removed from the eclipse.org mirrors.
+
 
+
====Manual Delete From Build Server====
+
 
+
To delete an old build, ssh to your build server, then run, for example:
+
 
+
cd /home/www-data/build/emft/''[subproject]''/downloads/drops/1.0.0;
+
sudo -u ''[web_user]'' rm -fr N200604152353;
+
 
+
where:
+
 
+
* <tt style="color:DarkGreen">''web_user''</tt> is the id on your build server which runs the Apache webserver processes, eg., <tt style="color:DarkGreen">www-data</tt> or <tt style="color:DarkGreen">apache</tt>
+
 
+
====Automated Delete From Build Server====
+
 
+
There is also a nightly crontab script that runs to purge old builds:
+
 
+
1 1 * * * sudo -u apache [http://dev.eclipse.org/viewcvs/indextech.cgi/*checkout*/org.eclipse.emft/releng/common/scripts/cleanupOldBuilds.sh?content-type=text/plain /home/www-data/build/emft/scripts/cleanupOldBuilds.sh] > \
+
          $HOME/cron_logs/cleanupOldBuilds.sh.emft.log.txt
+
 
+
The rules, as defined in the script, are:
+
 
+
# purge builds in OLD/ folder older than 30 days
+
# move [N] builds older than 10 days into OLD/
+
# move [IMS] builds older than 60 days into OLD/ (keep R builds!)
+
# purge old dependency downloads older than 20 days
+
 
+
====Manual Delete From Production Server (download.eclipse.org)====
+
 
+
When deleting from dev.eclipse.org (or download1.eclipse.org), you do not need to sudo to the web user:
+
 
+
cd /home/data/httpd/download.eclipse.org/technology/emft/''[subproject]''/downloads/drops/1.0.0;
+
rm -fr N200604152353;
+
 
+
====Archiving Builds on Production Server (download.eclipse.org)====
+
 
+
Nightly builds can just be destroyed, but consumers of your component may have longer-term dependencies
+
on Integration builds.  After a couple of releases, maybe even milestone builds want to be cleared away.
+
This can all be accomplished safely by '''archiving''' a build.  A build that is in the archive doesn't
+
take up space on the main Eclipse download server or its mirrors, but is still accessible in the event
+
that it is needed via the ''download.php?file=/path/to/zipfile.zip'' URL.
+
 
+
Simply move your build from from the main download area to the archive area:
+
 
+
cd /home/data/httpd/'''download'''.eclipse.org/technology/emft/''[subproject]''/downloads/drops/''[release]''/''[buildID]''
+
mkdir -p /home/data/httpd/'''archive'''.eclipse.org/technology/emft/''[subproject]''/downloads/drops/''[release]''
+
mv ''[buildID]'' /home/data/httpd/'''archive'''.eclipse.org/technology/emft/''[subproject]''/downloads/drops/''[release]''/
+
 
+
and you're done!
+
 
+
===Removing Update Manager Jars===
+
 
+
Update Manager jars should be purged from build and production servers with the same frequencies as above.
+
 
+
====Remove Jar Files====
+
 
+
To get a list of jars (ordered by modification time) that are older than a certain age (eg., 14 days), run:
+
 
+
  cd /home/data/httpd/download.eclipse.org/technology/emft/updates;
+
  find . -maxdepth 2 -type f -name "*eodm*" -mtime +'''''14''''' \
+
    -exec date -r {} +%s\ {} \; | sort -r | sed -e "s/[0-9]\+\ \.\///g";
+
 
+
Then, if you are satisfied with that list, delete them like this:
+
 
+
  for f in \
+
    `find . -maxdepth 2 -type f -name "*eodm*" -mtime +'''''14''''' \
+
      -exec date -r {} +%s\ {} \; | sort -r | sed -e "s/[0-9]\+\ \.\///g"`; do \
+
        echo "Delete: "$f; rm -fr $f; \
+
  done
+
 
+
====Remove Entries From site*.xml====
+
 
+
In addition to deleting jars, you must also remove the entries from [http://download.eclipse.org/tools/emf/updates/site-interim.xml site-interim.xml]. This file must be edited in CVS then checked out to the local filesystem to cause the removed builds to disappear.
+
 
+
If you do not update the file in CVS, but only edit it locally, the next UM jar build will recreate the removed entries since it extracts the latest version of that file from CVS before adding to it. To update the file in CVS and push it to eclipse.org, ssh to your build server or to any machine that can ssh to dev.eclipse.org, then:
+
 
+
cd /tmp;
+
cvs -d ''[eclipse_id]''@dev.eclipse.org:/cvsroot/org.eclipse \
+
  -q co -d updates www/emft/updates;
+
cd /tmp/updates;
+
 
+
# edit file: use '''dd''' to delete lines, ''':wq''' to save & quit
+
vi site-interim.xml;
+
cvs -q ci -m "remove old builds";
+
 
+
scp site-interim.xml \
+
  ''[eclipse_id]''@dev.eclipse.org:/home/data/httpd/download.eclipse.org/technology/emft/updates
+
cd /tmp; rm -fr /tmp/updates;
+
 
+
Of course, you can also edit the file in Eclipse or another editor, commit those changes, then check out the latest files and scp them to download.eclipse.org as shown above.
+
 
+
 
+
===Build.php Dependency URL Cleanup===
+
 
+
To remove old dependency URLs shown on your build.php page, edit the following file on your build server:
+
 
+
  sudo -u ''[web_user]'' vi /home/www-data/build/emft/requests/dependencies.urls.txt
+
 
+
Note that the most recent entries are listed at the bottom of the file, so delete from the top down (starting on line 3). If you delete too many, you can always re-add them using the web UI of build.php.
+
 
+
 
+
=== Removing or Replacing a Bad Build ===
+
 
+
Yes, it happens. You need to trash a milestone build and replace it with an M5a version. We've been there. Here's the steps you need to follow to make a bad build vanish forever using a hypothetical example.
+
 
+
* SSH to download1.eclipse.org and delete the bad build's folder.
+
 
+
cd /home/data/httpd/download.eclipse.org/modeling/mdt/uml2/downloads/drops/2.1.0
+
rm -fr I200704091234
+
 
+
* Delete the build from the build server too.
+
 
+
* Check out your project's RSS feed from CVS, remove the bad entry, and commit your changes. When you promote the replacement build, this file will be promoted to the correct place on download1.eclipse.org. The RSS feed controls what releases are loaded in the Search CVS / Release Notes database, so you must remove the bad entry.
+
 
+
cd /tmp;
+
cvs -d '''''username'''''@dev.eclipse.org:/cvsroot/org.eclipse -q co -d feeds \
+
  www/modeling/mdt/feeds
+
cd feeds;
+
vi builds-uml2.xml
+
cvs ci -m "remove bad build" builds-uml2.xml
+
 
+
* If you're not replacing your bad build w/ a fixed one, you'll have to manually upload the RSS feed file; otherwise, your next build will perform this step for you:
+
 
+
  scp builds-uml2.xml \
+
  '''''username'''''@download1.eclipse.org:/home/data/httpd/download.eclipse.org/modeling/mdt/feeds/
+
 
+
* Delete the entry from the releases table of the Search CVS database so it will vanish from the Release Notes. Use [http://build.eclipse.org/modeling/mdt/build/removeRelease.php this webpage]. If you don't see your build listed, then it hasn't been loaded yet, and you can safely skip this step.
+
 
+
* Rebuild. Promote your new build, sit back, and call it a day.
+
 
+
----
+
 
+
(Thanks to http://diberri.dyndns.org/html2wiki.html for assisting in migrating this document.)
+
 
+
[[Category:Modeling]] [[Category:EMFT]] [[Category:Releng]]
+

Latest revision as of 18:22, 29 August 2007