Monday, October 5, 2015

Tycho 13: Generating API documentation

If you want to add API documentation to your feature you want to make sure that documentation and implementation are consistent. Running javadoc manually is not ideal, better integrate documentation generation in your tycho build.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Create a help plug-in

We need a hosting plug-in for our API documentation. So create a new Plug-in Project named com.codeandme.tycho.help and mavenize it with Packaging set to eclipse-plugin. Add it to your master pom as usual.

Eclipse help is provided by adding extension points for org.eclipse.help.toc elements and according xml files. I will not go into details here as Lars did an excellent job with his tutorial on eclipse help.

For our project we provide 2 'classic' toc entries along with xml files: main.xml and reference.xml.

The third entry in plugin.xml (referring to help/api_docs.xml) does not have a corresponding xml file as we will create this one on the fly with maven.

We intend to generate documentation to a folder help/api-docs/javadoc. As tycho will not create this folder automatically, we need to add it manually.

Step 2: Configuring tycho

Documentation creation is a step we want to do for the help plug-in only. Therefore the following changes will go to com.codeandme.tycho.help/pom.xml and not to our master pom.
 <properties>
  <platform.api>org.eclipse.platform.doc.isv/reference/api</platform.api>
 </properties>

 <build>
  <plugins>
   <plugin>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-document-bundle-plugin</artifactId>
    <version>${tycho.extras.version}</version>
    <executions>
     <execution>
      <id>eclipse-javadoc</id>
      <phase>generate-resources</phase>
      <goals>
       <goal>javadoc</goal>
      </goals>
      <configuration>
       <outputDirectory>${project.basedir}/help/api-docs/javadoc</outputDirectory>
       <tocFile>${project.basedir}/help/api_docs.xml</tocFile>
       <tocOptions>
        <mainLabel>Tycho Tutorial API</mainLabel>
       </tocOptions>
       <javadocOptions>
        <!-- enable in case you need a proxy for web access 
        <jvmOptions>
         <jvmOption>-Dhttp.proxySet=true</jvmOption>
         <jvmOption>-Dhttp.proxyHost=proxy.example.com</jvmOption>
         <jvmOption>-Dhttp.proxyPort=81</jvmOption>
         <jvmOption>-DhttpnonProxyHosts=*.example.com</jvmOption>
        </jvmOptions>
         -->
        <additionalArguments>
         <additionalArgument>${javadoc-args}</additionalArgument>
         <additionalArgument>
          -link
          http://docs.oracle.com/javase/8/docs/api/
         </additionalArgument>
         <additionalArgument>
          -linkoffline
          ../../${platform.api}
          http://help.eclipse.org/mars/topic/org.eclipse.platform.doc.isv/reference/api/
         </additionalArgument>
         <additionalArgument>-public</additionalArgument>
        </additionalArguments>
       </javadocOptions>
      </configuration>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>
The property tycho.extras.version was added in our previous tutorial. Please add it to the master pom, if you did not do this already.

Lets look at some of the pom options:

Line 20 defines the TOC xml file to be created. Its display name is defined in line 22. TOC generation might be disabled by setting <skipTocGen>false</skipTocGen>
Lines 35-38 will add links to external documentation for standard java classes.
Lines 39-43 will add links to the eclipse API documentation typically shipped with every release.

Step 3: Define plug-ins for documentation creation

Typically you do not want to create documentation for all plug-ins. Test plug-ins for example should not show up there. Therefore we need to maintain a list of all plug-ins that should be considered by tycho.

This list is stored in com.codeandme.tycho.help/build.properties. Add them as extra classpath entries:
jars.extra.classpath = platform:/plugin/com.codeandme.tycho.plugin
To provide multiple plug-ins, add a comma-separated list (like for the bin.includes entry).

Tycho will create documentation for exported packages only. With the current project configuration com.codeandme.tycho.plugin does not export anything. You have to export a package there or tycho will fail to build.

Finally make sure to add the help folder to your binary build in build.properties.

Congratulations, you API documentation is now up to date for every build.

Thursday, October 1, 2015

Tycho 12: Build source features

Providing update sites containing source code for developers is considered good style. Used in a target platform it allows developers to see your implementation code. This makes debugging far easier as users do not need to checkout your source code from repositories they have to find first.

Tycho allows to package such repositories very easily.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.


Step 1: Create a source update site project

Create a new project of type Plug-in Development/Update Site Project. Name it com.codeandme.tycho.releng.p2.source and leave all the other settings to their defaults. You will end up in the Site Manifest Editor of your site.xml file. Instead of editing this file by hand we will immediately delete site.xml and copy over the category.xml file from com.codeandme.tycho.releng.p2.

Mavenize the project the same way as we did in tutorial 5: set Packaging to eclipse-repository and add the project to com.codeandme.tycho.releng/pom.xml.

Step 2: Modify category.xml

Source plug-ins and features will be created by tycho on the fly, so we have no real projects in the workspace we could add with the Site Manifest Editor. Therefore we need to open category.xml with the Text Editor. Tycho does not care about the url property, so remove it. Feature ids need to be changed to <original.id>.source.

If you like you can move all source features to a dedicated category:
<?xml version="1.0" encoding="UTF-8"?>
<site>
   <feature id="com.codeandme.tycho.plugin.feature" version="1.0.0.qualifier">
      <category name="source_components"/>
   </feature>
   <category-def name="source_components" label="Developer Resources"/>
</site>
Step 3: Configure tycho source builds

To enable source builds we need to extend com.codeandme.tycho.releng/pom.xml a bit. The source below contains only the additions to our pom file, so merge them accordingly (full version on github).
 <properties>
  <tycho.extras.version>${tycho.version}</tycho.extras.version>
 </properties>

 <build>
  <plugins>
   <!-- enable source feature generation -->
   <plugin>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-source-feature-plugin</artifactId>
    <version>${tycho.extras.version}</version>

    <executions>
     <execution>
      <id>source-feature</id>
      <phase>package</phase>
      <goals>
       <goal>source-feature</goal>
      </goals>
     </execution>
    </executions>

    <configuration>
     <excludes>
      <!-- provide plug-ins not containing any source code -->
      <plugin id="com.codeandme.tycho.product" />
     </excludes>
    </configuration>
   </plugin>

   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-source-plugin</artifactId>
    <version>${tycho.version}</version>

    <executions>
     <execution>
      <id>plugin-source</id>
      <goals>
       <goal>plugin-source</goal>
      </goals>
     </execution>
    </executions>
   </plugin>

   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-p2-plugin</artifactId>
    <version>${tycho.version}</version>
    <executions>
     <execution>
      <id>attached-p2-metadata</id>
      <phase>package</phase>
      <goals>
       <goal>p2-metadata</goal>
      </goals>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>
When building source plug-ins, tycho expects every plug-in project to actually contain source code. If projects do not contain source, we need to exclude them as we do on line 26.

After building the project we will end up with a p2 site containing binary builds and source builds of each feature/plug-in.