::* genBuildDetails.sh is called from [http://dev.eclipse.org/viewcvs/index.cgi/releng-common/tools/scripts/start.sh?root=Modeling_Project&view=markup start.sh], which is what starts the build.

::* genBuildDetails.sh is called from [http://dev.eclipse.org/viewcvs/index.cgi/releng-common/tools/scripts/start.sh?root=Modeling_Project&view=markup start.sh], which is what starts the build.

:::* start.sh is in turn called by the [http://dev.eclipse.org/viewcvs/index.cgi/www/modeling/emft/compare/build/index.php?root=Eclipse_Website&view=markup build website] ([[Modeling_Project_Releng/Building#Running_Builds|screenshot]]); however, to properly collect dependencies you need to also define targets in the findCatg method of [http://dev.eclipse.org/viewcvs/index.cgi/www/modeling/build/build-common.php?root=Eclipse_Website&view=markup build-common.php]

:::* start.sh is in turn called by the [http://dev.eclipse.org/viewcvs/index.cgi/www/modeling/emft/compare/build/index.php?root=Eclipse_Website&view=markup build website] ([[Modeling_Project_Releng/Building#Running_Builds|screenshot]]); however, to properly collect dependencies you need to also define targets in the findCatg method of [http://dev.eclipse.org/viewcvs/index.cgi/www/modeling/build/build-common.php?root=Eclipse_Website&view=markup build-common.php]

+

* Note that after updating genBuildDetails.sh and build-common.php you'll need to update the build machine following [[Modeling_Project_Releng/Website_Maintenance#Maintaining_CVS_Synch|Maintaining CVS Synch]]. Even still, you'll need to run a build adding the URL of the new dependency before a placeholder will appear in the dependencies list.

+

+

====Using PDE Packager ====

+

+

PDE Build provides a way to repackage existing (pre-built) features into arbitrary archives. This is useful if you want to build zip files with several top-level features (rather than just one feature). See [http://help.eclipse.org/ganymede/topic/org.eclipse.pde.doc.user/tasks/pde_packager.htm Repackaging Eclipse Components] for more information.

+

+

In order to use this tool you should have an existing build process that produces a single "master" feature zip with all features/plugins that you want to use as a starting point for repackaging. Configuring the packager is similar to configuring the builder: you will need a packager configuration directory for each package you want to produce. For instance, [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint.releng/builder/sdk/packager/?root=Modeling_Project Mint's SDK package] contains [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint.releng/builder/sdk/packager/packager.properties?root=Modeling_Project&view=markup packager.properties] (as opposed to build.properties), [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint.releng/builder/sdk/packager/packaging.properties?root=Modeling_Project&view=markup packaging.properties], and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint.releng/builder/sdk/packager/customTargets.xml?root=Modeling_Project&view=markup customTargets.xml]. All three are very template-like, but you need to make the following changes for your specific configuration:

+

+

: 1. In packager.properties, change property ''archiveNamePrefix'' to customize the name of your zip file (the final name is set in customTargets.xml to ${archiveNamePrefix}-${buildAlias}.zip) and set property ''featureList'' to a comma-separated list of IDs of the features you want to include in the archive.

+

: 2. Optionally, update packaging.properties to include additional files in the root of the archive.

+

+

In order to run the packager you must make [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.mint.releng/buildAll.xml?root=Modeling_Project&r1=1.13&r2=1.22 some changes] to your master build file:

This is required in order to manually build up your ''target platform'' that is used during packaging (much like for building, except everything must be in the binary form rather than source).

+

: 3. Populate a ''target directory'' with all your built features/plugins as well as their dependencies. The dependencies should technically not be needed at this point, but the packager requires them in order to function properly. E.g.,

Make sure you do this *after* all your jars have been signed; otherwise your zip will contain unsigned jars (and go ahead, ask Bjorn if that's OK ;-) )

+

: 4. Replace all your zip tasks that build your sdk/runtime/example archives with a corresponding call to the packager:

+

<antcall target="package">

+

<param name="packagingInfo" value="builder/sdk/packager" />

+

</antcall>

+

: 5. Lastly, move the code to build your tests *before* you run the packager, but *after* you build the master zip. This is required due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=240716 Bug 240716] -- the master builder sets the output form of all features to be jars while the packager needs them to stay unpacked (i.e., directories). This bug causes the first setting to remain in effect and your packager will produce jarred features, unless another builder resets it (e.g., the tests builder, which doesn't produce jarred features).

===Using Third Party Jars===

===Using Third Party Jars===

Line 148:

Line 200:

</patternset>

</patternset>

</unzip>

</unzip>

+

+

To ship Orbit jars with your zips, you'll need to explicitly add them into your zips.

+

+

* Add code such as this to the "postAssemble" target of your [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.ocl.releng/builder/all/customTargets.xml?root=Modeling_Project&view=diff&r1=1.3&r2=1.4 customTargets.xml] file.

* Note that in this specific example, <code>${LPGRuntimeVersion}</code> is defined in [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.ocl.releng/buildAll.xml?root=Modeling_Project&view=diff&r1=1.59&r2=1.60 buildAll.xml] and stored as a property in the generated build.cfg file so that it's accessible to all Ant scripts.

====Using Non-Orbit Jars====

====Using Non-Orbit Jars====

−

If you need to use third party jars during your build, but don't want to (or can't) ship them due to licensing or other reasons, here's how:

+

If you need to use third party jars during your build, but don't want to (or can't) ship them due to licensing or other reasons, here's how.

+

+

{{warning2|text=

+

PLEASE ENSURE you are not violating any EULAs or applying encroaching licenses to your EPL work by simply USING any third party jars!

:If you cannot ssh to your build server (eg., emft.eclipse.org) directly, repeat the above process for scp'ing your file(s) to dev.eclipse.org, then scp those files from there to emft.eclipse.org. Be sure to delete your temp files in both locations!

* If you ever get a stuck thread (eg., you forget to kill the Xvfb process) you can manually kill it like this:

* If you ever get a stuck thread (eg., you forget to kill the Xvfb process) you can manually kill it like this:

Line 374:

Line 455:

* To sign your jars using the jarsigner on build.eclipse.org, and/or to pack your jars using Pack200, see [[Modeling Project Releng/Building/Signing And Packing]].

* To sign your jars using the jarsigner on build.eclipse.org, and/or to pack your jars using Pack200, see [[Modeling Project Releng/Building/Signing And Packing]].

+

+

===All-In-One Bundles===

+

+

See [[Modeling_Project_Releng/Building/All-In-Ones|All-In-Ones]]. Note that a better approach is probably to use the [[EPP/How_to_create_a_package|EPP system]] or to include yourself in the latest coordinated release, eg., [[Galileo]].

:* See [[#Controling the appearance of your build page | above]]: change the value of this entry:

:* See [[#Controling the appearance of your build page | above]]: change the value of this entry:

−

"BaseBuilderBranch" => "M1_34"

+

"BaseBuilderBranch" => "M7_34"

====Scheduling Automated Builds====

====Scheduling Automated Builds====

Line 426:

Line 511:

In no particular order, here are some lessons learned from setting up builds:<br /><br />

In no particular order, here are some lessons learned from setting up builds:<br /><br />

+

+

====Built features & plugins have "HEAD" in their version qualifier ====

+

+

[[Image:Ecoretools-built-from-HEAD.png]]

+

+

There are two ways to control the naming of your features & plugins.

+

+

The simplest is to set this code in your buildAll.xml, before you load your label.properties file:

+

+

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

+

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

+

forceContextQualifier=${forceContextQualifier}

+

</echo>

+

<echo message="forceContextQualifier=${forceContextQualifier}" />

+

+

<property file="${buildDirectory}/label.properties" />

+

+

This will make all your plugins and features have the same qualifier, eg., 0.8.0.v200804211234 (and any optional suffixes).

+

+

If, however, you want more fine-grained control, or to NOT always build from HEAD but from tags you specifically set, you can use the [http://download.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/index.php#org.eclipse.releng Eclipse Releng Tool] to tag & release your features & plugins individually ([http://download.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/details.php#org.eclipse.releng more info]). By doing so, your [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gmf/org.eclipse.gmf.releng/maps/?root=Modeling_Project map file(s)] will contain the specific versions of features & plugins which are to be contributed to your build. Please use the convention "vYYYYMMDD" or "vYYYYMMDDhhmm" when tagging in order to ensure that your updated features & plugins will be treated as newer by Update Manager.

====Build fails, stalls, or tests never complete====

====Build fails, stalls, or tests never complete====

Line 483:

Line 588:

* 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.

* 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 that missed plugins contain build.properties file.

* Ensure all properties files and MANIFEST.MF files have a trailing newline at the end of the file.

* 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]

* 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]

Line 510:

Line 616:

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].

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].

+

+

====Features do not include extended suffixes====

+

+

Extended suffixes allow you to have a feature whose contents do not change, but whose version increments every time the included artefacts (plugins, subfeatures) do change. So, for example, if your SDK feature's contents have not changed since 1.0.4 but some or all of the included plugins are now at 1.1.0, you need not release a 1.1.0 version of your feature simply to allow your users to be able to install the updated plugins from the feature. The suffix will make the OSGi name of the feature "newer".

then you need to enable feature version suffix generation. In your [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mdt/org.eclipse.ocl.releng/builder/all/build.properties?root=Modeling_Project&view=annotate .releng/builder/*/build.properties], add:

+

+

{{codeblock|<nowiki>generateFeatureVersionSuffix=true</nowiki>}}

+

+

====Sources not found when installed by p2 (Eclipse 3.4M6+)====

+

+

If you've recently moved up to the latest Eclipse 3.4M6 or later, and have tried to install some SDK only to discover that the sources aren't found, you need to implement this change in your source plugins' MANIFEST.MF files:

Another cause can be the memory usage of component-specific build steps. If your component launches separate processes with their own jvm, you need to performance tune those steps. [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.teneo.releng/builder/examples/customTargets.xml?root=Modeling_Project&r1=1.21&r2=1.22&diff_format=u Here's an example].

Another cause can be the memory usage of component-specific build steps. If your component launches separate processes with their own jvm, you need to performance tune those steps. [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf.teneo.releng/builder/examples/customTargets.xml?root=Modeling_Project&r1=1.21&r2=1.22&diff_format=u Here's an example].

+

+

====Adding a new dependency====

+

+

Sometimes we need to create a feature which depends on third-party plugins the rest of our projects don't need. For example, we might need an "integration" feature for our project to behave correctly with a given plugin, but we don't want users to be forced to download this dependency. In such cases we create new features and build targets as shown above in [http://wiki.eclipse.org/index.php?title=Modeling_Project_Releng/Building#Option_A customizing zip bundles].

+

+

To add the dependency, simply change the target "postSetup" of your customTargets.xml. For exemple to add a dependency on EMF Compare, add

so that it will fetch the build infrastructure will know you wish to retrieve EMF Compare to build this particular target. '''Note''' however that this will ''not'' work for plugins distributed as update sites. For such dependencies, you will need to call "getUpdateSiteDependency" instead of "getDependency". For exemple, to add a dependency towards subversive, you can use :

However, as recently discovered, this won't actually turn [http://java.sun.com/j2se/1.5.0/docs/guide/language/assert.html Assertions] on, because each test plugin forks a separate thread for its tests, and does not forward this flag to that process.

+

+

2. test.xml, the script that each test plugin uses to define which tests to run

Note that to run tests with Assertions locally in Eclipse you have to add the VM argument "-ea" to the Run or Debug Configuration on the Arguments tab.

+

+

====Cannot find a test suite's console log (.metadata/.log)====

+

+

To capture the console logs for each independent test suite (.metadata/.log from the test's workspace), you need to edit the <code>cleanup</code> target of each test plugin's [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/tests/org.eclipse.emf.test.build/test.xml?root=Modeling_Project&r1=1.3&r2=1.6 test.xml]. Make sure that <code>${classname}</code> is globally defined.

Now, after your tests run, you'll get one more log file (for each test.xml you change) in your build folder's testresults/consolelogs/ folder. For easy access, these new logs will appear on that build's Test Results page, linked from your downloads page.

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].

+

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/index.cgi/org.eclipse.emf/org.eclipse.emf.releng/builder/tests/customTargets.xml?root=Modeling_Project&content-type=text%2Fxml&view=co tests/customTargets.xml] and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/tests/org.eclipse.emf.tests-feature/feature.xml?root=Modeling_Project&content-type=text%2Fxml&view=co <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].

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].

After 03/05, Eclipse ships with [[Equinox p2 Getting Started|p2]]. This changes the way that features and plugins can be naively installed into an Eclipse install. Instead of unzipping into eclipse/features/ and eclipse/plugins, you now have to unzip into eclipse/dropins/eclipse/features/ and eclipse/dropins/eclipse/plugins/.

+

After 03/05, Eclipse ships with [[Equinox p2 Getting Started|p2]]. This changes the way that features and plugins can be naively dropped into an Eclipse install. Instead of unzipping into eclipse/features/ and eclipse/plugins/, you now have to unzip into eclipse/dropins/eclipse/features/ and eclipse/dropins/eclipse/plugins/.

−

To convert your tests to use this new path, [http://www.eclipse.org/modeling/emf/searchcvs.php?q=file%3Agef+author%3Anickb+startdate%3A2008-03-26+19%3A58%3A41+enddate%3A2008-03-27+00%3A21%3A06&project=0&fullpath=Y see this example].

+

To convert your releng.basebuilder-based automated JUnit tests to use this new path, [http://www.eclipse.org/modeling/emf/searchcvs.php?q=file%3Agef+author%3Anickb+startdate%3A2008-03-26+19%3A58%3A41+enddate%3A2008-03-27+00%3A21%3A06&project=0&fullpath=Y see this example].

:* o.e.foo.test.*/test.xml (one test.xml for each of your test plugins)

:* o.e.foo.test.*/test.xml (one test.xml for each of your test plugins)

'''NOTE''': As of the 03/27 Eclipse Platform build, this conversion is no longer mandatory ''though still recommended'', as [http://dev.eclipse.org/mhonarc/lists/cross-project-issues-dev/msg02188.html p2 has been enhanced to search for dropins in the root eclipse/ folder as well as the dropins/ folder].

[[Category:Modeling]] [[Category:Releng]]

[[Category:Modeling]] [[Category:Releng]]

Latest revision as of 07:20, 18 June 2009

We use the Eclipse build process which relies on PDE. See this article if you are interested in the details. It also covers the JUnit automated tests that can be run during the build.

Incubation Status

For example, here are the changes required to make EMF Compare compliant: Search CVS results

1. All downloadable zip files for builds and milestones must include the word incubation in the filename. For example, emft-compare-SDK-incubation-N200708031343.zip. The jar files in the download zip file are NOT required (bug 178944) to contain the word incubation in the filename.

2. All Bundle-Names must include the word incubation. Note that Bundle-SymbolicNames should not include incubation because the Bundle-SymbolicName is a technical namespace, not a user namespace. For example, Bundle-Name: Foo Plug-in (Incubation).

4. In order to correctly generate the label for your update site categories/features, your promoteToEclipse.*.properties file must correctly reference your zips with "incubation" in their title. For example:

# used to determine the actual name of the SDK zip (when builds are aliased)
SDKfilenamepattern="$projectName-$subprojectName-SDK-incubation-*.zip"

When a project exits incubation, above changes should be reversed to remove the incubation 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 CVS. An example of this is org.eclipse.emf-feature/org.eclipse.emf.sdk. It is nested (rather than being its own org.eclipse.emf.[subproject].[bundlename]-feature) for cosmetic reasons (it looks in the file system).

When creating a new org.eclipse.emf.[subproject]-feature/org.eclipse.emf.[subproject].[bundlename] (or org.eclipse.emf.[subproject].[bundlename]-feature), 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 customTargets.xml and a build.properties file. Then make sure that customTargets.xml refers to the feature correctly, as in customTargets.xml. (Search for "sdk" on lines 9, 20, 187.)

2. Then, the buildAll.xml script must be told how to build the new zip, eg, buildAll.xml (line 139):

Add an entry such as (line break added for clarity):feature@org.eclipse.emf.validation.sdk=@cvsTag@,@cvsRoot1@,,org.eclipse.emft/validation/plugins/ org.eclipse.emf.validation-feature/org.eclipse.emf.validation.sdk

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 buildAll.xml 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 validation.ocl plugin which must be included in the validation runtime, but since the validation-feature makes no mention of it, it's excluded. So, to work around this, once the SDK is built, copy the validaton.ocl plugin & feature from the SDK zip to the runtime zip after its assembly. This is done in the org.eclipse.emft/releng/validation/buildAll.xml script:

Bear in mind that you must ensure that everything you need to compile is available. You will need to edit all the customTargets.xml files that are used to build code which depends on the new reqiurement. See target "postSetup".

Note that after updating genBuildDetails.sh and build-common.php you'll need to update the build machine following Maintaining CVS Synch. Even still, you'll need to run a build adding the URL of the new dependency before a placeholder will appear in the dependencies list.

Using PDE Packager

PDE Build provides a way to repackage existing (pre-built) features into arbitrary archives. This is useful if you want to build zip files with several top-level features (rather than just one feature). See Repackaging Eclipse Components for more information.

In order to use this tool you should have an existing build process that produces a single "master" feature zip with all features/plugins that you want to use as a starting point for repackaging. Configuring the packager is similar to configuring the builder: you will need a packager configuration directory for each package you want to produce. For instance, Mint's SDK package contains packager.properties (as opposed to build.properties), packaging.properties, and customTargets.xml. All three are very template-like, but you need to make the following changes for your specific configuration:

1. In packager.properties, change property archiveNamePrefix to customize the name of your zip file (the final name is set in customTargets.xml to ${archiveNamePrefix}-${buildAlias}.zip) and set property featureList to a comma-separated list of IDs of the features you want to include in the archive.

2. Optionally, update packaging.properties to include additional files in the root of the archive.

In order to run the packager you must make some changes to your master build file:

This is required in order to manually build up your target platform that is used during packaging (much like for building, except everything must be in the binary form rather than source).

3. Populate a target directory with all your built features/plugins as well as their dependencies. The dependencies should technically not be needed at this point, but the packager requires them in order to function properly. E.g.,

5. Lastly, move the code to build your tests *before* you run the packager, but *after* you build the master zip. This is required due to Bug 240716 -- the master builder sets the output form of all features to be jars while the packager needs them to stay unpacked (i.e., directories). This bug causes the first setting to remain in effect and your packager will produce jarred features, unless another builder resets it (e.g., the tests builder, which doesn't produce jarred features).

Using Third Party Jars

You are welcome to take advantage of third party code, but bear in mind these rules:

1. Third partycode must be submitted to IPzilla for legal clearance before being committed to CVS.

2. Many third party libraries are available via the Orbit project, and so can be added to the project at build time (rather than needing to be duplicated in CVS).

If you cannot ssh to your build server (eg., emft.eclipse.org) directly, repeat the above process for scp'ing your file(s) to dev.eclipse.org, then scp those files from there to emft.eclipse.org. Be sure to delete your temp files in both locations!

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:

You can also bring up that same help page in Eclipse's built-in help (JDT Plug-in Developer Guide > Programmer's Guide > JDT Core > Compiling Java code) 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
build.properties 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 build.properties. 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 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 buildAll.xml file.
Simply remove that and the javacSource=1.4 entries from the build.properties files in each builder/* folder. For example, see in the Query component's releng:

These two files control how the build behaves as far as defining what goes in (upstream zip dependencies, CVS sources) as well as other options, environment variables and properties. The config file is also where ${fooFile} and ${fooURL} ant variables are defined.

This will make all your plugins and features have the same qualifier, eg., 0.8.0.v200804211234 (and any optional suffixes).

If, however, you want more fine-grained control, or to NOT always build from HEAD but from tags you specifically set, you can use the Eclipse Releng Tool to tag & release your features & plugins individually (more info). By doing so, your map file(s) will contain the specific versions of features & plugins which are to be contributed to your build. Please use the convention "vYYYYMMDD" or "vYYYYMMDDhhmm" when tagging in order to ensure that your updated features & plugins will be treated as newer by Update Manager.

If that doesn't solve the problem, run a debug build with the -noclean flag checked to see what's in the eclipse/tmp/eclipse/plugins/ folder. For the case of the above build, the folder created was called org.eclipse.emf.ocl.doc_${pluginVersion}.200602231617 instead of org.eclipse.emf.ocl.doc_1.0.0.200602231617, since the property was not defined.

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 org.eclipse.emft.mwe.sdk, but rather org.eclipse.emf.mwe.sdk.

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, click here" 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.

Build is ok, everything compiles, but plugins are missing from the SDK

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., org.eclipse.net4j-feature/feature.xml), even if it contains NO source and that you've set that plugin to be unpack="false":

Plugin jars contain nested jars instead of class files

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

publish.xml fails to generate build artefacts

This has been deprecated in the latest org.eclipse.releng.basebuilder. For the solution, see details in bug 165698.

Features do not include extended suffixes

Extended suffixes allow you to have a feature whose contents do not change, but whose version increments every time the included artefacts (plugins, subfeatures) do change. So, for example, if your SDK feature's contents have not changed since 1.0.4 but some or all of the included plugins are now at 1.1.0, you need not release a 1.1.0 version of your feature simply to allow your users to be able to install the updated plugins from the feature. The suffix will make the OSGi name of the feature "newer".

Sources not found when installed by p2 (Eclipse 3.4M6+)

If you've recently moved up to the latest Eclipse 3.4M6 or later, and have tried to install some SDK only to discover that the sources aren't found, you need to implement this change in your source plugins' MANIFEST.MF files:

java.lang.NoClassDefFoundError: org/eclipse/core/launcher/Main

Out Of Memory Errors

This can be related to the memory available to the build process itself. The build is started via your component's build page, which collects properties and settings and passes them to the start.sh script.

To increase the available memory set the -Xmx parameter in the start.sh script (see Invoking Eclipse build...). Note that this script is shared by everyone on the server, so if at some point it's discovered that we need to change the global settings here, this is the place to change it by submitting a patch. On the other hand, if your build has memory requirements that are very different from others, submit a request to have memory and permgen settings for all builds a per-build configurable parameter.

Another cause can be the memory usage of component-specific build steps. If your component launches separate processes with their own jvm, you need to performance tune those steps. Here's an example.

Adding a new dependency

Sometimes we need to create a feature which depends on third-party plugins the rest of our projects don't need. For example, we might need an "integration" feature for our project to behave correctly with a given plugin, but we don't want users to be forced to download this dependency. In such cases we create new features and build targets as shown above in customizing zip bundles.

To add the dependency, simply change the target "postSetup" of your customTargets.xml. For exemple to add a dependency on EMF Compare, add

so that it will fetch the build infrastructure will know you wish to retrieve EMF Compare to build this particular target. Note however that this will not work for plugins distributed as update sites. For such dependencies, you will need to call "getUpdateSiteDependency" instead of "getDependency". For exemple, to add a dependency towards subversive, you can use :

Note that to run tests with Assertions locally in Eclipse you have to add the VM argument "-ea" to the Run or Debug Configuration on the Arguments tab.

Cannot find a test suite's console log (.metadata/.log)

To capture the console logs for each independent test suite (.metadata/.log from the test's workspace), you need to edit the cleanup target of each test plugin's test.xml. Make sure that ${classname} is globally defined.

Now, after your tests run, you'll get one more log file (for each test.xml you change) in your build folder's testresults/consolelogs/ folder. For easy access, these new logs will appear on that build's Test Results page, linked from your downloads page.

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: tests/customTargets.xml and *.tests-feature/feature.xml. 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.

If you have checked all these conditions and still get an error, make sure 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 190834 and 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.

eclipse/test.assembly/eclipse/ plugins/org.eclipse.test_3.1.0 not found

Ensure that you're unpacking your junit-tests zip properly. If you've just switched to/from the "incubation" filename convention, ensure that the value for ${archiveName} is set correctly. See this example.

Could not create the Java virtual machine

Check relengbuildgtk.sh, and make sure the $cp or $cpAndMain variable is being set correctly. Also, make sure that if you're building with Eclipse 3.2 you use org.eclipse.core.launcher.Main instead of Eclipse 3.3's org.eclipse.equinox.launcher.Main. See also Running Eclipse and PDE JUnit Testing.

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 unpack="false" from the org.eclipse.emf.*.tests plugin: <plugin id="org.eclipse.emf.ocl.tests" download-size="0" install-size="0" unpack="false" version="1.0.0"/>

Must define 'org.foo.ui.test.suite=org.foo.ui.test.AllTests' in your .releng/testing.properties

If you have created testing.properties but still get the error, check that the testPluginsToRun list doesn't contain whitespaces. See bug 280747

Don't forget to verify as well you added test.xml in your build.properties.

java.lang.Exception: Could not find plugin "org.eclipse.emf.mwe.tests"

If you can build without running tests (uncheck the JUnit Tests checkbox on the build page), but when you try to run the tests you get a 'Could not find plugin' error for your test plugin, you may be missing dependencies in your test environment. There are two places to check, and to add missing runtime dependencies:

JUnits do not run with p2-enabled Eclipse

After 03/05, Eclipse ships with p2. This changes the way that features and plugins can be naively dropped into an Eclipse install. Instead of unzipping into eclipse/features/ and eclipse/plugins/, you now have to unzip into eclipse/dropins/eclipse/features/ and eclipse/dropins/eclipse/plugins/.

To convert your releng.basebuilder-based automated JUnit tests to use this new path, see this example.