View source for Tycho/eclipse-repository

<css>
table.nowrap-first-column td:first-child {
    white-space: nowrap;
}
/* this style exists in other MediaWikis but not here, so I define it inline */
table.wikitable {
    margin: 1em 0px;
    background-color: #F9F9F9;
    border: 1px solid #AAA;
    border-collapse: collapse;
    color: #000;
}
table.wikitable tr th, table.wikitable tr td {
    border: 1px solid #AAA;
    padding: 0.2em;
}
</css> 

The packaging type <tt>eclipse-repository</tt> is [[Tycho/Packaging Types|Tycho's packaging type]] for aggregating content into a p2 repository (aka "update site"). It can also be used for building Eclipse/RCP application distributions.

== Source files ==

The following source files are taken into account in <tt>eclipse-repository</tt> projects:

<ul>
<li>
<p><tt>category.xml</tt> (optional): Selects features for the p2 repository and specifies how to categorize them in the [http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.user/tasks/tasks-124.htm p2 installation dialog].</p>
<p>''Example'':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<site>
   <feature id="mytool.addon.feature" />
   <feature id="mytool.feature">
      <category name="mytool.category.id"/>
   </feature>
   <category-def name="mytool.category.id" label="My Tool">
      <description>
         My Eclipse tool built with Tycho
      </description>
   </category-def>
</site>
</pre>
With this category.xml, the features mytool.addon.feature and mytool.feature would be included into the p2 repository. mytool.feature would be shown in the category "My Tool", and mytool.addon.feature in the automatically created category "Uncategorized".</p>
<p>
''Editor support'': category.xml files can be edited with the PDE's [http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/editors/category_editor/definition_page.htm Category Manifest Editor].<br/><br/></p>
</li>
<li>
<p><tt>&lt;productName&gt;.product</tt> (optional): Defines a product configuration, which contains the information needed to create an Eclipse or RCP application installation. The product definition (and the content listed in it) is included in the p2 repository. See [[#Creating product distributions|this usage scenario]] for how to also create a product installation in the build.</p>
<p>''Example'':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<?pde version="3.5"?>

<product uid="mytool.product" id="org.eclipse.platform.ide" version="1.0.0.qualifier" useFeatures="true" includeLaunchers="true">

   <configIni use="default">
   </configIni>

   <launcherArgs>
      <vmArgsMac>-XstartOnFirstThread -Dorg.eclipse.swt.internal.carbon.smallFonts</vmArgsMac>
   </launcherArgs>

   <features>
      <feature id="org.eclipse.platform"/>
      <feature id="mytool.feature"/>
      <feature id="mytool.addon.feature" installMode="root"/>
   </features>

   <configurations>
      <plugin id="org.eclipse.core.runtime" autoStart="true" startLevel="0" />
      <plugin id="org.eclipse.equinox.common" autoStart="true" startLevel="2" />
      <plugin id="org.eclipse.equinox.ds" autoStart="true" startLevel="2" />
   </configurations>

</product>
</pre>
This example product definition would result in an Eclipse installation with the features org.eclipse.platform, mytool.feature, and mytool.addon.feature. The mytool.addon.feature would be marked as separately installed feature in the installation, so that it could be updated or uninstalled independently from the product.
</p>
<p>''Editor support'': product files can be edited with the PDE's [http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/editor.htm Product Configuration Editor].<br/><br/></p>
</li>
<li>
<p><tt>&lt;productName&gt;.p2.inf</tt> (optional): p2 advice file for low-level [[Equinox/p2/Customizing Metadata|customizations of the p2 metadata]] produced from the product file.</p>
<p>''Editor support'': None. Only suitable for advanced users.</p>
</li>
</ul>

== Build results ==

The main artifact of an <tt>eclipse-repository</tt> project is a zipped p2 repository.

The content of the p2 repository content is aggregated in the following way:
# The categories and products defined in the project are included into the p2 repository.
# Recursively, the features, bundles, and other content ''included'' by already included content is included in the repository. The following artifacts can specify includes of other artifacts: categories, products, and features. (Note: Due to technical limitations in the p2 metadata format, dependencies with a strict version range, i.e. a range which only matches exactly one version of an artifact, are also considered as includes.)

You can also configure the build to include ''all transitive dependencies'' (instead of only transitive includes) by setting [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-repository-plugin/assemble-repository-mojo.html#includeAllDependencies <tt>includeAllDependencies</tt>] to <tt>true</tt>. See also [[#Creating a self-contained p2 repository|this usage scenario]].


== Build steps ==

The <tt>eclipse-repository</tt> packaging types includes the following build steps:

{| class="wikitable nowrap-first-column"
|-
! Build step
!width=100%| Summary
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-packaging-plugin/build-qualifier-aggregator-mojo.html <tt>tycho-packaging-plugin:build-qualifier-aggregator</tt>]
| Determines the replacement value for <tt>qualifier</tt> literals in product versions
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-publisher-plugin/publish-products-mojo.html <tt>tycho-p2-publisher-plugin:publish-products</tt>]
| Translates the product files into p2 metadata
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-publisher-plugin/publish-categories-mojo.html <tt>tycho-p2-publisher-plugin:publish-categories</tt>]
| Translates the category.xml into p2 metadata
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-repository-plugin/assemble-repository-mojo.html <tt>tycho-p2-repository-plugin:assemble-repository</tt>]
| Aggregates the p2 metadata and artifacts into a p2 repository
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-repository-plugin/archive-repository-mojo.html <tt>tycho-p2-repository-plugin:archive-repository</tt>]
| Compresses the p2 repository to a zip file
|-
| [http://maven.apache.org/plugins/maven-install-plugin/install-mojo.html <tt>maven-install-plugin:install</tt>]
| Writes the zipped p2 repository to the local Maven repository
|-
| [http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html <tt>maven-deploy-plugin:deploy</tt>]
| Deploys the zipped p2 repository to a Maven repository manager. See [[Tycho/Nexus Unzip Plugin]] for one option to use the deployed zipped p2 repository.
|}


== Usage scenarios ==

=== Creating a self-contained p2 repository ===

When a p2 repository is self-contained, users can install from it without having to contact other p2 repositories/update sites. This may be useful if you have dependencies on artifacts from more exotic update sites (which are not pre-configured in a normal Eclipse installation), or if your users are in a restricted environment without Internet access.

In order to create a self-contained p2 repository, set the [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-repository-plugin/assemble-repository-mojo.html#includeAllDependencies <tt>includeAllDependencies</tt>] parameter of the <tt>tycho-p2-repository-plugin</tt> to <tt>true</tt>:
<pre>
<build>
   <plugins>
      <plugin>
         <groupId>org.eclipse.tycho</groupId>
         <artifactId>tycho-p2-repository-plugin</artifactId>
         <version>${tycho-version}</version>
         <configuration>
            <includeAllDependencies>true</includeAllDependencies>
         </configuration>
      </plugin>
   </plugins>
</build>
</pre>

=== Creating product distributions ===

The packaging type <tt>eclipse-repository</tt> creates a p2 repository, which contain the product definition metadata. This metadata can be used to install the product from the p2 repository (using the p2 director), or update an existing installation of your product.

Most likely however, you also want to create ready-to-use distribution archives of your product, which make it easier for your users to get the initial installation of your product. To accomplish this, add the following goals in the project's POM:
<pre>
<build>
   <plugins>
      <plugin>
         <groupId>org.eclipse.tycho</groupId>
         <artifactId>tycho-p2-director-plugin</artifactId>
         <version>${tycho-version}</version>
         <executions>
            <execution>
               <id>create-product-distributions</id>
               <goals>
                  <goal>materialize-products</goal>
                  <goal>archive-products</goal>
               </goals>
            </execution>
         </executions>
      </plugin>
   </plugins>
</build>
</pre>

If the <tt>eclipse-repository</tt> project contains more than one product file, you need to choose for which ones you want to create distribution archives. See the plugin documentation for how to do this and for other configuration options:

{| class="wikitable nowrap-first-column"
|-
! Build step
!width=100%| Summary
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-director-plugin/materialize-products-mojo.html <tt>tycho-p2-director-plugin:materialize-products</tt>]
| Creates installations for the products defined in the project.
|-
| [http://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-director-plugin/archive-products-mojo.html <tt>tycho-p2-director-plugin:archive-products</tt>]
| Creates archives with the product installations
|}

[[Category:Tycho|eclipse-repository]]