Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Callisto Build and Update Tips and Tricks
On this page, please add any little tidbits that help with the versioning, site management, etc., that are not part of other documents.
Contents
Automatically versioning features appropriately
I haven't tried it yet, but in [| bug 125801 Andrew Niefer mentions that
<p>
When using ".qualifier", the resulting feature version can take the form of
1.2.3.qualifier_suffix, where qualifier will come from the cvs tag, or date the
same as for plugins. suffix will be generated based on the qualifiers of the
contained plugins.
Whether or not to append the _suffix to the version is controlled by the
property "generateFeatureVersionSuffix" in the builder's build.properties. The
default value is false.
I personally feel that generateFeatureVersionSuffix should be the default, but since it isn't, thought I'd document here.
This is important since a feature's qualifier needs to not just change accourding to its own changes, but also needs to reflect the "most changed" plugin it contains.
- For more on how to set up qualifiers in your PDE-based build, look here: EMFT Procedures (Qualifiers).
- -- Codeslave.ca.ibm.com 13:16, 7 June 2006 (EDT)
Do not use underscore in version qualifiers
I think this will all work better post M5, but certainly on 3.1.x streams, and underscore is converted to a hyphen in some places, and will at first seeem to work, but then there's problems associating source with its code, etc., so ... use with care, if not outright avoid. See [| bug 89428] for some discussions.
Use the platform releng tool
To update your map files automatically while releasing your plug-ins, the releng tool found as a download way at the bottom of the platform download page is quite helpful. The instructions are sparse, but it's fairly straightforward (right-click a project and select Team -> Release...).
When using .qualifier at the end of your Bundle-Version manifest entries, your plug-ins will be versioned according to the tags entered in your map files automatically when using the release engineering tool with the PDE basebuilder.
Guide to understanding versioning
Just because this page cannot be linked enough, look here for detailed information on when and how to apply new version numbers to your plug-ins and features: [Plug-in Versioning]
And example build script to condition update jars and produce zipped distributions
This should be taken as an "example script" that can be used by some build processes. As of this writing, it does happen to be the one we in WTP use. We try to use "the standard" PDE Build process as much as possible, turn on "produce update jars", and turn on "runPackager", so this task below assumes we already have a zipped up version of update site jars, and, that during the "postPackage" phase of the customTarget.xml we can call our utility script, as follows.
<target name="postPackage">
<property name="archiveName"
value="wtp-wst-sdk-${buildLabel}.zip" />
<ant
antfile="${wtp.builder.home}/scripts/build/buildutilities.xml"
target="unpackUpdateJarsAndCreateZippedPackages">
<property name="buildDirectory" value="${buildDirectory}"/>
<property name="buildLabel" value="${buildLabel}"/>
<property name="archiveName" value="${archiveName}"/>
</ant>
</target>
So, if people fine this useful, great!
You can always see all our scripts in releng.wtpbuilder in the wtp repository at /cvsroot/webtools and this file is
buildutilities.xml
<?xml version="1.0" encoding="UTF-8"?>
<project name="Build Utility Tasks"
default="nodefault"
basedir=".">
<property name="debug" value="true" />
<!-- ================================================================================== -->
<!-- -->
<!-- unpackUpdateJarsAndCreateZippedPackages -->
<!-- -->
<!-- This task takes a zip file of update jars, which is created by PDE build -->
<!-- process, and "converts" it to a traditional zip file, processing the -->
<!-- jars with pack200 for better compression on update sites. -->
<!-- -->
<!-- -->
<!-- ================================================================================== -->
<target name="unpackUpdateJarsAndCreateZippedPackages"
depends="init">
<!--Note: we use this odd "tmpsite-archiveName-temp" to make sure unique directories,
since in some cases these directories can not be deleted from ant, see
https://bugs.eclipse.org/bugs/show_bug.cgi?id=142926,
and since directory names ending in .zip are misinterpreted by jarProcessor, see
https://bugs.eclipse.org/bugs/show_bug.cgi?id=143385
But, its handy to do as unique directories anyway, since if a larger
process calls this mulitiple times, on different zips, and if debugging
is turnned on, then all the tmpsite directories are left on disk for
inspection.
-->
<property name="tmpsite"
value="${buildDirectory}/tmpsite-${archiveName}-temp" />
<!-- ================================================================================== -->
<!-- -->
<!-- 0. make "backup" copy of original zip, if debugging, -->
<!-- since might be needed for comparison -->
<!-- -->
<!-- ================================================================================== -->
<antcall target="makeBackupCopyForDebugging" />
<!-- ================================================================================== -->
<!-- -->
<!-- 1. normalize jars here, from a zip file of update jars. -->
<!-- The normalized jars are put in zip file of same name, in a directory -->
<!-- named normalized -->
<!-- -->
<!-- ================================================================================== -->
<java jar="${pde.builder.path}/startup.jar"
fork="true"
jvm="${java15-home}/bin/java"
failonerror="true"
maxmemory="256m"
dir="${buildDirectory}">
<arg line="#{logIfDebug}" />
<arg line="-application org.eclipse.update.core.siteOptimizer" />
<!-- note: this -processAll option is critical in this first step.
For various reasons, jarProcessor is written to not act on
any jar if the jar is not "marked", or if not told explicitly to
to processAll
-->
<arg line="-jarProcessor ${verboseIfDebug} -processAll -outputDir ${tmpsite}/normalized -repack ${buildDirectory}/${buildLabel}/${archiveName}" />
</java>
<!-- ================================================================================== -->
<!-- -->
<!-- 2. unzip the normalized jars in the zip file produced in step 1., to the -->
<!-- directory {tmpsite} for further processing. plugins and features -->
<!-- end up in {tmpsite}/eclipse -->
<!-- -->
<!-- ================================================================================== -->
<unzip dest="${tmpsite}"
src="${tmpsite}/normalized/${archiveName}" />
<!-- ================================================================================== -->
<!-- -->
<!-- 3. copy all update jars to a common update site directory, if desired. -->
<!-- Note: overwite is false to avoid "touching" files already produced and -->
<!-- processed be previous steps in a larger build process. This means the updateSite -->
<!-- *must* be complete clean before the larger process starts. -->
<!-- -->
<!-- ================================================================================== -->
<mkdir dir="${buildDirectory}/${buildLabel}/updateSite" />
<copy todir="${buildDirectory}/${buildLabel}/updateSite"
overwrite="false">
<fileset dir="${tmpsite}/eclipse" />
</copy>
<!-- ================================================================================== -->
<!-- -->
<!-- 4. for modularity, pack200 is done here, optionally. -->
<!-- gz files are produced in update site directory. -->
<!-- -->
<!-- This is optional since -->
<!-- processing is expensive to do for every build. Only need when ready to declare -->
<!-- an update site, and, for exmaple, no need to do for "local" or HEAD builds -->
<!-- since developers wouldn't normally need it for a quick check of of a build. -->
<!-- -->
<!-- ================================================================================== -->
<!-- <property
name="doPack"
value="true" /> -->
<antcall target="createPackFilesIfDesired" />
<!-- ================================================================================== -->
<!-- -->
<!-- 5. now create traditional zip file of unpacked jars. This type of -->
<!-- "unpack" is not related to pack200, but instead means to unpack -->
<!-- those jars that are supposed to be unpacked based on feature defintion, -->
<!-- if the plugin's unpack attribute is set to true in the feature -->
<!-- -->
<!-- ================================================================================== -->
<!-- use releng task of unpackUpdateJars -->
<unpackUpdateJars site="${tmpsite}/eclipse"
output="${tmpsite}/unpacked/eclipse" />
<!-- add copy of legal doc's here, product.ini, etc., before re-zipping -->
<copy todir="${tmpsite}/unpacked/eclipse"
overwrite="false">
<fileset dir="${wtp.builder.home}/rootfiles">
</fileset>
</copy>
<!-- delete the zip file of update jars we started with, which we are about to re-create
as traditional zip file -->
<delete file="${buildDirectory}/${buildLabel}/${archiveName}" />
<!-- recreate zip file now, same name, traditional content, which is mix of folders and jars -->
<zip destfile="${buildDirectory}/${buildLabel}/${archiveName}"
basedir="${tmpsite}/unpacked"
update="false"
duplicate="preserve" />
<!-- always produce checksum files for any zips produced -->
<antcall target="createChecksums" />
<!-- ================================================================================== -->
<!-- -->
<!-- 6. can now remove tmpsite as no longer needed, unless debugging -->
<!-- -->
<!-- ================================================================================== -->
<antcall target="deleteTmpSite" />
</target>
<!-- ============================================================================================== -->
<!-- -->
<!-- Utility and Helper tasks -->
<!-- -->
<!-- ============================================================================================== -->
<target name="init">
<condition property="verboseIfDebug"
value="-verbose"
else="">
<istrue value="${debug}" />
</condition>
<condition property="logIfDebug"
value="-debug -consolelog"
else="">
<istrue value="${debug}" />
</condition>
</target>
<target name="deleteTmpSite" unless="debug">
<delete dir="${tmpsite}" />
</target>
<target name="createPackFilesIfDesired" if="doPack" depends="init">
<java jar="${pde.builder.path}/startup.jar"
fork="true"
jvm="${java15-home}/bin/java"
failonerror="true"
maxmemory="256m"
dir="${buildDirectory}">
<arg line="${logIfDebug}" />
<arg line="-application org.eclipse.update.core.siteOptimizer" />
<arg line="-jarProcessor ${verboseIfDebug} -outputDir ${buildDirectory}/${buildLabel}/updateSite -pack ${buildDirectory}/${buildLabel}/updateSite" />
</java>
</target>
<target name="makeBackupCopyForDebugging" if="debug">
<!-- temporary copy while confirming build to be able to do side-by-side comparisons -->
<mkdir dir="${buildDirectory}/backuporiginalzips" />
<copy file="${buildDirectory}/${buildLabel}/${archiveName}"
todir="${buildDirectory}/backuporiginalzips" />
</target>
<target name="createChecksums">
<!-- This createChecksums task creates two files, for use in two contexts.
a. an x.md5 file, that has the name of the file in the contents.
This is good for some "third party" executables, like md5summ, that
expects the name in the file.
b. since ant does not deal well with md5 files with anything in them
other than the checksum, we provide same thing in a file with
an md5antformat extension, that has only the checksum.
-->
<mkdir dir="${buildDirectory}/${buildLabel}/checksum" />
<checksum file="${buildDirectory}/${buildLabel}/${archiveName}"
property="md5" />
<echo message="${md5} *${archiveName}"
file="${buildDirectory}/${buildLabel}/checksum/${archiveName}.md5" />
<echo message="${md5}"
file="${buildDirectory}/${buildLabel}/checksum/${archiveName}.md5antformat" />
</target>
<target name="nodefault">
<echo message="There is no default target for this buildutililites.xml ant script." />
</target>
</project>