EMF/EMF 2.3/Adoption

Unfortunately, my scripting capabilities aren't what they should be. So, instead, find here a step-by-step guide to adopting EMF 2.3 and J2SDK 5.0 in your EMFT builds (or a build based on the EMFT build scripts).

Actually adopting EMF 2.3 is as simple as selecting a 2.3 build from the list of dependencies in the build tool. The rest of this page is all about building with J2SDK 5.0.

Branch your Releng Folder

I am assuming that you are adopting J2SDK 5.0/EMF 2.3 on the HEAD branch of your project. If you haven't already created a maintenance branch on your releng project (org.eclipse.emf.*.releng), you will want to do that now. Otherwise, the changes you make in the following steps will apply to the builds of the maintenance branch(es) of your previous release(s).

Just use the same branch name and root tag as you used the last time that you branched your source projects.

For example, if you're working on 1.0.x builds, use the tag R1_0_maintenance for both your code and your releng. The build page will assume that if you're building from R1_0_maintenance that your releng code will come from the same place. Running your build in debug mode will allow you to override this, if ever necessary in future, or if you ever want to use a tag instead of a branch. When branching your releng code, pick only the folder that your code resides in, such as, for OCL, /org.eclipse.emft/releng/ocl/. DO NOT tag the common code, /org.eclipse.emft/releng/common/.

If you don't have permission to branch this code, please contact your administrator.

If you had already branched, then chances are that the patch you applied for bug 159212 also needs to be applied to your maintenance branch. Check now that it was. In particular, searching for transientPropertiesFile should find no hits (this patch did away with the transient properties file).

Use the J2SDK 5.0 Version of the Doclet

EMF provides a version of the doclet that creates the topics_Reference.xml file in your doc plug-in specifically for J2SDK 5.0. First, try the following in build/javadoc.xml.template file:

<target name="javadoc">
   <echo message="Get Doclet and compile it with JDK5.0 for use with javadoc"/>
   <cvs cvsRoot=":pserver:anonymous@dev.eclipse.org:/cvsroot/tools" 
     package="org.eclipse.emf.releng.build/org.eclipse.emf.build" 
     reallyquiet="yes"/>
   <delete dir="org.eclipse.emf.releng.build/org.eclipse.emf.build/src/CVS"/>
   <move todir="."><fileset dir="org.eclipse.emf.releng.build/org.eclipse.emf.build/src"/></move>
   
   <javac srcdir="org/eclipse/emf/build/doclet" classpath=".:${java.home}/../lib/tools.jar" failonerror="true"/>

(i.e., remove the reference to the tag="R2_2_maintenance" to check out to get the J2SDK 1.4 version).

If that doesn't work (the doclet wouldn't compile for me with my J2SDK 5.0 distribution), then just comment it out altogether:

<target name="javadoc">
   <!--  Doesn't compile with 5.0
   <echo message="Get Doclet and compile it with JDK5.0 for use with javadoc"/>
   <cvs cvsRoot=":pserver:anonymous@dev.eclipse.org:/cvsroot/tools" 
     package="org.eclipse.emf.releng.build/org.eclipse.emf.build" 
     reallyquiet="yes"/>
   <delete dir="org.eclipse.emf.releng.build/org.eclipse.emf.build/src/CVS"/>
   <move todir="."><fileset dir="org.eclipse.emf.releng.build/org.eclipse.emf.build/src"/></move>
   
   <javac srcdir="org/eclipse/emf/build/doclet" classpath=".:${java.home}/../lib/tools.jar" failonerror="true"/>
   -->

and below that, in the <javadoc> tag, comment out the doclet reference:

    <!-- Doesn't compile with 5.0
    <doclet name="org.eclipse.emf.build.doclet.Doclet" path=".">
    <param name="-tocFilename" value="topics_Reference.xml"/>
    <param name="-tocRefPrefix" value="references/javadoc/"/>
    <param name="-tocTitle" value="API Reference"/>
    </doclet>
    -->

In this case, because the doclet was responsible for generating an import TOC file, we need an alternative way to do that. The following appended to the end of your build/antJavadoc.sh script will suffice (see the attachment to bug 163877):

# Generate topics_Reference.xml (replacement for doclet). 
trXML=$currentPath"/../topics_Reference.xml";
echo '<?xml version="1.0" encoding="UTF-8"?>' > $trXML;
echo '<?NLS TYPE="org.eclipse.help.toc"?>' >> $trXML;
echo '<toc label="Reference">' >> $trXML;
echo '  <topic label="API Reference" href="references/javadoc/overview-summary.html">' >> $trXML;
for packSum in `find $destDir -name "package-summary.html" | sort`; do
	path=${packSum%/package-summary.html}; path=${path#$destDir/}; # org/eclipse/xsd/ecore/importer/taskdefs
	label=${path//\//.}; # org.eclipse.xsd.ecore.importer.taskdefs
	echo '    <topic label="'$label'" href="references/javadoc/'$path'/package-summary.html" />' >> $trXML;
done
echo '  </topic>' >> $trXML;
echo '</toc>' >> $trXML;

Update the JUnit Testing

Now that we are building with J2SDK 5.0, we also want to test with it. In the builder/tests/configs/local/testing.properties file in your releng project, change the following properties (they don't all appear together, as shown):

# instead of downloading and unpacking the JDK each time, just reuse the symlinked one in /opt/
vmExecutable=/opt/ibm-java2-1.4/jre/bin/java

#extra vm flags
Xflags=-Xj9 -Xms256M -Xmx256M

to the following:

# instead of downloading and unpacking the JDK each time, just reuse the symlinked one in /opt/
vmExecutable=/opt/sun-java2-5.0/jre/bin/java

#extra vm flags
Xflags=-Xms256M -Xmx256M

Set javac Source (javacSource) and Target (javacTarget) Properties

Look in your *.xml and *.properties files for entries like:

 <property name="javacSource" value="1.5"/>
 <property name="javacTarget" value="1.5"/>

or

javacSource=1.5
javacTarget=1.5

If you see the equivalent assignments with "1.4", change them to "1.5" or "5.0". If you see neither and your build fails (in the next step), try adding these directives where appropriate.

Start your Build

Voilà! You are now ready to test your build. Thanks to fixes by Nick in the automagic selection of which branch of the releng project is used to build your component, you need only to select in the build page:

• the "HEAD | 1.1.0 | /opt/sun-java2-5.0" branch from the drop-down list
• your component (obviously!)
• an EMF 2.3 build
• Eclipse 3.3M3 or later

and hit the Build button. If you do not already have an appropriate branch, release number, and JDK combination in the drop-down-list, you will need to add it to the www/emft/build.options.txt file in the eclipse.org CVS repository. e.g:

1.1.0=HEAD,/opt/sun-java2-5.0

Required Execution Environment

EMF 2.3 requires JDK1.5 as a minimum requirement. If you'd like to force the same requirement on your plugins, add this line to the end of your MANIFEST.MF files:

Bundle-RequiredExecutionEnvironment: J2SE-1.5

Just make sure there's an empty line at the end of the file too.