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/13 19:29:03 UTC
svn commit: r1432692 - in /uima/site/trunk/uima-website:
docs/eclipse-update-site.html xdocs/eclipse-update-site.xml
Author: schor
Date: Sun Jan 13 18:29:03 2013
New Revision: 1432692
URL: http://svn.apache.org/viewvc?rev=1432692&view=rev
Log:
[UIMA-2568] align with what is actually implemented
Modified:
uima/site/trunk/uima-website/docs/eclipse-update-site.html
uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml
Modified: 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=1432692&r1=1432691&r2=1432692&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/eclipse-update-site.html (original)
+++ uima/site/trunk/uima-website/docs/eclipse-update-site.html Sun Jan 13 18:29:03 2013
@@ -188,7 +188,7 @@ mechanisms to install whatever version a
<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
+Eclipse features/plugins, the new artifacts are <em>added</em> to
the set of existing (and perhaps, older versions of) feature and plugins.
</p>
<table class="subsectionTable">
@@ -196,39 +196,6 @@ the set of existing (and perhaps, older
- <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>
@@ -238,7 +205,8 @@ longer part of Eclipse releases.
<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.
+the "P2" approach for Eclipse update sites was developed, and
+became the preferred way to package update sites.
It has some changes (among others):
</p>
<ul>
@@ -254,16 +222,19 @@ to resolve dependencies.</p></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.
+and artifacts.xml (these files are actually made into compressed Jars).
+</li>
+<li>
+The former update site files: site.xml, and digest.zip are no longer needed.
</li>
</ul>
<p>
-Some of the UIMA plugin projects need to have the "high-fidelity" resolution of software
+Some of the UIMA plugin projects now 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
+are no longer building the update site for pre-P2 style because P2 support has been
in Eclipse for several years (since mid 2008).
</p>
</blockquote>
@@ -274,43 +245,6 @@ in Eclipse for several years (since mid
- <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>
@@ -326,9 +260,11 @@ in the top level composite description i
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.
+localized to just that sub-site. The composite update site
+can also be separately maintained - it needs to change only when
+new sub-sites are added.
</p>
- <p>Our subsites are named subfolders of the main update site
+ <p>Our subsites are designed to be kept in named subfolders of the main update site
(.../dist/uima/eclipse-update-site).</p>
<p>
We currently have sub-sites for
@@ -339,6 +275,66 @@ We currently have sub-sites for
<li>TextEditor (coming soon)</li>
</ul>
</p>
+ <p>The update site looks like:
+<pre>
+.../dist/uima/eclipse-update-site
+ /compositeArtifacts.jar
+ /compositeContent.jar
+ /uimaj
+ /artifacts.jar
+ /content.jar
+ /features/.... all features
+ /plugins/.... all plugins
+ /uima-as
+ /artifacts.jar
+ /content.jar
+ /features/.... all features
+ /plugins/.... all plugins
+</pre>
+</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>
+The main Eclipse update site (which only has composite pointers to subsites)
+is kept with the general UIMA build tooling in
+<a target="_blank" href="http://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-composite-update-site">
+ http://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-composite-update-site</a>.
+</p>
+ <p>Feature and Plugin projects associated with particular parts of
+the UIMA project (such as the TextMarker, or Java Base SDK, etc.),
+reside within those major components.</p>
+ <p>
+Each subsite is typically built with its associated component. It is
+therefore reasonable to version these together with the component.
+So, for example, the UIMA Java SDK, released at version 2.4.0, will have
+the plugin and feature projects for it also at 2.4.0.
+</p>
+ <p>
+The project in the build tools, uima-eclipse-composite-update-site, is
+only rebuilt when a new subsite is added; it has incrementing version
+numbers.
+</p>
+ <p>The update-site packaging of released components is released as part of
+the underlying release of the components it packages; it doesn't (normally)
+have a separate "vote". When doing a componet release, the release manager
+should build and make available for testing the update (sub) site (and a
+new version of the composite update site, if that is being added to).
+When the release is accomplished, the release action is then a simple
+SVN copy from the dev/ to the release/ spot in the distribution SVN.
+</p>
</blockquote>
</td></tr>
</table>
@@ -354,9 +350,9 @@ We currently have sub-sites for
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
- <p>To do any work on the Eclipse update sites, you must have
+ <p>To run the build for any of 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
+installation (4.2 or later) 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>
@@ -364,34 +360,41 @@ file like this:</p>
<eclipse-equinox-launcher>
${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
</eclipse-equinox-launcher>
+%lt;uima-eclipse-jar-processor>
+ ${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.p2.jarprocessor_1.0.200.v20110808-1657.jar
+%lt;/uima-eclipse-jar-processor>
</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
+ <p>
+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>
+Composite collection. If so, update buildCompositeRepository.xml
+in the build/trunk/uima-eclipse-composite-update-site
+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).
+In that project, run the Eclipse category editor on the file
+category.xml and update the categories. You must add any new
+features to one (or more) categories, for them to be "visible";
+this includes new versions of existing features. If you are
+changing categories, this is where that is done, also; but that
+is probably a rare occurrence.
</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.
+Each update site "build" will use the pom to pull into .../target/eclipse-update-site
+the complete set of features and plugins for that sub-site.
+It does this using information specified in the POM,
+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.
+Therefore, you must edit the POM to specify the new versions
+of any of the features and plugins being released, adding those
+to the lists inside of the build step that copies the plugin and feature
+artifacts.
</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
+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.
@@ -404,6 +407,39 @@ distribution.
+ <a name="Earlier Optimizations (Historical)">
+ <h2>Earlier Optimizations (Historical)
+ </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="Links and References">
<h2>Links and References
</h2>
Modified: 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=1432692&r1=1432691&r2=1432692&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml (original)
+++ uima/site/trunk/uima-website/xdocs/eclipse-update-site.xml Sun Jan 13 18:29:03 2013
@@ -43,36 +43,15 @@ mechanisms to install whatever version a
<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
+Eclipse features/plugins, the new artifacts are <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.
+the "P2" approach for Eclipse update sites was developed, and
+became the preferred way to package update sites.
It has some changes (among others):
</p>
<ul>
@@ -89,50 +68,24 @@ to resolve dependencies.</p></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.
+and artifacts.xml (these files are actually made into compressed Jars).
+</li>
+<li>
+The former update site files: site.xml, and digest.zip are no longer needed.
</li>
</ul>
<p>
-Some of the UIMA plugin projects need to have the "high-fidelity" resolution of software
+Some of the UIMA plugin projects now 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
+are no longer building 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
@@ -142,10 +95,12 @@ in the top level composite description i
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.
+localized to just that sub-site. The composite update site
+can also be separately maintained - it needs to change only when
+new sub-sites are added.
</p>
-<p>Our subsites are named subfolders of the main update site
+<p>Our subsites are designed to be kept in named subfolders of the main update site
(.../dist/uima/eclipse-update-site).</p>
<p>
@@ -157,12 +112,68 @@ We currently have sub-sites for
<li>TextEditor (coming soon)</li>
</ul>
</p>
+
+<p>The update site looks like:
+<pre>
+.../dist/uima/eclipse-update-site
+ /compositeArtifacts.jar
+ /compositeContent.jar
+ /uimaj
+ /artifacts.jar
+ /content.jar
+ /features/.... all features
+ /plugins/.... all plugins
+ /uima-as
+ /artifacts.jar
+ /content.jar
+ /features/.... all features
+ /plugins/.... all plugins
+</pre>
+</p>
</subsection>
+<subsection name="Layout and Versioning">
+<p>
+The main Eclipse update site (which only has composite pointers to subsites)
+is kept with the general UIMA build tooling in
+<a target="_blank"
+ href="http://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-composite-update-site">
+ http://svn.apache.org/repos/asf/uima/build/trunk/uima-eclipse-composite-update-site</a>.
+</p>
+
+<p>Feature and Plugin projects associated with particular parts of
+the UIMA project (such as the TextMarker, or Java Base SDK, etc.),
+reside within those major components.</p>
+
+<p>
+Each subsite is typically built with its associated component. It is
+therefore reasonable to version these together with the component.
+So, for example, the UIMA Java SDK, released at version 2.4.0, will have
+the plugin and feature projects for it also at 2.4.0.
+</p>
+
+<p>
+The project in the build tools, uima-eclipse-composite-update-site, is
+only rebuilt when a new subsite is added; it has incrementing version
+numbers.
+</p>
+
+<p>The update-site packaging of released components is released as part of
+the underlying release of the components it packages; it doesn't (normally)
+have a separate "vote". When doing a componet release, the release manager
+should build and make available for testing the update (sub) site (and a
+new version of the composite update site, if that is being added to).
+When the release is accomplished, the release action is then a simple
+SVN copy from the dev/ to the release/ spot in the distribution SVN.
+</p>
+
+</subsection>
+
+
<subsection name="How to Change the Update Site">
-<p>To do any work on the Eclipse update sites, you must have
+<p>To run the build for any of 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
+installation (4.2 or later) 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>
@@ -170,44 +181,74 @@ file like this:</p>
<eclipse-equinox-launcher>
${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar
</eclipse-equinox-launcher>
+%lt;uima-eclipse-jar-processor>
+ ${uima-maven-build-eclipse-home}/plugins/org.eclipse.equinox.p2.jarprocessor_1.0.200.v20110808-1657.jar
+%lt;/uima-eclipse-jar-processor>
</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
+
+<p>
+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>
+Composite collection. If so, update buildCompositeRepository.xml
+in the build/trunk/uima-eclipse-composite-update-site
+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).
+In that project, run the Eclipse category editor on the file
+category.xml and update the categories. You must add any new
+features to one (or more) categories, for them to be "visible";
+this includes new versions of existing features. If you are
+changing categories, this is where that is done, also; but that
+is probably a rare occurrence.
</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.
+Each update site "build" will use the pom to pull into .../target/eclipse-update-site
+the complete set of features and plugins for that sub-site.
+It does this using information specified in the POM,
+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.
+Therefore, you must edit the POM to specify the new versions
+of any of the features and plugins being released, adding those
+to the lists inside of the build step that copies the plugin and feature
+artifacts.
</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
+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="Earlier Optimizations (Historical)">
+<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="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>