• A Guide To Releasing Eclipse Update Sites during Incubation (DRAFT)
  • Contents
  • Status - DRAFT
  • Abstract
  • Setting up Eclipse mirroring
  • Creating and maintaining an Eclipse update site project
  • Optimized update sites
  • Sample build process
  • Help Wanted!

This document is under active development. This is a first draft intended to allow public review.

This document is descriptive, not normative. It aims to guide podlings through the process of releasing Eclipse update sites with proper mirroring.

Podlings may distribute suitable artifacts through an Eclipse update site. All artifacts distributed through the update site must satisfy the standard policy. This implies that:

• The update site must be contained within the podling distribution directory.
• All artifacts must be signed and summed.
• Mirroring must be used.

This guide describes a process for accomplishing this.

The Eclipse <site> information will contain a URL that Eclipse uses to get the list of mirrors. To set this up to use the automatic Apache mirroring system, make a pair of files in project website space, e.g. in a directory your-project-name/docs/mirrors-support called something like: eclipse-update--xml.cgi and the same name with the type ".html".

In the .cgi version, put the following:

#!/bin/sh
# Wrapper script around mirrors.cgi script
# (we must change to that directory in order for python to pick up the
#  python includes correctly)
cd /www/www.apache.org/dyn/mirrors
/www/www.apache.org/dyn/mirrors/mirrors.cgi $*

In the .html version, put:

<mirrors>
<mirror url="[preferred]/incubator/your-project-name/eclipse-update-site/"
label="Recommended mirror: [preferred]"/>
[if-any http]
  [for http]
    <mirror url="[http]/incubator/your-project-name/eclipse-update-site/"
      label="[http]"/>
  [end]
[end]
[if-any backup]
  [for backup]
    <mirror url="[backup]/incubator/your-project-name/eclipse-update-site/"
      label="Backup mirror: [backup]"/>
  [end]
[end]
</mirrors>

Doing this will return the list of mirrors to Eclipse, as generated by the apache mirroring system

Your project will be making many releases. Some subset (or perhaps all) of the releases will be available from the update site. Overtime, the update site itself will be updated to reflect new versions being added. Plan your release process to allow for properly tagging the versions of the update site project that go with each release.

Your project may have several components; these may be on different release cycles. A particular refresh of the update site might involve a subset of the components being managed by the update site.

For those components that are being released, new Jars will be generated, signed, and added to the update site. In addition, you will be changing the site.xml file to reflect these newly released components. The generation process for the update site will need to combine the newly release components, with the previously released things for previous levels. If the previous components are small, you can keep these in SVN; if they are large, consider keeping them in www.apache.org/dist/incubator/your-project/eclipse-update-site since they're there already.

The update site project is created with an Eclipse wizard. You have to edit the site.xml file. Here's some tips:

• If you are creating an optimized update site (see following section) include the pack200="true" attribute on the <site> tag, and set the digestURL attribute to refer to the directory containing the digest.zip file. You can use a relative directory (relative to the directory containing the site.xml file). For example, if your digest.zip was in the same directory as the site.xml, use "/"; if it was in a subdirectory of this called "digests", use "/digests".

• Set the mirrorsURL attribute to the location on your project's website where the mirroring support cgi script is. For instance, it might be something like this: http://incubator.apache.org/your-project-name/mirrors-support/eclipse-update--xml.cgi

  This is the key to getting the mirroring to work with the Eclipse update process.

Starting with Eclipse 3.3, an optimized form of update sites is possible, through two forms of optimization. One is making use of the pack200 Jar optimizations, part of Java 5 and beyond, and the other is having a compact form of the update site information created and placed in a "digest.zip" file. (Note: don't forget to have your signing process sign this zip.) See the Update Site Optimization article for details on creating optimized update sites.

A typical build script builds feature Jars from associated Eclipse feature projects, copies (perhaps from Maven repositories to insure getting a particular release level) jars for the plugins, runs the packer, and builds the digest. Another script might do signing and signature verification of the jar and zip artifacts. For a sample of scripts that do this, please refer to the SVN for the UIMA project's update site - in particular the build.xml and the signEclipseUpdateSite.sh script.

Help to improve the system by posting a patch for this document to the incubator section of JIRA or a comment to general.AT.incubator.apache.org.