You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2013/01/09 22:11:31 UTC
svn commit: r1431080 - in /uima/site/trunk/uima-website:
docs/eclipse-update-site.html xdocs/eclipse-update-site.xml
Author: schor
Date: Wed Jan 9 21:11:31 2013
New Revision: 1431080
URL: http://svn.apache.org/viewvc?rev=1431080&view=rev
Log:
no Jira - add planned info on Eclipse Update Site P2 version
Added:
uima/site/trunk/uima-website/docs/eclipse-update-site.html (with props)
uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml (with props)
Added: uima/site/trunk/uima-website/docs/eclipse-update-site.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/eclipse-update-site.html?rev=1431080&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/eclipse-update-site.html (added)
+++ uima/site/trunk/uima-website/docs/eclipse-update-site.html Wed Jan 9 21:11:31 2013
@@ -0,0 +1,484 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+ <style type="text/css">@import "stylesheets/base.css";</style>
+ <meta name="author" value="Apache UIMA Documentation Team">
+ <meta name="email" value="dev@uima.apache.org">
+
+
+
+ <title>Apache UIMA - UIMA's Eclipse Update Site</title>
+ </head>
+
+ <body>
+ <div class="topLogos">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <a href="index.html">
+ <img style="border: 1px solid black;" src="./images/UIMA_banner2tlpTm.png" alt="UIMA project logo" border="0"/>
+ </a>
+ </td>
+ <td align='CENTER'>
+ <div class="pageBanner">UIMA's Eclipse Update Site</div>
+ </td>
+ <td align='RIGHT'>
+ <a href="http://www.apache.org">
+ <img src="./images/asf-logo-on-white-smallTm.png" alt="Apache UIMA" border="0"/>
+ </a>
+ </td>
+ </tr>
+ </table>
+ <hr noshade="" size="1"/>
+ </div>
+ <table border="0" width="100%" cellspacing="4">
+ <tr>
+ <td align='RIGHT' colspan="2">
+ <form method="get" action="http://www.google.com/search">
+ Search the site
+ <input type="text" name="q" size="25" maxlength="255" value="" />
+ <input type="hidden" name="sitesearch" value="http://uima.apache.org/" />
+ <input name="Search" value="Search Site" type="submit"/>
+ </form>
+ </td>
+ </tr>
+ <tr> <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top">
+
+
+
+
+
+
+ <!-- regular menu -->
+ <div class="navBar">
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">General</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./index.html">Home</a>
+ </div>
+ <div class="navBarItem"> <a href="./downloads.cgi">Downloads</a>
+ </div>
+ <div class="navBarItem"> <a href="./documentation.html">Documentation</a>
+ </div>
+ <div class="navBarItem"> <a href="./news.html">News</a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="./mail-lists.html">Mailing Lists</a>
+ </div>
+ <div class="navBarItem"> <a href="./mail-lists.html#Apache_UIMA_Forums">Forums</a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.general" target="_blank"><em> Users</em> <img src="images/offsitelink.png" /></a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.devel" target="_blank"><em>Dev</em> <img src="images/offsitelink.png" /></a>
+ </div>
+ <div class="navBarItem"> <a href="http://cwiki.apache.org/UIMA/powered-by-apache-uima.html" target="_blank">Powered By UIMA <img src="images/offsitelink.png"/></a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="http://issues.apache.org/jira/browse/uima" target="_blank">Issue tracker <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="http://cwiki.apache.org/UIMA/" target="_blank">Wiki <img src="images/offsitelink.png"/></a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Components & Tools</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./sandbox.html#uima-addons-annotators">Annotators</a>
+ </div>
+ <div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a>
+ </div>
+ <div class="navBarItem"> <a href="./sandbox.html">Addons and Sandbox</a>
+ </div>
+ <div class="navBarItem"> <a href="./external-resources.html">External Resources</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Community</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./get-involved.html">Get Involved</a>
+ </div>
+ <div class="navBarItem"> <a href="./contribution-policy.html">Contribution Policies</a>
+ </div>
+ <div class="navBarItem"> <a href="./faq.html">FAQ</a>
+ </div>
+ <div class="navBarItem"> <a href="./project-guidelines.html">Project Guidelines</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Development</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./dev-quick.html">Quick Start: building</a>
+ </div>
+ <div class="navBarItem"> <a href="./building-uima.html">Building from Source</a>
+ </div>
+ <div class="navBarItem"> <a href="./one-time-setup.html">One-time setups</a>
+ </div>
+ <div class="navBarItem"> <a href="./svn.html">Source Code</a>
+ </div>
+ <div class="navBarItem"> <a href="./distribution.html">Creating a Distribution</a>
+ </div>
+ <div class="navBarItem"> <a href="./release.html">Doing a UIMA release</a>
+ </div>
+ <div class="navBarItem"> <a href="./codeConventions.html">Code Conventions</a>
+ </div>
+ <div class="navBarItem"> <a href="./uima-specification.html">UIMA Specification (OASIS)</a>
+ </div>
+ <div class="navBarItem"> <a href="./team-list.html">Project Team</a>
+ </div>
+ <div class="navBarItem"> <a href="./maven-design.html">Maven Use</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./iks09.html">IKS 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./gscl09.html">GSCL 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lsm09.html">LSM 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lrec08.html">LREC 2008</a>
+ </div>
+ <div class="navBarItem"> <a href="./gldv07.html">GLDV 2007</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">ASF</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="http://www.apache.org/licenses/" target="_blank">License <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/foundation/thanks.html" target="_blank">ASF Sponsors <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/foundation/sponsorship.html" target="_blank">ASF Sponsorship <img src="images/offsitelink.png"/></a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/security" target="_blank">Security <img src="images/offsitelink.png"/></a>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="UIMA's Eclipse Update Site"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> UIMA's Eclipse Update Site</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+The Apache UIMA™ project maintains an Eclipse update site as part
+of its prebuilt artifacts. The information on this page is mainly for
+developers, and documents how this update site is managed.
+</p>
+ <p>
+Over time, the update site ends up containing various Eclipse features
+and their plugins, at different "versions". It uses the (evolving) Eclipse standard
+mechanisms to install whatever version a user might require.
+</p>
+ <p>
+Because of this, the update site itself keeps "older" versions. Every
+time a new release is made which includes one or more new versions of some
+Eclipse features/plugins, these artifacts are built and <em>added</em> to
+the set of existing (and perhaps, older versions of) feature and plugins.
+</p>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Early Optimizations">
+ <h2>Early Optimizations
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+The first UIMA Eclipse update sites were optimized by the then-current
+approach to optimization. This included 2 special things:
+<ul>
+<li>"super-duper" packing of the jar files using some new compression
+utilities that came with Java 5.</li>
+<li>A separate copy of all the metadata needed for initial processing
+by the Eclipse update mechanism - put into a compressed "digest.zip".</li>
+<p>
+See <a target="_blank" href="http://wiki.eclipse.org/Update_Site_Optimization">http://wiki.eclipse.org/Update_Site_Optimization</a>,
+which describes the design goals for this.</p>
+<p class="note">But note that the information on this page is now out of date, and has been
+superseded by a second version of update site packaging. In fact, the
+previously available headless Eclipse application, <em>org.eclipse.update.core.siteOptimizer</em>, is no
+longer part of Eclipse releases.
+</p>
+</ul>
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="P2">
+ <h2>P2
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+At some point in the evolution of the Eclipse update site mechanisms,
+the "P2" approach for Eclipse update sites became supported.
+It has some changes (among others):
+</p>
+ <ul>
+<li>It adds to the normal metadata about components, the detailed
+version and dependency information contained in the manifest of the
+OSGi component JARs. This is a finer-grained versioning system in which
+version information is associated with Java Packages, in contrast
+to the entire contents of a Jar being the entity which is versioned.
+<p>Some tooling, such as <a target="_blank" href="http://eclipse.org/tycho/">http://eclipse.org/tycho/Tycho</a>,
+need this finer-grained information
+to resolve dependencies.</p></li>
+<li>
+It continues the previous approach of putting a copy of the metadata
+in a separately downloaded file (formerly, the digest.zip). In P2
+this is now in 2 files: content.xml
+and artifacts.xml.
+</li>
+</ul>
+ <p>
+Some of the UIMA plugin projects need to have the "high-fidelity" resolution of software
+dependencies that comes with the P2 repositories.
+</p>
+ <p>
+As of January 2013, we are converting to the P2 style of update sites, and
+will not build the update site for pre-P2 style because P2 support has been
+in Eclipse for several years (since mid 2008).
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Layout and Versioning">
+ <h2>Layout and Versioning
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+Since the Eclipse update site is something that is added to whenever
+particular components are released, the maven projects used to support it
+are in a shared location, under the SVN folder for our build tooling:
+<a target="_blank" href="http://svn.apache.org/repos/asf/uima/build/trunk/eclipse-packagings">
+ http://svn.apache.org/repos/asf/uima/build/trunk/eclipse-packagings</a>.
+</p>
+ <p>This is a change from our previous organization, which placed the
+update-site project in the uimaj part of our repository (which holds the
+source code for the Java SDK of the base UIMA).</p>
+ <p>Feature plugin projects are associated with particular parts of
+the UIMA project (such as the textmarker, or Java Base SDK, etc.),
+and reside within those major components.</p>
+ <p>
+Because the Update Site is a mere repackaging of released artifacts, it
+is treated more like our website, in the sense that changes here are not
+versioned. However, because the update site contains downloadable
+signed artifacts, they are not hosted on our website, but rather on the
+official Apache distribution mirror system. The meta information in the
+update site includes references to the Apache mirror system, so
+the Eclipse install mechanism can use the mirrors.
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Composite Update Sites">
+ <h2>Composite Update Sites
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+Update sites can be composite. A composite update site
+merely includes pointers to other update sites. The installation
+procedure combines all of the composite update sites mentioned
+in the top level composite description into one, for purposes
+of displaying and working with it. We use the composite mechanism
+to make maintenance of independently developed features more isolated;
+when a new version of a sub-site is developed, updates are
+localized to just that sub-site.
+</p>
+ <p>Our subsites are named subfolders of the main update site
+(.../dist/uima/eclipse-update-site).</p>
+ <p>
+We currently have sub-sites for
+<ul>
+<li>uimaj - base Java UIMA SDK tools and runtime
+</li>
+<li>uima-as - addons for the base tooling to add the deployment descriptor editor, and uima-as runtime</li>
+<li>TextEditor (coming soon)</li>
+</ul>
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="How to Change the Update Site">
+ <h2>How to Change the Update Site
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>To do any work on the Eclipse update sites, you must have
+maven property variables set to identify an accessible Eclipse
+installation so the Eclipse packaging tooling and Ant support
+can be located. These are typically put into your .m2 setttings.xml
+file like this:</p>
+ <pre>
+<uima-maven-build-eclipse-home>C:/x/y/z/eclipse</uima-maven-build-eclipse-home>
+<eclipse-equinox-launcher>
+ ${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
+</eclipse-equinox-launcher>
+</pre>
+ <p>We use the Composite pattern for our update site, to allow a
+cleaner separation of independent sets of Features, for maintenance
+ease. The first decision when doing an update is to decide if
+you need to add a new sub-update-site to the set managed by the
+Composite collection. If so, update the script part inside the
+POM (follow the commented instructions) to add the sub-site.</p>
+ <p>
+To update a sub-site, go to that subsite's project for its update-site.
+For example, for uimaj, this is the project uimaj-eclipse-update-site.
+In that project, run the Eclipse category editor to update the categories
+(if necessary).
+</p>
+ <p>
+Each update site "build" will use the pom to pull into a prototype
+update site in its /target directory the complete set of features and plugins.
+It does this using information specified in the POM, as dependencies.
+It does this for all versions of the features and plugins.
+</p>
+ <p>
+Therefore, you must edit this POM if you are specifying new versions
+of any of the features and plugins, and add those dependencies to the
+list inside of the build step that copies the plugin and feature
+dependencies.
+</p>
+ <p>
+Running <code>mvn package</code> on the update site pom will produce a
+P2 update site in /target/eclipse-update-site. When releasing, the
+contents of this directory needs to be copied into the appropriately
+named subfolder for this sub-site in the release spot for UIMA
+distribution.
+</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Links and References">
+ <h2>Links and References
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>Here are links to more information; there are many (partially) out-of-date
+websites which are misleading but these links (as of January, 2013, seem up to date.)</p>
+ <ul>
+<li><a target="_blank" href="http://wiki.eclipse.org/Equinox/p2/Getting_Started_for_Releng">
+http://wiki.eclipse.org/Equinox/p2/Getting_Started_for_Releng</a>
+- describes basic concepts</li>
+<li><a target="_blank" href="http://wiki.eclipse.org/Equinox/p2/Publisher">
+http://wiki.eclipse.org/Equinox/p2/Publisher</a>
+- describes the basic methods and Ant tasks used to create and modify update sites for P2;
+includes information on generating the P2 style Category metadata.
+</li>
+<li><a target="_blank" href="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit">
+http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit</a>
+- a general presentation on P2
+</li>
+<li><a target="_blank" href="http://wiki.eclipse.org/P2">
+http://wiki.eclipse.org/P2</a>
+- the main starting page for P2 info on the Eclipse Wiki
+</li>
+<li><a target="_blank" href="http://wiki.eclipse.org/Update_Site_Optimization">
+http://wiki.eclipse.org/Update_Site_Optimization</a>
+- now <em>OUT OF DATE</em> information on how update sites were optimized, before P2
+</li>
+<li><a target="_blank" href="http://wiki.eclipse.org/Equinox/p2/Composite_Repositories_(new)">
+http://wiki.eclipse.org/Equinox/p2/Composite_Repositories_(new)</a>
+- a discussion of Composite Repositories - a top level file structure that aggregates together
+other update sites
+</li>
+<li><a target="_blank" href="http://wiki.eclipse.org/Equinox/p2/Ant_Tasks">
+http://wiki.eclipse.org/Equinox/p2/Ant_Tasks</a>
+- Ant tasks for P2, but may be <em>out of date</em> - a good summary of the Ant tasks
+we use in the automated build of the update site.
+</li>
+<li><a target="_blank" href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm">
+http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm</a>
+- a discussion of Ant tasks for P2. These are the versions for the current Eclipse (Juno - 4.2) release.
+These are used in our build automation.
+</li>
+
+</ul>
+ </blockquote>
+ </td></tr>
+ </table>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ </td>
+ </tr>
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <table class="pageFooter">
+ <tr>
+ <td><a href="index.html">Home</a></td>
+ <td><a href="privacy-policy.html">Privacy Policy</a></td>
+ <td style="font-size:75%">
+ Copyright © 2006-2011, The Apache Software Foundation.<br/>
+ Apache UIMA, UIMA, the Apache UIMA logo and the Apache Feather logo are trademarks of The Apache Software Foundation.<br/>
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </td>
+ <td><a href="mailto:dev@uima.apache.org">Contact us</a></td>
+ </tr>
+ </table>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+
Propchange: uima/site/trunk/uima-website/docs/eclipse-update-site.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml?rev=1431080&view=auto
==============================================================================
--- uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml (added)
+++ uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml Wed Jan 9 21:11:31 2013
@@ -0,0 +1,263 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<document>
+
+<properties>
+<title>UIMA's Eclipse Update Site</title>
+<author email="dev@uima.apache.org">Apache UIMA Documentation Team</author>
+</properties>
+
+<body>
+
+<section name="UIMA's Eclipse Update Site">
+
+<p>
+The Apache UIMA™ project maintains an Eclipse update site as part
+of its prebuilt artifacts. The information on this page is mainly for
+developers, and documents how this update site is managed.
+</p>
+
+<p>
+Over time, the update site ends up containing various Eclipse features
+and their plugins, at different "versions". It uses the (evolving) Eclipse standard
+mechanisms to install whatever version a user might require.
+</p>
+
+<p>
+Because of this, the update site itself keeps "older" versions. Every
+time a new release is made which includes one or more new versions of some
+Eclipse features/plugins, these artifacts are built and <em>added</em> to
+the set of existing (and perhaps, older versions of) feature and plugins.
+</p>
+
+<subsection name="Early Optimizations">
+<p>
+The first UIMA Eclipse update sites were optimized by the then-current
+approach to optimization. This included 2 special things:
+<ul>
+<li>"super-duper" packing of the jar files using some new compression
+utilities that came with Java 5.</li>
+<li>A separate copy of all the metadata needed for initial processing
+by the Eclipse update mechanism - put into a compressed "digest.zip".</li>
+<p>
+See <a target="_blank"
+href="http://wiki.eclipse.org/Update_Site_Optimization">http://wiki.eclipse.org/Update_Site_Optimization</a>,
+which describes the design goals for this.</p>
+<p class="note">But note that the information on this page is now out of date, and has been
+superseded by a second version of update site packaging. In fact, the
+previously available headless Eclipse application, <em>org.eclipse.update.core.siteOptimizer</em>, is no
+longer part of Eclipse releases.
+</p>
+</ul>
+</p>
+</subsection>
+
+<subsection name="P2">
+<p>
+At some point in the evolution of the Eclipse update site mechanisms,
+the "P2" approach for Eclipse update sites became supported.
+It has some changes (among others):
+</p>
+<ul>
+<li>It adds to the normal metadata about components, the detailed
+version and dependency information contained in the manifest of the
+OSGi component JARs. This is a finer-grained versioning system in which
+version information is associated with Java Packages, in contrast
+to the entire contents of a Jar being the entity which is versioned.
+<p>Some tooling, such as <a target="_blank"
+href="http://eclipse.org/tycho/">http://eclipse.org/tycho/Tycho</a>,
+need this finer-grained information
+to resolve dependencies.</p></li>
+<li>
+It continues the previous approach of putting a copy of the metadata
+in a separately downloaded file (formerly, the digest.zip). In P2
+this is now in 2 files: content.xml
+and artifacts.xml.
+</li>
+</ul>
+<p>
+Some of the UIMA plugin projects need to have the "high-fidelity" resolution of software
+dependencies that comes with the P2 repositories.
+</p>
+
+<p>
+As of January 2013, we are converting to the P2 style of update sites, and
+will not build the update site for pre-P2 style because P2 support has been
+in Eclipse for several years (since mid 2008).
+</p>
+</subsection>
+
+<subsection name="Layout and Versioning">
+<p>
+Since the Eclipse update site is something that is added to whenever
+particular components are released, the maven projects used to support it
+are in a shared location, under the SVN folder for our build tooling:
+<a target="_blank"
+ href="http://svn.apache.org/repos/asf/uima/build/trunk/eclipse-packagings">
+ http://svn.apache.org/repos/asf/uima/build/trunk/eclipse-packagings</a>.
+</p>
+<p>This is a change from our previous organization, which placed the
+update-site project in the uimaj part of our repository (which holds the
+source code for the Java SDK of the base UIMA).</p>
+
+<p>Feature plugin projects are associated with particular parts of
+the UIMA project (such as the textmarker, or Java Base SDK, etc.),
+and reside within those major components.</p>
+
+<p>
+Because the Update Site is a mere repackaging of released artifacts, it
+is treated more like our website, in the sense that changes here are not
+versioned. However, because the update site contains downloadable
+signed artifacts, they are not hosted on our website, but rather on the
+official Apache distribution mirror system. The meta information in the
+update site includes references to the Apache mirror system, so
+the Eclipse install mechanism can use the mirrors.
+</p>
+
+</subsection>
+
+<subsection name="Composite Update Sites">
+<p>
+Update sites can be composite. A composite update site
+merely includes pointers to other update sites. The installation
+procedure combines all of the composite update sites mentioned
+in the top level composite description into one, for purposes
+of displaying and working with it. We use the composite mechanism
+to make maintenance of independently developed features more isolated;
+when a new version of a sub-site is developed, updates are
+localized to just that sub-site.
+</p>
+
+<p>Our subsites are named subfolders of the main update site
+(.../dist/uima/eclipse-update-site).</p>
+
+<p>
+We currently have sub-sites for
+<ul>
+<li>uimaj - base Java UIMA SDK tools and runtime
+</li>
+<li>uima-as - addons for the base tooling to add the deployment descriptor editor, and uima-as runtime</li>
+<li>TextEditor (coming soon)</li>
+</ul>
+</p>
+</subsection>
+
+<subsection name="How to Change the Update Site">
+<p>To do any work on the Eclipse update sites, you must have
+maven property variables set to identify an accessible Eclipse
+installation so the Eclipse packaging tooling and Ant support
+can be located. These are typically put into your .m2 setttings.xml
+file like this:</p>
+<pre>
+<uima-maven-build-eclipse-home>C:/x/y/z/eclipse</uima-maven-build-eclipse-home>
+<eclipse-equinox-launcher>
+ ${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
+</eclipse-equinox-launcher>
+</pre>
+<p>We use the Composite pattern for our update site, to allow a
+cleaner separation of independent sets of Features, for maintenance
+ease. The first decision when doing an update is to decide if
+you need to add a new sub-update-site to the set managed by the
+Composite collection. If so, update the script part inside the
+POM (follow the commented instructions) to add the sub-site.</p>
+
+<p>
+To update a sub-site, go to that subsite's project for its update-site.
+For example, for uimaj, this is the project uimaj-eclipse-update-site.
+In that project, run the Eclipse category editor to update the categories
+(if necessary).
+</p>
+
+<p>
+Each update site "build" will use the pom to pull into a prototype
+update site in its /target directory the complete set of features and plugins.
+It does this using information specified in the POM, as dependencies.
+It does this for all versions of the features and plugins.
+</p>
+
+<p>
+Therefore, you must edit this POM if you are specifying new versions
+of any of the features and plugins, and add those dependencies to the
+list inside of the build step that copies the plugin and feature
+dependencies.
+</p>
+
+<p>
+Running <code>mvn package</code> on the update site pom will produce a
+P2 update site in /target/eclipse-update-site. When releasing, the
+contents of this directory needs to be copied into the appropriately
+named subfolder for this sub-site in the release spot for UIMA
+distribution.
+</p>
+</subsection>
+
+<subsection name="Links and References">
+<p>Here are links to more information; there are many (partially) out-of-date
+websites which are misleading but these links (as of January, 2013, seem up to date.)</p>
+<ul>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/Equinox/p2/Getting_Started_for_Releng">
+http://wiki.eclipse.org/Equinox/p2/Getting_Started_for_Releng</a>
+- describes basic concepts</li>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/Equinox/p2/Publisher">
+http://wiki.eclipse.org/Equinox/p2/Publisher</a>
+- describes the basic methods and Ant tasks used to create and modify update sites for P2;
+includes information on generating the P2 style Category metadata.
+</li>
+<li><a target="_blank"
+href="http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit">
+http://www.slideshare.net/PascalRapicault/understanding-and-extending-p2-for-fun-and-profit</a>
+- a general presentation on P2
+</li>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/P2">
+http://wiki.eclipse.org/P2</a>
+- the main starting page for P2 info on the Eclipse Wiki
+</li>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/Update_Site_Optimization">
+http://wiki.eclipse.org/Update_Site_Optimization</a>
+- now <em>OUT OF DATE</em> information on how update sites were optimized, before P2
+</li>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/Equinox/p2/Composite_Repositories_(new)">
+http://wiki.eclipse.org/Equinox/p2/Composite_Repositories_(new)</a>
+- a discussion of Composite Repositories - a top level file structure that aggregates together
+other update sites
+</li>
+<li><a target="_blank"
+href="http://wiki.eclipse.org/Equinox/p2/Ant_Tasks">
+http://wiki.eclipse.org/Equinox/p2/Ant_Tasks</a>
+- Ant tasks for P2, but may be <em>out of date</em> - a good summary of the Ant tasks
+we use in the automated build of the update site.
+</li>
+<li><a target="_blank"
+href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm">
+http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fp2_repositorytasks.htm</a>
+- a discussion of Ant tasks for P2. These are the versions for the current Eclipse (Juno - 4.2) release.
+These are used in our build automation.
+</li>
+
+</ul>
+</subsection>
+</section>
+</body>
+</document>
\ No newline at end of file
Propchange: uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml
------------------------------------------------------------------------------
svn:eol-style = native