Wednesday, July 18, 2012

Pre-indexing documentation with tycho

Older Eclipses had this irritating feature of indexing help on first access. I think that many of you remember that :-). The issue has been fixed in Eclipse 3.1. Wait. Actually only the mechanism to do the indexing at build time was delivered, and all content providers should have used it.

The indexing at build time was usually achieved by two steps:
1. Declare an extension saying where your index will be created:
<extension point="org.eclipse.help.toc">
   <index path="index">
   </index>
</extension>

2. Ensure that the index is actually built via customBuildCallbacks.xml
<project name="Build specific targets and properties" default="noDefault">
    <target name="post.build.jars">
        <help.buildHelpIndex manifest="plugin.xml" destination="."/>
    </target>
</project>
The problem with the customBuildCallbacks is that it allows for to much creativity, which is nearly as desired in build systems as in accountancy :). Thus it should not be used. So, the question is, how to make it work with maven? I wish the answer was simple, but I have no other choice then present it in the most brutal form of xml:
<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.tycho.extras
            <artifactId>tycho-eclipserun-plugin</artifactId>
            <!-- this is actually present in any 0.14+ version -->
            <version>0.16.0-SNAPSHOT</version>
            <configuration>
                <!-- this is to fix some lucene 3.x compatibility issue -->
		<argLine>-Dhelp.lucene.tokenizer=standard</argLine>
                <!-- actuall indexer call -->
		<appArgLine>-application org.eclipse.ant.core.antRunner -buildfile customBuildCallbacks.xml build.index</appArgLine>
                <dependencies>
                    <!-- list of bundles that we need -->
                    <dependency>
                        <artifactId>org.eclipse.ant.core</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
		    <dependency>
                        <artifactId>org.apache.ant</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
                    <dependency>
                        <artifactId>org.eclipse.help.base</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
                </dependencies>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>eclipse-run</goal>
                    </goals>
                    <phase>compile</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
It should be read as: assemble an eclipse with org.apache.core,org.eclipse.ant.core, org.eclipse.help.base and all required dependencies, and then invoke the indexer. I hope this will be useful to someone during migration to tycho :-). Best regards Sources: Eclipse Help and Tycho wiki.

2 comments:

  1. There is a little typo - the antRunner target should be the same as the target name in the customBuildCallbacks.xml i.e. post.build.jars rather than build.index

    ReplyDelete
    Replies
    1. Thanks for the comment. This is intentional - although may be questioned. The point is to call as little from customBuildCallbacks as possible. In the original I had direct call to the indexer without the xml at all, but that would be to much hardcore...

      Delete