Difference between revisions of "Tycho/eclipse-repository"

Revision as of 05:43, 7 March 2014

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 configuration 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 configuration 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. Note that the installMode attribute is an extension of the product file format which is currently not supported by the PDE, so you may need to re-insert the attribute after having used the 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 product configurations 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:

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 configuration meta-data. This meta-data 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>materialize-products</id>
               <goals>
                  <goal>materialize-products</goal>
               </goals>
            </execution>
            <execution>
               <id>archive-products</id>
               <goals>
                  <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. If you choose to materialize more than one product, you need to specify the attachId (which becomes a part of the classifier) to make the classifiers unique. Similarly, you can specify the root folder in the product zip files:

<build>
   <plugins>
      <plugin>
         <groupId>org.eclipse.tycho</groupId>
         <artifactId>tycho-p2-director-plugin</artifactId>
         <version>${tycho-version}</version>
         <executions>
            <execution>
               <id>materialize-products</id>
               <goals>
                  <goal>materialize-products</goal>
               </goals>
            </execution>
            <execution>
               <id>archive-products</id>
                  <goals>
                     <goal>archive-products</goal>
                  </goals>
            </execution>
         </executions>
         <configuration>
            <products>
               <product>
                  <id>some.product.id</id>
               </product>
               <product>
                  <id>other.product.id</id>
                  <attachId>other</attachId>

                  <!-- optional parameters (with default values) -->
                  <rootFolder></rootFolder>
                  <rootFolders>
                     <macosx></macosx>
                     <win32></win32>
                  </rootFolders>
               </product>
            </products>
            <!-- global optional parameters (with default values) -->
            <installFeatures>true</installFeatures>
            <profile>DefaultProfile</profile>
         </configuration>
      </plugin>
   </plugins>
</build>

The product installation can be configured through the following parameters:

• rootFolder

The path where the installed product shall be stored in the archive, e.g. eclipse. By default, the product is stored in the archive root.

• rootFolders

OS-specific installation root folders, overriding rootFolder. Allowed children are <macosx>, <win32> and <linux> or any other OS available in P2. Starting from Tycho 0.18

• installFeatures

true (default): Include the feature JARs in installation. (Technically, this sets the p2 profile property org.eclipse.update.install.features to true.)

false: Omit the features folder in the installation.

• profile

The name of the p2 profile to be used for the installation