Difference between revisions of "Tycho/Target Platform"

From Eclipsepedia

Jump to: navigation, search
(364134 target platform includes implicit content from reactor/local Maven repo; use term "simple target platform config")
(380120 document multiple target files feature)
(16 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
Background: OSGi allows to specify dependencies with version ranges and package dependencies (<tt>Import-Package</tt>). These dependencies (intentionally) do not map to unique artifacts. In order to pick a set of concrete bundles to be used for compilation, test execution, and assembly, Tycho needs a set of candidate artifacts which may be used to match the dependencies. This list of candidate artifacts is called the "target platform". The process of selecting artifacts from the target platform according to the project's dependencies is called "dependency resolution".
 
Background: OSGi allows to specify dependencies with version ranges and package dependencies (<tt>Import-Package</tt>). These dependencies (intentionally) do not map to unique artifacts. In order to pick a set of concrete bundles to be used for compilation, test execution, and assembly, Tycho needs a set of candidate artifacts which may be used to match the dependencies. This list of candidate artifacts is called the "target platform". The process of selecting artifacts from the target platform according to the project's dependencies is called "dependency resolution".
  
There are different ways to define the target platform; the most common ones are repositories with layout=p2, which add entire p2 repositories to the target platform, or target definition files for more fine-grained control.
+
There are different ways to define the content of the target platform; the most common ones are repositories with layout=p2 in the POM, which add entire p2 repositories to the target platform, or target definition files for more fine-grained control.
  
 
=== Which approach should I use for the target platform for my project? ===
 
=== Which approach should I use for the target platform for my project? ===
  
Since there are a few different ways to configure a target platform in Tycho, here are some rule of thumbs for the most common cases:
+
Since there are a few different ways to configure a target platform in Tycho, here are some rules of thumb for the most common cases:
# If you are already using a target file in Eclipse, and that target file only contains <tt>location</tt> elements with <tt>type="InstallableUnit"</tt>, use that target file for the Tycho build. In all other cases, it is not possible to share the target platform configuration between Tycho and Eclipse.
+
# If you are already using a target file in Eclipse, and that target file only contains "Software Site" locations (i.e. <tt>location</tt> elements with <tt>type="InstallableUnit"</tt>), use that target file for the Tycho build. This approach is the only way to share the same target platform configuration between Tycho and Eclipse.
 
# If you don't care about individual bundles and versions, just configure the needed p2 repositories in the POM and have Tycho pick anything required from these repositories.
 
# If you don't care about individual bundles and versions, just configure the needed p2 repositories in the POM and have Tycho pick anything required from these repositories.
 
# If you want control over the which bundles/bundle versions are visible to the build, use a target file.
 
# If you want control over the which bundles/bundle versions are visible to the build, use a target file.
Line 14: Line 14:
 
=== Target platform configuration ===
 
=== Target platform configuration ===
  
The target platform is defined through POM configuration (see details below). Each module has its own target platform, although with the normal configuration inheritance in Maven, the target platform configurations are usually the same across multiple modules. In case multiple configuration approaches are combined (which should be rarely necessary), the target platform contains the union of the content defined through each approach.
+
The target platform is defined through POM configuration (see details below). Each module has its own target platform, although with the normal configuration inheritance in Maven, the target platform configurations are usually the same across multiple modules.
  
 +
<div id="Layout_p2">
 
==== Simple target platform configuration ====
 
==== Simple target platform configuration ====
  
Line 30: Line 31:
  
 
Background: In a normal (i.e. non-Tycho) Maven project, one can configure Maven repositories which can be used by Maven to resolve the project dependencies. While Maven repositories cannot be used directly (see [[#"POM dependencies consider"|below]] for an indirect approach), Tycho can use p2 repositories for resolving OSGi dependencies. The p2 repositories need to be marked with layout=p2. (The normal Maven dependency resolution ignores repositories with layout=p2.)
 
Background: In a normal (i.e. non-Tycho) Maven project, one can configure Maven repositories which can be used by Maven to resolve the project dependencies. While Maven repositories cannot be used directly (see [[#"POM dependencies consider"|below]] for an indirect approach), Tycho can use p2 repositories for resolving OSGi dependencies. The p2 repositories need to be marked with layout=p2. (The normal Maven dependency resolution ignores repositories with layout=p2.)
 +
</div>
  
 
==== Target files ====
 
==== Target files ====
  
The PDE target definition file format (*.target) allows to select a subset of units (bundles, features, etc.) from one or more p2 repositories. In order to add the content of a target definition file (see "Content" tab of the Target Editor) to the target platform in the Tycho build, configure the target file in the <tt>target-platform-configuration</tt> build plugin. Example:
+
The PDE target definition file format (*.target) allows to select a subset of units (bundles, features, etc.) from one or more p2 repositories. In order to add the content of a target definition file (see "Content" tab of the Target Editor) to the target platform in the Tycho build, place the target file in a [[Tycho/Packaging Types#eclipse-target-definition|eclipse-target-definition]] module and configure it in the <tt>target-platform-configuration</tt> build plugin. Example:
 
<pre>
 
<pre>
 
<plugin>
 
<plugin>
Line 45: Line 47:
 
             <artifactId>target-definition</artifactId>
 
             <artifactId>target-definition</artifactId>
 
             <version>1.0.0-SNAPSHOT</version>
 
             <version>1.0.0-SNAPSHOT</version>
            <classifier>targetFileNameWithoutExtension</classifier>
 
 
         </artifact>
 
         </artifact>
 
       </target>
 
       </target>
Line 51: Line 52:
 
</plugin>
 
</plugin>
 
</pre>
 
</pre>
The target definition file then needs to be placed in the root of project with the specified GAV.
 
  
'''Note:''' Tycho has only limited support for target definition files:
+
Since Tycho 0.17.0, it is also possible to configure multiple target files by specifying more than one <tt>&lt;artifact&gt;</tt> reference. Tycho interprets these target files independently and in the same way as in Eclipse: Each of the configured target files need to resolve successfully when opened in the Eclipse Target Editor. Note that the use of this Tycho feature is limited because the Eclipse PDE currently does ''not'' support activating more than one target file at once (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=392652 bug 392652]).
 +
 
 +
<p>'''Note:''' Tycho's support for the target definition file format is limited:
 
* The location types "Directory", "Installation", and "Features" are not supported.
 
* The location types "Directory", "Installation", and "Features" are not supported.
 
* The selection on the Content tab of the Target Editor is ignored, i.e. it is not possible to de-select individual bundles for the Tycho target platform.
 
* The selection on the Content tab of the Target Editor is ignored, i.e. it is not possible to de-select individual bundles for the Tycho target platform.
 +
* The option "Include source if available" is not supported.
 +
</p>
 +
 +
<p>'''Related Information'''
 +
* [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Ftarget_shared%2Flocation_edit_site_wizard.htm Target editor documentation]; section on [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Ftarget_shared%2Flocation_edit_site_wizard.htm "Software Site" locations]
 +
</p>
 +
 +
<div id="POM_Dependencies">
  
 
==== "POM dependencies consider" ====
 
==== "POM dependencies consider" ====
Line 64: Line 74:
  
 
This configuration has the following effect:
 
This configuration has the following effect:
* First, Maven resolves the GAV dependencies according to the normal Maven rules. This results in a list of artifacts with the specified artifacts and their transitive Maven dependencies.
+
* First, Maven resolves the GAV dependencies according to the normal Maven rules. This results in a list of artifacts consisting of the specified artifacts and their transitive Maven dependencies.
* Tycho then considers each of these artifacts for the target platform: if the artifact is an OSGi bundle, it is added to the target platform. Other artifacts are ignored. OSGi bundles which become part of the target platform in this way are then available to resolve the project's OSGi dependencies.
+
* Tycho then checks each of these artifacts, and ''if the artifact is an OSGi bundle'', it is added to the target platform. Other artifacts are ignored. OSGi bundles which become part of the target platform in this way are then available to resolve the project's OSGi dependencies.
  
For an example, see the POM of this [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-demo/itp02/build02 demo project].
+
For an example, see the POM of this [http://git.eclipse.org/c/tycho/org.eclipse.tycho-demo.git/tree/itp02/build02 demo project].
  
=== Implicit target platform content ===
+
'''Note''': Tycho always attempts to resolve transitive dependencies, so if you need a POM dependency in the target platform of one module, you will also need it in all downstream modules. Therefore the POM dependencies (and the <tt>pomDependencies</tt>=<tt>consider</tt> configuration) typically need to be added in the parent POM.
 +
</div>
  
Apart from the explicitly configured content, the target platform of a module also contains the following artifacts:
+
=== Effective content of the target platform ===
 +
 
 +
In case multiple target platform configuration approaches are combined, the target platform contains the union of the content defined through each approach.
 +
 
 +
Apart from the explicitly configured content, the target platform also contains the following artifacts:
 
* Other artifacts from the same [[Tycho/Glossary#Reactor|reactor]]
 
* Other artifacts from the same [[Tycho/Glossary#Reactor|reactor]]
 
* Locally built artifacts in the local Maven repository
 
* Locally built artifacts in the local Maven repository
  
TODO Option to exclude locally built artifacts from the target platform ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=355367 bug 355367])
+
Finally, it is possible to remove artifacts again from the target platform through a filtering syntax.
 +
 
 +
==== Locally built artifacts ====
 +
 
 +
Just like in a normal Maven build, a Tycho build can use artifacts that have been built locally and installed (e.g. with <tt>mvn clean install</tt>) into the local Maven repository. In terms of the target platform, this means that these artifacts are implicitly added to the target platform. This is for example useful if you want to rebuild a part of a Tycho reactor, or if you want to build against a locally built, newer version of an upstream project.
 +
 
 +
There are the following options to disable this feature:
 +
* Setting the CLI option <tt>-Dtycho.localArtifacts=ignore</tt> excludes locally built artifacts in one build. (<tt>tycho.localArtifacts=ignore</tt> may also be configured in the <tt>settings.xml</tt>; in this case, the default behaviour can be temporarily re-enabled with the CLI option <tt>-Dtycho.localArtifacts=default</tt>. Since Tycho 0.16.0.)
 +
* Deleting <tt>~/.m2/repository/.meta/p2-local-metadata.properties</tt> resets Tycho's list of locally build artifacts, and therefore these artifacts will not be added to target platforms (unless, of course, the artifacts are installed again).
 +
 
 +
==== Filtering ====
 +
 
 +
Since [[Tycho/Release Notes/0.14|Tycho 0.14.0]], it is possible to selectively remove content from the target platform. This for example allows to restrict the version of a bundle, or to select one particular provider for a package. Filtering is done as last step in the target platform computation, so the filters apply to all sources listed above.
 +
 
 +
The filters are specified in the <tt>target-platform-configuration</tt> build plugin:
 +
<pre>
 +
<plugin>
 +
  <groupId>org.eclipse.tycho</groupId>
 +
  <artifactId>target-platform-configuration</artifactId>
 +
  <version>${tycho-version}</version>
 +
  <configuration>
 +
      <filters>
 +
 
 +
        <!-- example 1: restrict version of a bundle -->
 +
        <filter>
 +
            <type>eclipse-plugin</type>
 +
            <id>org.eclipse.osgi</id>
 +
            <restrictTo>
 +
              <versionRange>[3.6,3.7)</versionRange> <!-- alternative: <version> for selecting exactly one versions -->
 +
            </restrictTo>
 +
        </filter>
 +
 
 +
        <!-- example 2: remove all providers of the package javax.persistence except the bundle javax.persistence -->
 +
        <filter>
 +
            <type>java-package</type>
 +
            <id>javax.persistence</id>
 +
            <restrictTo>
 +
              <type>eclipse-plugin</type>
 +
              <id>javax.persistence</id>
 +
            </restrictTo>
 +
        </filter>
 +
 
 +
        <!-- example 3: work around Equinox bug 348045 -->
 +
        <filter>
 +
            <type>p2-installable-unit</type>
 +
            <id>org.eclipse.equinox.servletbridge.extensionbundle</id>
 +
            <removeAll />
 +
        </filter>
 +
      </filters>
 +
  </configuration>
 +
</plugin>
 +
</pre>
 +
 
 +
'''Notes''':
 +
* The filters will only remove content from the target platform; they will not add new content. If you specify a restriction that is not fulfilled by any of the units from the target platform sources, all units that the filter applies to (i.e. units that match the <tt>filter.type</tt>, <tt>filter.id</tt>, and <tt>filter.version/versionRange</tt> criteria) will be removed from the target platform.
 +
* Package provider restrictions work by removing all other bundles exporting the package. This means that these other bundles (and the packages only exported by them) won't be available in your build.
  
 
=== Dependency resolution troubleshooting ===
 
=== Dependency resolution troubleshooting ===
  
TODO
+
TODO  
 +
 
 +
Run mvn with "-Dtycho.debug.resolver=true -X" to see debug output.
 +
 
 +
This will debug
 +
* Properties
 +
* Available IUs
 +
* JRE IUs
 +
* Root IUs
 +
 
 +
==== Listing IUs available ====
 +
 
 +
To list all the available IUs in an Eclipse repository (e.g. indigo), run:
 +
 
 +
<pre>
 +
$ java -jar plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar -debug -consolelog -application org.eclipse.equinox.p2.director -repository http://download.eclipse.org/releases/indigo/ -list
 +
</pre>
 +
 
 +
* Java is used (instead of the eclipse binary) so that the console output appears in the shell window instead of a spawned window
 +
* Make sure your shell is inside the Eclipse root directory
 +
* You will need to replace that version number for <tt>org.eclipse.equinox.launcher</tt> with the one found inside your Eclipse installation.
 +
* You will need to replace the Eclipse repository with the one you want a list of.
 +
 
 +
This can be used to double check availability of bundle versions, and compare with what Nexus thinks is available with the source Eclipse repository.
 +
 
 +
==== Browsing a p2 repository ====
  
 +
There is a graphical p2 browser (java webstart app) available on [https://github.com/ifedorenko/p2-browser github].
 +
Just follow the instructions in the README to start it.
  
 
[[Category:Tycho|Target Platform]]
 
[[Category:Tycho|Target Platform]]

Revision as of 10:14, 20 February 2013

The target platform is the set of artifacts from which Tycho resolves the project's dependencies.

Background: OSGi allows to specify dependencies with version ranges and package dependencies (Import-Package). These dependencies (intentionally) do not map to unique artifacts. In order to pick a set of concrete bundles to be used for compilation, test execution, and assembly, Tycho needs a set of candidate artifacts which may be used to match the dependencies. This list of candidate artifacts is called the "target platform". The process of selecting artifacts from the target platform according to the project's dependencies is called "dependency resolution".

There are different ways to define the content of the target platform; the most common ones are repositories with layout=p2 in the POM, which add entire p2 repositories to the target platform, or target definition files for more fine-grained control.

Contents

Which approach should I use for the target platform for my project?

Since there are a few different ways to configure a target platform in Tycho, here are some rules of thumb for the most common cases:

  1. If you are already using a target file in Eclipse, and that target file only contains "Software Site" locations (i.e. location elements with type="InstallableUnit"), use that target file for the Tycho build. This approach is the only way to share the same target platform configuration between Tycho and Eclipse.
  2. If you don't care about individual bundles and versions, just configure the needed p2 repositories in the POM and have Tycho pick anything required from these repositories.
  3. If you want control over the which bundles/bundle versions are visible to the build, use a target file.

Target platform configuration

The target platform is defined through POM configuration (see details below). Each module has its own target platform, although with the normal configuration inheritance in Maven, the target platform configurations are usually the same across multiple modules.

Simple target platform configuration

In order allow Tycho to resolve the project dependencies against anything from a specific p2 repository, add that repository in the <repositories> section of the POM. Example:

<repository>
   <id>eclipse-indigo</id>
   <url>http://download.eclipse.org/releases/indigo</url>
   <layout>p2</layout>
</repository>

In terms of the target platform, this means that the entire content of the p2 repositories specified in this way become part of the target platform.

Background: In a normal (i.e. non-Tycho) Maven project, one can configure Maven repositories which can be used by Maven to resolve the project dependencies. While Maven repositories cannot be used directly (see below for an indirect approach), Tycho can use p2 repositories for resolving OSGi dependencies. The p2 repositories need to be marked with layout=p2. (The normal Maven dependency resolution ignores repositories with layout=p2.)

Target files

The PDE target definition file format (*.target) allows to select a subset of units (bundles, features, etc.) from one or more p2 repositories. In order to add the content of a target definition file (see "Content" tab of the Target Editor) to the target platform in the Tycho build, place the target file in a eclipse-target-definition module and configure it in the target-platform-configuration build plugin. Example:

<plugin>
   <groupId>org.eclipse.tycho</groupId>
   <artifactId>target-platform-configuration</artifactId>
   <version>${tycho-version}</version>
   <configuration>
      <target>
         <artifact>
            <groupId>org.example</groupId>
            <artifactId>target-definition</artifactId>
            <version>1.0.0-SNAPSHOT</version>
         </artifact>
      </target>
   </configuration>
</plugin>

Since Tycho 0.17.0, it is also possible to configure multiple target files by specifying more than one <artifact> reference. Tycho interprets these target files independently and in the same way as in Eclipse: Each of the configured target files need to resolve successfully when opened in the Eclipse Target Editor. Note that the use of this Tycho feature is limited because the Eclipse PDE currently does not support activating more than one target file at once (see bug 392652).

Note: Tycho's support for the target definition file format is limited:

  • The location types "Directory", "Installation", and "Features" are not supported.
  • The selection on the Content tab of the Target Editor is ignored, i.e. it is not possible to de-select individual bundles for the Tycho target platform.
  • The option "Include source if available" is not supported.

Related Information

"POM dependencies consider"

OSGi bundles from Maven repositories can be added to the target platform in the following way:

  1. Specify a dependency to the OSGi bundle artifact in the POM's <dependencies> section.
  2. Set the configuration parameter pomDependencies=consider on the target-platform-configuration plugin

This configuration has the following effect:

  • First, Maven resolves the GAV dependencies according to the normal Maven rules. This results in a list of artifacts consisting of the specified artifacts and their transitive Maven dependencies.
  • Tycho then checks each of these artifacts, and if the artifact is an OSGi bundle, it is added to the target platform. Other artifacts are ignored. OSGi bundles which become part of the target platform in this way are then available to resolve the project's OSGi dependencies.

For an example, see the POM of this demo project.

Note: Tycho always attempts to resolve transitive dependencies, so if you need a POM dependency in the target platform of one module, you will also need it in all downstream modules. Therefore the POM dependencies (and the pomDependencies=consider configuration) typically need to be added in the parent POM.

Effective content of the target platform

In case multiple target platform configuration approaches are combined, the target platform contains the union of the content defined through each approach.

Apart from the explicitly configured content, the target platform also contains the following artifacts:

  • Other artifacts from the same reactor
  • Locally built artifacts in the local Maven repository

Finally, it is possible to remove artifacts again from the target platform through a filtering syntax.

Locally built artifacts

Just like in a normal Maven build, a Tycho build can use artifacts that have been built locally and installed (e.g. with mvn clean install) into the local Maven repository. In terms of the target platform, this means that these artifacts are implicitly added to the target platform. This is for example useful if you want to rebuild a part of a Tycho reactor, or if you want to build against a locally built, newer version of an upstream project.

There are the following options to disable this feature:

  • Setting the CLI option -Dtycho.localArtifacts=ignore excludes locally built artifacts in one build. (tycho.localArtifacts=ignore may also be configured in the settings.xml; in this case, the default behaviour can be temporarily re-enabled with the CLI option -Dtycho.localArtifacts=default. Since Tycho 0.16.0.)
  • Deleting ~/.m2/repository/.meta/p2-local-metadata.properties resets Tycho's list of locally build artifacts, and therefore these artifacts will not be added to target platforms (unless, of course, the artifacts are installed again).

Filtering

Since Tycho 0.14.0, it is possible to selectively remove content from the target platform. This for example allows to restrict the version of a bundle, or to select one particular provider for a package. Filtering is done as last step in the target platform computation, so the filters apply to all sources listed above.

The filters are specified in the target-platform-configuration build plugin:

<plugin>
   <groupId>org.eclipse.tycho</groupId>
   <artifactId>target-platform-configuration</artifactId>
   <version>${tycho-version}</version>
   <configuration>
      <filters>

         <!-- example 1: restrict version of a bundle -->
         <filter>
            <type>eclipse-plugin</type>
            <id>org.eclipse.osgi</id>
            <restrictTo>
               <versionRange>[3.6,3.7)</versionRange> <!-- alternative: <version> for selecting exactly one versions -->
            </restrictTo>
         </filter>

         <!-- example 2: remove all providers of the package javax.persistence except the bundle javax.persistence -->
         <filter>
            <type>java-package</type>
            <id>javax.persistence</id>
            <restrictTo>
               <type>eclipse-plugin</type>
               <id>javax.persistence</id>
            </restrictTo>
         </filter>

         <!-- example 3: work around Equinox bug 348045 -->
         <filter>
            <type>p2-installable-unit</type>
            <id>org.eclipse.equinox.servletbridge.extensionbundle</id>
            <removeAll />
         </filter>
      </filters>
   </configuration>
</plugin>

Notes:

  • The filters will only remove content from the target platform; they will not add new content. If you specify a restriction that is not fulfilled by any of the units from the target platform sources, all units that the filter applies to (i.e. units that match the filter.type, filter.id, and filter.version/versionRange criteria) will be removed from the target platform.
  • Package provider restrictions work by removing all other bundles exporting the package. This means that these other bundles (and the packages only exported by them) won't be available in your build.

Dependency resolution troubleshooting

TODO

Run mvn with "-Dtycho.debug.resolver=true -X" to see debug output.

This will debug

  • Properties
  • Available IUs
  • JRE IUs
  • Root IUs

Listing IUs available

To list all the available IUs in an Eclipse repository (e.g. indigo), run:

$ java -jar plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar -debug -consolelog -application org.eclipse.equinox.p2.director -repository http://download.eclipse.org/releases/indigo/ -list
  • Java is used (instead of the eclipse binary) so that the console output appears in the shell window instead of a spawned window
  • Make sure your shell is inside the Eclipse root directory
  • You will need to replace that version number for org.eclipse.equinox.launcher with the one found inside your Eclipse installation.
  • You will need to replace the Eclipse repository with the one you want a list of.

This can be used to double check availability of bundle versions, and compare with what Nexus thinks is available with the source Eclipse repository.

Browsing a p2 repository

There is a graphical p2 browser (java webstart app) available on github. Just follow the instructions in the README to start it.