Tycho/eclipse-repository

The packaging type eclipse-repository is 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 eclipse-repository projects:

• category.xml (optional): Selects features for the p2 repository and specifies how to categorize them in the p2 installation dialog.

  Example:

  <?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>
  

  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".

  Editor support: category.xml files can be edited with the PDE's Category Manifest Editor.
  
  

• <productName>.product (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 this usage scenario for how to also create a product installation in the build.

  Example:

  <?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>
  

  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.

  Editor support: product files can be edited with the PDE's Product Configuration Editor.
  
  

• <productName>.p2.inf (optional): p2 advice file for low-level customizations of the p2 metadata produced from the product file.

  Editor support: None. Only suitable for advanced users.

Build results

The main artifact of an eclipse-repository project is a zipped p2 repository.

The content of the p2 repository content is aggregated in the following way:

1. The categories and products defined in the project are included into the p2 repository.
2. 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 includeAllDependencies to true. See also this usage scenario.

Build steps

The eclipse-repository packaging types includes the following build steps:

Build step	Summary
tycho-packaging-plugin:build-qualifier-aggregator	Determines the replacement value for qualifier literals in product versions
tycho-p2-publisher-plugin:publish-products	Translates the product files into p2 metadata
tycho-p2-publisher-plugin:publish-categories	Translates the category.xml into p2 metadata
tycho-p2-repository-plugin:assemble-repository	Aggregates the p2 metadata and artifacts into a p2 repository
tycho-p2-repository-plugin:archive-repository	Compresses the p2 repository to a zip file
maven-install-plugin:install	Writes the zipped p2 repository to the local Maven repository
maven-deploy-plugin:deploy	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 includeAllDependencies parameter of the tycho-p2-repository-plugin to true:

<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>

Creating product distributions

The packaging type eclipse-repository 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:

<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>

If the eclipse-repository 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:

Build step	Summary
tycho-p2-director-plugin:materialize-products	Creates installations for the products defined in the project.
tycho-p2-director-plugin:archive-products	Creates archives with the product installations