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/Dependency Resolution Troubleshooting"

(Work in progress)
 
m (be more clear that TP resolution is not dependency resolution)
 
(3 intermediate revisions by one other user not shown)
Line 15: Line 15:
 
</pre>
 
</pre>
  
Details:
+
Details on the parts of the message:
* <code>Resolving dependencies of ...</code>
+
* <code>Resolving dependencies of MavenProject ...</code>
: This line prints the Maven groupId, artifactId, and version and the file system location of the project whose dependencies are being resolved.
+
: This line prints the Maven groupId, artifactId, and version and the file system location of the project being resolved.
* <code>Software being installed</code>
+
* <code>Software being installed: ...</code>
: ...
+
: This line prints the seed of the dependency resolution, i.e. the artifact whose dependencies are being resolved. This is typically the main artifact of the project, but it could also be one of the artifacts specified as <tt>extraRequirements</tt> (TODO link to documentation).
 +
* <code>Missing requirement: &lt;artifact&gt; requires '&lt;dependency&gt;' but it could not be found</code>
 +
: This line prints one of the mandatory dependencies which cannot be resolved. This can either be a dependency of the seed artifact, or a dependency of an artifact which is a direct or transitive dependency of the seed artifact. See below for details on the &lt;dependency&gt; part of the message.
 +
* <code>Cannot satisfy dependency: &lt;artifact&gt; depends on: &lt;dependency&gt;</code>
 +
: In case the missing requirement is not on the seed artifact directly, the error message contains one or more of these lines. They trace the chain of dependencies from the seed artifact to the artifact with the missing requirement.
 +
 
 +
The message may also look like this
 +
<pre>
 +
[ERROR] Cannot resolve project dependencies:
 +
[ERROR]  You requested to install 'com.mycorp.feature.feature.group 0.0.0' but it could not be found
 +
</pre>
 +
 
 +
Details on this message:
 +
* <code>You requested to install '<reference>' but it could not be found</code>
 +
: This message is shown when one of the <tt>extraRequirements</tt> specified in the <tt>target-platform-configuration</tt> cannot be resolved. The &lt;reference&gt; is printed in the same format as the dependencies in missing requirements messages (see below for details).
 +
 
 +
=== Understanding missing requirement messages ===
 +
 
 +
Requirements in the p2 error messages consist of three parts: type (optional), ID, and version range.
 +
 
 +
When the requirement string includes a type, it is either <code>package</code> for an <tt>Import-Package</tt> dependency of a bundle, or <code>bundle</code> for <tt>Require-Bundle</tt> dependency of a bundle. In case the type is omitted, the requirement is specified in terms of the p2 ID of the required artifact (or more precisely, the ID of the "p2 installable unit"; installable units are the entities on which the p2 resolver works, and most installable units represent an artifact).
 +
 
 +
For most types of Eclipse artifacts, the p2 IDs are identical to the Eclipse IDs. So from an error message <code>... requires 'org.example.foo 0.0.0' but it could not be found</code> you can read that the artifact on the left-hand side requires an artifact with p2 ID <tt>org.example.foo</tt>. Most likely, the requirement expects a bundle with this ID as <tt>Bundle-SymbolicName</tt>.
 +
 
 +
For features however, the p2 IDs differ from the Eclipse IDs: The p2 ID of a feature is the feature ID with a <tt>.feature.group</tt> suffix. So for example <code>Missing requirement: com.mycorp.feature.feature.group 1.0.0.qualifier requires 'org.eclipse.rcp.feature.group 0.0.0' ...</code> tells you that the feature <tt>com.mycorp.feature</tt> has an unresolved dependency to the feature <tt>org.eclipse.rcp</tt>.
 +
 
 +
The version range has one of the following forms:
 +
* <code>1.2.3.something</code> - a single version: This stands for "version '1.2.3.something' or higher", i.e. the dependency only constrains the required artifact's version with a lower bound. Consequently, <code>0.0.0</code> stands for "any version".
 +
* <code>[1.2.3,1.3.0)</code> - two versions in brackets: This stands for "a version between '1.2.3' (inclusive) and '1.3.0' (exclusive)". The type of the brackets indicated whether the lower and upper bound is included (square brackets) or excluded (parentheses).
 +
* <code>[1.2.3.something]</code> - a single version in brackets: This stands for "strictly version '1.2.3.something'", i.e. the dependency is only satisfied by exactly one artifact. This kind of dependencies are also known as "strict version dependencies".
 +
 
 +
== Why can dependency XYZ not be resolved? ==
 +
 
 +
The candidate artifacts to match (="resolve") a dependency are the artifacts from the project's target platform. So if Tycho cannot resolve a dependency - and the artifact actually exists somewhere - it means that you do not have it included in the project's target platform. There are various ways to add artifacts to the target platform: See [[Tycho/Target Platform]].
 +
 
 +
Note that every project has its own target platform, although they are typically configured in the same way by specifying the target-platform-configuration and POM dependencies for <tt>pomDependencies=consider</tt> in the parent POM.
 +
 
 +
TODO: How to show the target platform content
 +
 
 +
== Differential diagnosis ==
 +
 
 +
This section explains other problems with similar symptoms, but which are not dependency resolution problems.
 +
 
 +
=== Target definition resolution errors ===
 +
 
 +
<pre>
 +
[ERROR] Cannot resolve target definition:
 +
</pre>
 +
 
 +
This error is message is shown (since Tycho 0.22.0) when a target definition is inconsistent. Target definition files are resolved by Tycho to compute the target platform of a project (see [[Tycho/Target Platform#Target files|here]] for more information). The target platform is needed for the dependency resolution, so this is a separate step before the dependency resolution. To address this problem, open the target definition file in Eclipse with the ''Target Definition Editor''. This editor should always be showing the same or a similar error message as Tycho - so you can attempt to fix the target definition there without having to run the Tycho build over and over again.
 +
 
 +
[[Category:Tycho|Dependency Resolution Troubleshooting]]

Latest revision as of 10:27, 10 October 2014

This page aims to provide help with understanding and analyzing dependency resolution errors that you may see in a Tycho build.

Error messages from p2

At the core of its dependency resolution, Tycho uses the constraint satisfaction engine of p2, the Eclipse provisioning platform. In case of a dependency resolution failure, Tycho displays the diagnostic message generated by p2. Since p2 is normally used to create or update Eclipse installations, the messages may sound confusing at first, but they contain valuable information. This section provides hints how to read these messages.

Example dependency resolution error message:

[INFO] Resolving dependencies of MavenProject: com.mycorp:com.mycorp.myplugin:0.1.0-SNAPSHOT @ C:\Source\MyProject\com.mycorp.myplugin\pom.xml
[INFO] {osgi.ws=win32, osgi.os=win32, osgi.arch=x86_64, org.eclipse.update.install.features=true}
[ERROR] Cannot resolve project dependencies:
[ERROR]   Software being installed: com.mycorp.myplugin 0.1.0.qualifier
[ERROR]   Missing requirement: com.mycorp.mylib 0.1.0.qualifier requires 'package org.eclipse.someproject [1.8.2,2.0.0)' but it could not be found
[ERROR]   Cannot satisfy dependency: com.mycorp.myplugin 0.1.0.qualifier depends on: bundle com.mycorp.mylib 0.0.0

Details on the parts of the message:

  • Resolving dependencies of MavenProject ...
This line prints the Maven groupId, artifactId, and version and the file system location of the project being resolved.
  • Software being installed: ...
This line prints the seed of the dependency resolution, i.e. the artifact whose dependencies are being resolved. This is typically the main artifact of the project, but it could also be one of the artifacts specified as extraRequirements (TODO link to documentation).
  • Missing requirement: <artifact> requires '<dependency>' but it could not be found
This line prints one of the mandatory dependencies which cannot be resolved. This can either be a dependency of the seed artifact, or a dependency of an artifact which is a direct or transitive dependency of the seed artifact. See below for details on the <dependency> part of the message.
  • Cannot satisfy dependency: <artifact> depends on: <dependency>
In case the missing requirement is not on the seed artifact directly, the error message contains one or more of these lines. They trace the chain of dependencies from the seed artifact to the artifact with the missing requirement.

The message may also look like this

[ERROR] Cannot resolve project dependencies:
[ERROR]   You requested to install 'com.mycorp.feature.feature.group 0.0.0' but it could not be found

Details on this message:

  • You requested to install '<reference>' but it could not be found
This message is shown when one of the extraRequirements specified in the target-platform-configuration cannot be resolved. The <reference> is printed in the same format as the dependencies in missing requirements messages (see below for details).

Understanding missing requirement messages

Requirements in the p2 error messages consist of three parts: type (optional), ID, and version range.

When the requirement string includes a type, it is either package for an Import-Package dependency of a bundle, or bundle for Require-Bundle dependency of a bundle. In case the type is omitted, the requirement is specified in terms of the p2 ID of the required artifact (or more precisely, the ID of the "p2 installable unit"; installable units are the entities on which the p2 resolver works, and most installable units represent an artifact).

For most types of Eclipse artifacts, the p2 IDs are identical to the Eclipse IDs. So from an error message ... requires 'org.example.foo 0.0.0' but it could not be found you can read that the artifact on the left-hand side requires an artifact with p2 ID org.example.foo. Most likely, the requirement expects a bundle with this ID as Bundle-SymbolicName.

For features however, the p2 IDs differ from the Eclipse IDs: The p2 ID of a feature is the feature ID with a .feature.group suffix. So for example Missing requirement: com.mycorp.feature.feature.group 1.0.0.qualifier requires 'org.eclipse.rcp.feature.group 0.0.0' ... tells you that the feature com.mycorp.feature has an unresolved dependency to the feature org.eclipse.rcp.

The version range has one of the following forms:

  • 1.2.3.something - a single version: This stands for "version '1.2.3.something' or higher", i.e. the dependency only constrains the required artifact's version with a lower bound. Consequently, 0.0.0 stands for "any version".
  • [1.2.3,1.3.0) - two versions in brackets: This stands for "a version between '1.2.3' (inclusive) and '1.3.0' (exclusive)". The type of the brackets indicated whether the lower and upper bound is included (square brackets) or excluded (parentheses).
  • [1.2.3.something] - a single version in brackets: This stands for "strictly version '1.2.3.something'", i.e. the dependency is only satisfied by exactly one artifact. This kind of dependencies are also known as "strict version dependencies".

Why can dependency XYZ not be resolved?

The candidate artifacts to match (="resolve") a dependency are the artifacts from the project's target platform. So if Tycho cannot resolve a dependency - and the artifact actually exists somewhere - it means that you do not have it included in the project's target platform. There are various ways to add artifacts to the target platform: See Tycho/Target Platform.

Note that every project has its own target platform, although they are typically configured in the same way by specifying the target-platform-configuration and POM dependencies for pomDependencies=consider in the parent POM.

TODO: How to show the target platform content

Differential diagnosis

This section explains other problems with similar symptoms, but which are not dependency resolution problems.

Target definition resolution errors

[ERROR] Cannot resolve target definition:

This error is message is shown (since Tycho 0.22.0) when a target definition is inconsistent. Target definition files are resolved by Tycho to compute the target platform of a project (see here for more information). The target platform is needed for the dependency resolution, so this is a separate step before the dependency resolution. To address this problem, open the target definition file in Eclipse with the Target Definition Editor. This editor should always be showing the same or a similar error message as Tycho - so you can attempt to fix the target definition there without having to run the Tycho build over and over again.

Back to the top