Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Tycho/eclipse-repository"

(added build results and usage scenarios section)
(add missing category)
 
(6 intermediate revisions by one other user not shown)
Line 1: Line 1:
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.
+
<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 ==
 
== Source files ==
Line 29: Line 46:
 
</li>
 
</li>
 
<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 configuration 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><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'':
 
<p>''Example'':
 
<pre>
 
<pre>
Line 58: Line 75:
 
</product>
 
</product>
 
</pre>
 
</pre>
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.
+
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>
<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]. Note that the <tt>installMode</tt> 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.<br/><br/></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>
 
<li>
 
<li>
Line 67: Line 84:
 
</li>
 
</li>
 
</ul>
 
</ul>
 
  
 
== Build results ==
 
== Build results ==
Line 74: Line 90:
  
 
The content of the p2 repository content is aggregated in the following way:
 
The content of the p2 repository content is aggregated in the following way:
# The categories and product configurations defined in the project are included into the p2 repository.
+
# 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.)
 
# 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]].
 
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 ==
 
== Build steps ==
  
TODO list included goals with links to sitedoc
+
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 ==
 
== Usage scenarios ==
Line 107: Line 152:
 
=== Creating product distributions ===
 
=== Creating product distributions ===
  
The packaging type <tt>eclipse-repository</tt> 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.
+
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:
 
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:
Line 119: Line 164:
 
         <executions>
 
         <executions>
 
             <execution>
 
             <execution>
               <id>materialize-products</id>
+
               <id>create-product-distributions</id>
 
               <goals>
 
               <goals>
 
                   <goal>materialize-products</goal>
 
                   <goal>materialize-products</goal>
              </goals>
 
            </execution>
 
            <execution>
 
              <id>archive-products</id>
 
              <goals>
 
 
                   <goal>archive-products</goal>
 
                   <goal>archive-products</goal>
 
               </goals>
 
               </goals>
Line 136: Line 176:
 
</pre>
 
</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. If you choose to materialize more than one product, you need to specify the <tt>attachId</tt> (which becomes a part of the classifier) to make the classifiers unique. Similarly, you can specify the root folder in the product zip files:
+
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:
 
+
<pre>
+
<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>
+
</pre>
+
  
The product installation can be configured through the following parameters:
+
{| 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
 +
|}
  
* <tt>rootFolder</tt>
+
[[Category:Tycho|eclipse-repository]]
: The path where the installed product shall be stored in the archive, e.g. <tt>eclipse</tt>. By default, the product is stored in the archive root.
+
* <tt>rootFolders</tt>
+
: OS-specific installation root folders, overriding <tt>rootFolder</tt>. Allowed children are <tt><macosx></tt>, <tt><win32></tt> and <tt><linux></tt> or any other OS available in P2. Starting from Tycho 0.18
+
* <tt>installFeatures</tt>
+
: true (default): Include the feature JARs in installation. (Technically, this sets the p2 profile property <tt>org.eclipse.update.install.features</tt> to true.)
+
: false: Omit the features folder in the installation.
+
* <tt>profile</tt>
+
: The name of the p2 profile to be used for the installation
+

Latest revision as of 16:27, 25 February 2015


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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.