Introducing p2diff

There was a small problem when Eclipse Juno SR1 was released late last month. While I won’t bore you with the details (you can read about it on bug 390756), the crux of the problem is that the metadata for MacOS specified the launcher name with a capital ‘E’ (Eclipse) vs. eclipse.  This was a mistake in how the metadata was written and this lead to Eclipse installs with missing ini files.

Now you could argue that p2 should handle this more gracefully (which it should), but that doesn’t matter now. Since everyone already has Eclipse Juno SR0, fixing p2 at this point would not help. The only reasonable course of action is to fix the metadata and publish an SR1a. Thanks to Thomas Hallgren, we quickly got a new version of Buckminster which would publish the repository with the proper Eclipse launcher capitalization.  Markus Knauer then went to work and created new p2 repositories (SR1a).  But this lead to an important question: are there any other differences between SR1 and SR1a. We need to be sure that only the launcher named changed.

Since p2 repositories are simply an unordered set of Installable Units stored in an arbitrary data store (which is often XML, but doesn’t need to be), using a text based diff tool isn’t very useful. To help ensure that we didn’t introduce any unwanted changes to SR1a, I wrote a p2diff tool which compares (and pretty prints) the differences between two p2 repositories.

I’ve made the tool available on GitHub.  In addition to p2diff, I’ve also published a tutorial about how to construct such a tool. The tutorial is titled Eclipse p2 Tutorial: Managing Metadata.

p2diff can be used in a number of different ways. You can simply see which IUs exist in one repo, but not in another.  You can also ignore IU versions, which will show you when a new IU has been introduced. For example, here is the difference between the Programming Languages category in the Indigo release vs Juno

Finally, you can perform a deep compare, which will show you how the different parts of an IU have changed. This was very useful in helping us determine that only the name of the launcher changed between SR1 and SR1a.

Here is a complete list of the options available.

es-victoria:x86_64 irbull$ ./p2diff -h

NAME p2diff – Shows the differences between two p2 repositories

USAGE p2diff [options] repository1 repository2

DESCRIPTION Loads two p2 repositories and pretty prints the differences. The tool can be configured for high level differences, or it can show more detailed information about how specific IUs have changed.

The following options are available: -h Displays this message -onlylatest Only operate on the latest version of each IU -ignorecase When comparing IUs, the IDs are compared in a case insenstive way -mode=all Compare all IUs regardless of their ID -mode=ignoreVersions If an IU in each repository has the same ID, consider them equal, regardless of their version. -mode=deep If an IU in each repository has the same ID, compare the contents of the IU. -query=all Operate on ALL the IUs in a repository -query=groups Only operate on IUs that are marked as GROUPS -query=categorized Only operate on IUs that have been explicitly categorized -category= Used in conjunction with -query=categorized. This will only print IUs in a specific category

EXAMPLE USAGE Print the differences between the Juno and Indigo releases, but only show the items in the Programming Languages category.

./p2diff -query=categorized -mode=ignoreVersions -category=Programming Languages -onlylatest https://download.eclipse.org/releases/juno https://download.eclipse.org/releases/indigo

LICENSE p2Diff is licensed under the EPL. Copyright EclipseSource 2012. Maintained by Ian Bull.

I hope you find both the tool and the tutorial useful. If you have any feedback, leave me a message (or issue a pull request).