In Part 1 of this series, I looked at use of composite repos to provide a way of combining update sites into a single URL for ease of use and a single point of entry from which to do updates.
In Part 2, I discussed why we switched from using a collection of SDKs against which to build - using the now-deprecated brute-force "just unzip into eclipse root folder or dropins" approach - to using a single target platform update site so as to simplify maintenance and provide a reusable artifact for both build and workspace provisioning.
Now, let's look at the no-brainer that says that "less is more" when it comes to telling p2 from where to get updates, and that less effort for your user when installing is always a win.
If this sounds familar, I did blog about this briefly back in August. Since then, we've also added a quick XSLT script to remove the "Uncategorized" category that Tycho automatically adds for features which are listed in your site.xml but are not associated with a category. While this isn't strictly related to associate sites, it is about ease of use; while I applaud the desire to have everything belong to a category bucket (perhaps because the model Tycho's using requires it), the reason we'd rather hide these is to declutter the install view and not confuse people by suggesting features that won't work on their OS (eg., for which there's no XulRunner port).
But I digress...
Associate Sites
In the old days of yore, you could situate an associateSites.xml next to your site.xml in your "classic" update site, and Eclipse Update Manager would happily read that file and add those extra sites to your list of available update sites.Then came p2, and while the old way still worked, it was no longer ideal. So, the new approach was to insert these associate sites directly into the p2 metadata for the site, content.xml and artifacts.xml (or content.jar and artifacts.jar).
This could be accomplished via a somewhat hacky appraoch - unpacking the existing metadata (content.jar) and shoehorning in the information at the bottom of the content.xml file, using an ant script (see "add.associate.sites" target, below) and a list of sites to be added:
<target name="add.associate.sites" if="associate.sites">
<if>
<and>
<!-- Defined in aggregateSite.properties -->
<isset property="associate.sites" />
<not>
<equals arg1="${associate.sites}" arg2="" />
</not>
</and>
<then>
<if>
<available file="${update.site.source.dir}/content.jar" type="file" />
<then>
<unzip src="${update.site.source.dir}/content.jar" dest="${update.site.source.dir}" />
<delete file="${update.site.source.dir}/content.jar" />
</then>
</if>
<!-- counter variable -->
<var name="associate.sites.0" value="" />
<for param="associate.site" list="${associate.sites}" delimiter=",
">
<sequential>
<var name="associate.sites.0" value="${associate.sites.0}00" />
</sequential>
</for>
<length property="associate.sites.length" string="${associate.sites.0}" />
<loadfile srcfile="${update.site.source.dir}/content.xml" property="content.xml">
<filterchain>
<tailfilter lines="-1" skip="1" />
</filterchain>
</loadfile>
<echo file="${update.site.source.dir}/content.xml" message="${content.xml}" />
<echo file="${update.site.source.dir}/content.xml" append="true"> <references size='${associate.sites.length}'>
</echo>
<for param="associate.site" list="${associate.sites}" delimiter=",
">
<sequential>
<!-- insert into content.xml -->
<echo file="${update.site.source.dir}/content.xml" append="true"> <repository uri='@{associate.site}' url='@{associate.site}' type='0' options='1'/>
<repository uri='@{associate.site}' url='@{associate.site}' type='1' options='1'/>
</echo>
</sequential>
</for>
<echo file="${update.site.source.dir}/content.xml" append="true"> </references>
</repository>
</echo>
<!--
workaround for Tycho bug: uncategorized features in site.xml are put into
"Uncategorized" category, rather than just being uncategorized (hidden)
-->
<copy file="${update.site.source.dir}/content.xml" tofile="${update.site.source.dir}/content.old.xml" overwrite="true" />
<xslt style="remove-uncategorized.xsl" in="${update.site.source.dir}/content.old.xml" out="${update.site.source.dir}/content.xml" />
<zip destfile="${update.site.source.dir}/content.jar" basedir="${update.site.source.dir}" includes="content.xml" />
<delete file="${update.site.source.dir}/content.xml" />
<delete file="${update.site.source.dir}/content.old.xml" />
</then>
</if>
</target>
So, now, instead of telling people to add multiple update sites to resolve missing potentially dependencies when installing, we can cause those extra sites to be automatically added at the same time they add the single URL for JBoss Tools. Now the additional sites need only be listed for reference, but no additional effort is required by the user.
BONUS HACK: to force a site that may already be listed (but disabled) to be added again, and this time definitely be enabled, you can add an extra slash into URL. Thus http://download.eclipse.org/birt/update-site/2.6 becomes http://download.eclipse.org//birt/update-site/2.6/, and as p2 sees a new site, it adds the new site (instead of ignoring it because it's already present but disabled. Again, a win.
Alternatively, you could cast an arcane spell using a p2.inf file in your feature's root folder or plugin's META-INF/ folder to add these additional, required sites... or do whatever processing you might need. I'm not sure if Tycho supports this yet, or how fully PDE supports reading this information. Got sample code? Send it to me as a comment below or via twitter to @nickboldt. Thanks!
In part 4, I'll talk a little about how to prevent your product build from getting updates from unofficial sources, and preload your product with the official sites from which to get updates. Because it's important to balance ease of use with prevention of unsupported features. SPOILER ALERT: may contain p2.inf instructions.
