Google Git
Sign in
eclipse / virgo / org.eclipse.virgo.documentation / refs/heads/3.5.x / . / tooling-guide / src / wiki.xml
blob: dfd0228e8f489a7c94eb7244fd53f06738d17f27 [file] [log] [blame]
<?xml version='1.0' ?><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter>
<title>Installation and Release Notes</title>
<section id="Features">
<title>Features</title>
<para>The Virgo Tooling/IDE concept concerns the whole Virgo tooling (that was available inside SpringSource Tool Suite) being put in a separate project. The tooling supports the following: </para>
<itemizedlist>
<listitem>
<para>Bundle projects </para>
</listitem>
<listitem>
<para>Par projects </para>
</listitem>
<listitem>
<para>Plan files/projects </para>
</listitem>
<listitem>
<para>Web Bundles </para>
</listitem>
<listitem>
<para>Deployment to a Virgo Server in the server view.</para>
</listitem>
</itemizedlist>
</section>
<section id="Installation">
<title>Installation</title>
<section id="Install_Eclipse">
<title>Install Eclipse</title>
<para>If you're not installing into an existing Eclipse, you'll need one. </para>
<itemizedlist>
<listitem>
<para>Eclipse Helios SR2, or </para>
</listitem>
<listitem>
<para>Eclipse Indigo</para>
</listitem>
</itemizedlist>
<para>Eclipse JEE Indigo recommended.</para>
</section>
<section id="Install_Virgo">
<title>Install Virgo</title>
<orderedlist>
<listitem>
<para>Select
<emphasis role="italic">Help&gt;Install New Software..</emphasis>
</para>
</listitem>
<listitem>
<para>Enter one of the Virgo update sites below.</para>
</listitem>
<listitem>
<para>Select &quot;Virgo Tools&quot; feature and click install.</para>
</listitem>
</orderedlist>
</section>
<section id="Update_Sites">
<title>Update Sites</title>
<para>
<emphasis role="bold">Note, M4 is not quite here yet, so as of the moment you should use the snapshot build, not the milestone. As soon as M3 is formally released, this will change.</emphasis>
</para>
<variablelist>
<varlistentry>
<term>Milestone: &lt;code&gt;
<ulink url="http://download.eclipse.org/virgo/milestone/tooling&amp;lt;/code&amp;gt">http://download.eclipse.org/virgo/milestone/tooling&amp;lt;/code&amp;gt</ulink>;
</term>
</varlistentry>
<varlistentry>
<term>Snapshot: &lt;code&gt;
<ulink url="http://download.eclipse.org/virgo/snapshot/tooling&amp;lt;/code&amp;gt">http://download.eclipse.org/virgo/snapshot/tooling&amp;lt;/code&amp;gt</ulink>;
</term>
</varlistentry>
</variablelist>
<para>Many users will also want to install the M2E release at: &lt;code&gt;
<ulink url="http://download.eclipse.org/technology/m2e/releases&amp;lt;/code&amp;gt">http://download.eclipse.org/technology/m2e/releases&amp;lt;/code&amp;gt</ulink>;. (e.g. in order to run the greenpages examples.)
</para>
</section>
</section>
<section id="Known_Issues">
<title>Known Issues</title>
<section id="M4_Candidate_.28Current_Snapshot.29">
<title>M4 Candidate (Current Snapshot)</title>
<para>
<emphasis role="bold">The Virgo tools currently do not support Eclipse 3.6 (Helios) and derived Spring Source products.</emphasis> Please see:
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=377236">https://bugs.eclipse.org/bugs/show_bug.cgi?id=377236</ulink>.
</para>
<para>Significant bugs still exist. Please see these release train bugs for a current list, and please report any other issues you discover:</para>
<itemizedlist>
<listitem>
<para>368783: Server management UI bug train
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=368783">https://bugs.eclipse.org/bugs/show_bug.cgi?id=368783</ulink>
</para>
</listitem>
<listitem>
<para>368785: Server runtime support bug train
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=368785">https://bugs.eclipse.org/bugs/show_bug.cgi?id=368785</ulink>
</para>
</listitem>
<listitem>
<para>368782: Plugin packaging issues bug train
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=368782">https://bugs.eclipse.org/bugs/show_bug.cgi?id=368782</ulink>
</para>
</listitem>
</itemizedlist>
<para>You can see all open bugs
<ulink url="https://bugs.eclipse.org/bugs/buglist.cgi?list_id=1289794;query_format=advanced;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;component=tooling;product=Virgo">here</ulink>.
</para>
</section>
<section id="M3">
<title>M3</title>
<para>There wasn't one. :) We're moving to M4 to more closely align with Virgo Runtime releases.</para>
</section>
<section id="Milestone_M2">
<title>Milestone M2</title>
<section id="Version_Compatibility">
<title>Version Compatibility</title>
<para>The milestone does not work well with the current milestone of the runtime environment (&quot;3.1.0&quot; / 3.5.0). Please target the 3.0.2 Release Virgo Runtime or use the current milestone.</para>
</section>
</section>
</section>
<section id="Notes">
<title>Notes</title>
<section id="Web_Application_Bundles">
<title>Web Application Bundles</title>
<para>To create a web application bundle choose to create a normal bundle project, but on the Bundle Content panel select the additional property entitled &quot;Web Application Bundle&quot;. On the Bundle Properties panel enter a suitable context path for the application as the Web-ContextPath. </para>
</section>
<section id="Bundlor">
<title>Bundlor</title>
<para>Bundlor is not used by default, you must create you own template file and then turn on incremental manifest generation. </para>
</section>
<section id="PDE.2FEquinox_Bundles_not_supported_yet">
<title>PDE/Equinox Bundles not supported yet</title>
<para>Deploying PDE/Equinox Bundles to Virgo Web Server are not yet supported yet, although exporting the bundles (as Eclipse Plug-in JARs) and manually deploying to Virgo Web Server works. Please show your support on
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=329198">Bugzilla #329198</ulink>.
</para>
</section>
</section>
<section id="Migration">
<title>Migration</title>
<section id="From_Pre_M2_to_M3">
<title>From Pre M2 to M3</title>
<section id="Server_Versions">
<title>Server Versions</title>
<para>The good news: We have done away with the need for managing multiple server versions. This also means that we won't have to support multiple WebTools Server Runtimes and Servers which will make adding new servers and variants much easier. See
<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=373453">https://bugs.eclipse.org/bugs/show_bug.cgi?id=373453</ulink> for more details.
</para>
<para>The bad news: Any Server Runtimes that you already created for Virgo Server 3.5 will not work. But since Virgo Tooling didn't work with Virgo Server 3.5 *anyway*, this is sort of a moot issue.</para>
<para>What to do: If you have an existing (i.e., created using Virgo IDE installed before 10 March 2012) Virgo Server 3.5 Runtime defined, just delete it and replace it with a new Virgo Runtime in
<emphasis role="italic">Preferences:Server:Runtime Environments</emphasis>. You'll see that the correct version is discovered automatically. Then, open any Servers that uses the old runtime and select the new one from the Runtime Environment popup menu.
</para>
</section>
</section>
<section id="From_Spring_Source_and_Virgo_2.x_Tooling">
<title>From Spring Source and Virgo 2.x Tooling</title>
<para>Moving from the old tooling to the new requires some changes to your existing projects, these are documented here. </para>
<para>The Bundlor .settings file has a new name (
<emphasis role="italic">com.springsource.server.ide.bundlor.core.prefs</emphasis> -&amp;gt;
<emphasis role="italic">org.eclipse.virgo.ide.bundlor.core.prefs</emphasis>) and the property keys in it have new names as well. Currently these just need to be changed manually (replace
<emphasis role="italic">com.springsource.server</emphasis> by
<emphasis role="italic">org.eclipse.virgo</emphasis>)
<emphasis role="bold">or use the project properties pane to create new settings and delete the old one.</emphasis> (recommended)
</para>
<para>The Bundle Dependencies classpath entry has a new name (
<emphasis role="italic">com.springsource.server.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER</emphasis> -&amp;gt;
<emphasis role="italic">org.eclipse.virgo.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER</emphasis>). This can be changed manually (in the .classpath file) or in the Java Build Path section of the project properties.
</para>
<para>The attributes used to mark folders as test folders have been renamed (
<emphasis role="italic">com.springsource.server.ide.jdt.core.test.classpathentry</emphasis> -&amp;gt;
<emphasis role="italic">org.eclipse.virgo.ide.jdt.core.test.classpathentry</emphasis>). This can be changed manually (in the .classpath file).
</para>
<para>The PAR and Bundle nature have been renamed (
<emphasis role="italic">com.springsource.server.ide.facet.core.bundlenature</emphasis> -&amp;gt;
<emphasis role="italic">org.eclipse.virgo.ide.facet.core.bundlenature</emphasis> and (
<emphasis role="italic">com.springsource.server.ide.facet.core.parnature</emphasis> -&amp;gt;
<emphasis role="italic">org.eclipse.virgo.ide.facet.core.parnature</emphasis>)). This can be changed manually (in the .project file).
</para>
<para>The format and name of a PAR project changed. Rename
<emphasis role="italic">.settings/com.springsource.server.ide.runtime.core.par.xml</emphasis> to
<emphasis role="italic">.settings/org.eclipse.virgo.ide.runtime.core.par.xml</emphasis>. Inside the file rename occurences of
<emphasis role="italic">com.springsource.server</emphasis> to
<emphasis role="italic">org.eclipse.virgo</emphasis>.
</para>
<para>
<emphasis role="bold">Snapshot build change:</emphasis> We've made a change in our tooling that will require modifying the org.eclipse.virgo.ide.runtime.core.par.xml file so that it points to the correct par.ecore URI. Rename
<emphasis role="italic">xmlns:com.springsource.server.ide.par=&quot;
<ulink url="http:///com/springsource/server/ide/par.ecore&amp;quot">http:///com/springsource/server/ide/par.ecore&amp;quot</ulink>;
</emphasis> to
<emphasis role="italic">&quot;xmlns:org.eclipse.virgo.ide.par=&quot;
<ulink url="http://eclipse.org/virgo/par.ecore&amp;quot">http://eclipse.org/virgo/par.ecore&amp;quot</ulink>;
</emphasis>
</para>
<para>Inside the WST settings file (
<emphasis role="italic">.settings/org.eclipse.wst.common.project.facet.core.xml</emphasis>) rename occurences of
<emphasis role="italic">com.springsource.server.bundle</emphasis> to
<emphasis role="italic">org.eclipse.virgo.server.bundle</emphasis> and occurences of
<emphasis role="italic">com.springsource.server.par</emphasis> to
<emphasis role="italic">org.eclipse.virgo.server.par</emphasis>.
</para>
<para>Most/all of the conversion should be done by the following script (it has only see marginal testing, use at your own risk):
&lt; pre&gt;#!/bin/sh</para>
<orderedlist>
<listitem>
<para>NOTE1: Run this at your own risk&amp;nbsp;:)</para>
</listitem>
<listitem>
<para>NOTE2: I should quote more dots in sed expressions but I'm lazy.</para>
</listitem>
<listitem>
<para>TODO: Delete old com.springsource files after conversion</para>
</listitem>
</orderedlist>
<para>if
<ulink url="&amp;amp;nbsp;!">-d &amp;quot;$1&amp;quot; </ulink>; then
</para>
<literallayout> echo &amp;quot;Please point me at an eclipse project&amp;quot;&amp;amp;nbsp;;
exit 1
</literallayout>
<para>fi</para>
<orderedlist>
<listitem>
<para>Bundlor settings</para>
</listitem>
</orderedlist>
<para>f=&quot;$1/.settings/com.springsource.server.ide.bundlor.core.prefs&quot;
[ -f &quot;$f&quot; ] &amp;amp;&amp;amp; (</para>
<literallayout> echo &amp;quot;$1: Converting bundlor preferences&amp;quot;
sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' &amp;quot;$f&amp;quot; &amp;amp;gt; &amp;quot;$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)&amp;quot;
</literallayout>
<para>)</para>
<orderedlist>
<listitem>
<para>convert PAR</para>
</listitem>
</orderedlist>
<para>f=&quot;$1/.settings/com.springsource.server.ide.runtime.core.par.xml&quot;
[ -f &quot;$f&quot; ] &amp;amp;&amp;amp; (</para>
<literallayout> echo &amp;quot;$1: Converting PAR project dependencies&amp;quot;
sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' &amp;quot;$f&amp;quot; &amp;amp;gt; &amp;quot;$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)&amp;quot;
</literallayout>
<para>)</para>
<orderedlist>
<listitem>
<para>Fix classpaths </para>
</listitem>
</orderedlist>
<para>f=&quot;$1/.classpath&quot;
[ -f &quot;$f&quot; ] &amp;amp;&amp;amp; (</para>
<literallayout> echo &amp;quot;$1: Converting classpath containers and entries&amp;quot;
sed -i \
-e 's/com.springsource.server.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER/org.eclipse.virgo.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER/g' \
-e 's/com.springsource.server.ide.jdt.core.test.classpathentry/org.eclipse.virgo.ide.jdt.core.test.classpathentry/g' \
&amp;quot;$f&amp;quot;
</literallayout>
<para>)</para>
<orderedlist>
<listitem>
<para>Fix natures..</para>
</listitem>
</orderedlist>
<para>f=&quot;$1/.project&quot;
[ -f &quot;$f&quot; ] &amp;amp;&amp;amp; (</para>
<literallayout> echo &amp;quot;$1: Converting project natures&amp;quot;
sed -i \
-e 's/com.springsource.server.ide.facet.core.bundlenature/org.eclipse.virgo.ide.facet.core.bundlenature/g' \
-e 's/com.springsource.server.ide.facet.core.parnature/org.eclipse.virgo.ide.facet.core.parnature/g' \
&amp;quot;$f&amp;quot;
</literallayout>
<para>)</para>
<orderedlist>
<listitem>
<para>Fix the wst file, could also replace runtime name here</para>
</listitem>
</orderedlist>
<para>f=&quot;$1/.settings/org.eclipse.wst.common.project.facet.core.xml&quot;
[ -f &quot;$f&quot; ] &amp;amp;&amp;amp; (</para>
<literallayout> echo &amp;quot;$1: Converting org.eclipse.wst.common.project.facet.core.xml&amp;quot;
sed -i \
-e 's/com.springsource.server.bundle/org.eclipse.virgo.server.bundle/g' \
-e 's/com.springsource.server.par/org.eclipse.virgo.server.par/g' \
&amp;quot;$f&amp;quot;
</literallayout>
<para>)</para>
<para>&lt;/pre&gt;</para>
</section>
</section>
<section id="Maven_plugin">
<title>Maven plugin</title>
<para>To support the development of OSGi bundles for Eclipse Virgo with Maven a Maven plugin is available. This plugin is able to start/stop a local Eclipse Virgo instance. Moreover it is possible to deploy/undeploy/refresh bundles via Maven. </para>
<section id="Build">
<title>Build</title>
<para>In order to use the plugin one has to download the source code from
<ulink url="https://github.com/frieder/virgo-maven-plugin">Github</ulink>&amp;nbsp;and build the binary manually. This can be easily done by executing the following Maven command in the root folder of the plugin where the pom.xml file is located.
&lt; pre&gt;mvn clean install&lt;/pre&gt;
Moreover to generate the documentation just execute the following Maven command (or take the one provided in the repository on Github).
&lt; pre&gt;mvn clean&amp;nbsp;plugin:xdoc javadoc:javadoc jxr:jxr site
&lt; /pre&gt;
</para>
</section>
<section id="Goals">
<title>Goals</title>
<para>The plugin provides a set of Maven goals that allow different actions. </para>
<informaltable>
<tr>
<td>
<emphasis role="bold">Goal</emphasis>
</td>
<td>
<emphasis role="bold">Description</emphasis>
</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:start&lt;/code&gt; </td>
<td>Starts a Virgo instance by executing the provided startup script. &lt;br&gt; </td>
</tr>
<tr>
<td>&lt;code&gt;virgo:shutdown&lt;/code&gt; </td>
<td>Stops a running Virgo instance.</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:immediateShutdown&lt;/code&gt; </td>
<td>Stops a running Virgo instance immediately.</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:deploy&lt;/code&gt; </td>
<td>Deploys an OSGi bundle to a running Virgo instance.</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:undeploy&lt;/code&gt; </td>
<td>Undeploys an OSGi bundle from a running Virgo instance.</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:refresh&lt;/code&gt; </td>
<td>Refreshs an already installed module on a running Virgo instance.</td>
</tr>
<tr>
<td>&lt;code&gt;virgo:bundleRefresh&lt;/code&gt; </td>
<td>Refreshs an already installed OSGi bundle on a running Virgo instance.</td>
</tr>
</informaltable>
</section>
<section id="Simple_example_POM">
<title>Simple example POM</title>
<para>Once the plugin has been build and installed in the local Maven repository it can be used within a Maven project. Following is a simple example of a pom file that uses the Maven plugin.&amp;nbsp;
&lt; pre&gt;&amp;lt;project xmlns=&quot;
<ulink url="http://maven.apache.org/POM/4.0.0&amp;quot">http://maven.apache.org/POM/4.0.0&amp;quot</ulink>; xmlns:xsi=&quot;
<ulink url="http://www.w3.org/2001/XMLSchema-instance&amp;quot">http://www.w3.org/2001/XMLSchema-instance&amp;quot</ulink>;
xsi:schemaLocation=&quot;
<ulink url="http://maven.apache.org/POM/4.0.0">http://maven.apache.org/POM/4.0.0</ulink>
<ulink url="http://maven.apache.org/xsd/maven-4.0.0.xsd&amp;quot;&amp;amp;gt">http://maven.apache.org/xsd/maven-4.0.0.xsd&amp;quot;&amp;amp;gt</ulink>;
&amp;lt;modelVersion&amp;gt;4.0.0&amp;lt;/modelVersion&amp;gt;
&amp;lt;groupId&amp;gt;org.example.osgi&amp;lt;/groupId&amp;gt;
&amp;lt;artifactId&amp;gt;test-bundle&amp;lt;/artifactId&amp;gt;
&amp;lt;version&amp;gt;0.0.1-SNAPSHOT&amp;lt;/version&amp;gt;
&amp;lt;packaging&amp;gt;bundle&amp;lt;/packaging&amp;gt;
&amp;lt;name&amp;gt;OSGi Test Bundle&amp;lt;/name&amp;gt;
&amp;lt;properties&amp;gt;
&amp;lt;project.build.sourceEncoding&amp;gt;UTF-8&amp;lt;/project.build.sourceEncoding&amp;gt;
&amp;lt;/properties&amp;gt;
&amp;lt;build&amp;gt;
&amp;lt;plugins&amp;gt;
&amp;lt;plugin&amp;gt;
&amp;lt;groupId&amp;gt;org.apache.felix&amp;lt;/groupId&amp;gt;
&amp;lt;artifactId&amp;gt;maven-bundle-plugin&amp;lt;/artifactId&amp;gt;
&amp;lt;version&amp;gt;2.3.6&amp;lt;/version&amp;gt;
&amp;lt;extensions&amp;gt;true&amp;lt;/extensions&amp;gt;
&amp;lt;configuration&amp;gt;
&amp;lt;instructions&amp;gt;
&amp;lt;Bundle-SymbolicName&amp;gt;${project.groupId}.${project.artifactId}&amp;lt;/Bundle-SymbolicName&amp;gt;
&amp;lt;Bundle-Name&amp;gt;${project.name}&amp;lt;/Bundle-Name&amp;gt;
&amp;lt;Bundle-Version&amp;gt;${project.version}&amp;lt;/Bundle-Version&amp;gt;
&amp;lt;/instructions&amp;gt;
&amp;lt;/configuration&amp;gt;
&amp;lt;/plugin&amp;gt;
&amp;lt;plugin&amp;gt;
&amp;lt;groupId&amp;gt;net.flybyte.virgo&amp;lt;/groupId&amp;gt;
&amp;lt;artifactId&amp;gt;virgo-maven-plugin&amp;lt;/artifactId&amp;gt;
&amp;lt;version&amp;gt;1.0.0&amp;lt;/version&amp;gt;
&amp;lt;configuration&amp;gt;
&amp;lt;virgoRoot&amp;gt;C:/Java/virgo-tomcat-server-3.0.2.RELEASE&amp;lt;/virgoRoot&amp;gt;
&amp;lt;/configuration&amp;gt;
&amp;lt;/plugin&amp;gt;
&amp;lt;/plugins&amp;gt;
&amp;lt;/build&amp;gt;
&amp; lt;/project&amp;gt;
&lt; /pre&gt;
More examples can be found in the documentation. Following are some exemplary Maven commands.
&lt; pre&gt;mvn virgo:start &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;lt;-- will start a Virgo instance
mvn clean package virgo:deploy &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp; &amp;nbsp;&amp;lt;-- will create an artifact and deploy it to Virgo&lt;/pre&gt;
</para>
</section>
</section>
<section id="Importing_Virgo_Projects_into_Eclipse">
<title>Importing Virgo Projects into Eclipse</title>
<para>See
<ulink url="http://wiki.eclipse.org/Virgo/Committers#Eclipse_Setup">Eclipse Setup</ulink> under the Committers tab.
</para>
<para>
<ulink url="/wiki/Category:Virgo">Category:Virgo</ulink>
<ulink url="/wiki/Category:EclipseRT">Category:EclipseRT</ulink>&lt;/rev&gt;&lt;/revisions&gt;&lt;/page&gt;&lt;/pages&gt;&lt;/query&gt;&lt;/api&gt;
</para>
</section>
</chapter>