Jump to: navigation, search

Minerva

Minerva is the Maven version of Athena.

At the moment, the code is hosted at GitHub but the plan is to have it hosted at eclipse.org...

git clone git://github.com/caniszczyk/minerva.git

Building

To build the project from the command line after checking the code out, simply run

mvn -Dskip.ui.tests clean install

In Maven, the parent pom.xml serves as the central point on adding things to the build. It's also generally the most complicated piece of the build as it contains information that is shared by children pom.xml files. The first part of the parent pom.xml we'll look at contains identifying information:

...
<groupId>org.aniszczyk.minerva</groupId>
<artifactId>minerva-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>

<name>Minvera Parent</name>
...

The second part contains profile information and where to get dependencies.

  <properties>
    <tycho-version>0.10.0</tycho-version>
    <platform-version-name>helios</platform-version-name>
    <eclipse-site>http://download.eclipse.org/releases/${platform-version-name}</eclipse-site>
    <wikitext-site>http://download.eclipse.org/tools/mylyn/update/weekly</wikitext-site>
    <swtbot-site>http://download.eclipse.org/technology/swtbot/${platform-version-name}/dev-build/update-site</swtbot-site>
  </properties>

  <profiles>
    <profile>
      <id>platform-helios</id>
      <activation>
        <property>
          <name>platform-version-name</name>
          <value>helios</value>
        </property>
      </activation>
      <properties>
        <eclipse-site>http://download.eclipse.org/releases/helios</eclipse-site>
        <platform-version>[3.6,3.7)</platform-version>
        <swtbot-site>http://download.eclipse.org/technology/swtbot/helios/dev-build/update-site</swtbot-site>
      </properties>
    </profile>
    <profile>
      <id>platform-indigo</id>
      <activation>
        <property>
          <name>platform-version-name</name>
          <value>indigo</value>
        </property>
      </activation>
      <properties>
        <eclipse-site>http://download.eclipse.org/releases/indigo</eclipse-site>
        <platform-version>[3.7,3.8)</platform-version>
        <swtbot-site>http://download.eclipse.org/technology/swtbot/indigo/dev-build/update-site</swtbot-site>
      </properties>
    </profile>
  </profiles>
...
  <repositories>
    <repository>
      <id>helios</id>
      <layout>p2</layout>
      <url>${eclipse-site}</url>
    </repository>
    <repository>
      <id>swtbot</id>
      <layout>p2</layout>
      <url>${swtbot-site}</url>
    </repository>
    <repository>
      <id>wikitext</id>
      <layout>p2</layout>
      <url>${wikitext-site}</url>
    </repository>
  </repositories>

The third part lists the modules (e.g., features, plug-ins) that are part of the build:

  <modules>
    <module>org.aniszczyk.minerva.core</module>
    <module>org.aniszczyk.minerva.ui</module>

    <module>org.aniszczyk.minerva-feature</module>
    <module>org.aniszczyk.minerva.source-feature</module>

    <module>org.aniszczyk.minerva.tests.core</module>
    <module>org.aniszczyk.minerva.tests.ui</module>

    <module>org.aniszczyk.minerva-updatesite</module>
   </modules>

Features

Features simply reference the parent pom and have a packaging attribute of eclipse-feature.

Here's a pom.xml snippet from the minerva feature:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva-feature</artifactId>
  <packaging>eclipse-feature</packaging>

  <name>Minerva Feature (Incubation)</name>

Plug-ins

Plug-ins simply reference the parent pom and have a packaging attribute of eclipse-plugin.

Here's a pom.xml snippet from the minerva core plug-in:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva.core</artifactId>
  <packaging>eclipse-plugin</packaging>

  <name>Minerva Core Plug-in</name>

Source

To package source with Tycho, you need first need a feature that contains the source plug-ins.

In Minerva, this is in org.aniszczyk.minerva.source-feature. The pom.xml is just like any feature with Tycho:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva.source-feature</artifactId>
  <packaging>eclipse-feature</packaging>

  <name>Minerva Sources Feature</name>

The important part is that your feature.xml references the plug-ins you want source for:

   <plugin
         id="org.aniszczyk.minerva.core.source"
         download-size="0"
         install-size="0"
         version="0.0.0"
         unpack="false"/>

   <plugin
         id="org.aniszczyk.minerva.ui.source"
         download-size="0"
         install-size="0"
         version="0.0.0"
         unpack="false"/>

Then in any plug-ins that you reference, you need to ensure their respective pom.xml contains a reference to the maven-osgi-source-plugin maven plug-in.

 <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.tycho</groupId>
        <artifactId>maven-osgi-source-plugin</artifactId>
      </plugin>
     ...
    </plugins>
  </build>

Repositories (Update Sites)

Plug-ins simply reference the parent pom and have a packaging attribute of eclipse-update-site.

Here's a pom.xml snippet from the minerva site:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva-updatesite</artifactId>
  <packaging>eclipse-update-site</packaging>

Tests

Tests are an important part of any software project. Tycho both supports headless and UI tests (with SWTBot).

Headless Tests

Headless tests simply reference the parent pom and have a packaging attribute of eclipse-test-plugin.

Here's a pom.xml snippet from the minerva core tests:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva.core.tests</artifactId>
  <packaging>eclipse-test-plugin</packaging>

  <name>Minerva Core Test Plug-in</name>

  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.tycho</groupId>
        <artifactId>maven-osgi-test-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <excludes>
            <!-- test mojo matches TestProject be default and treats it as PojoTest -->
            <exclude>**/Test*.class</exclude>
          </excludes>
          <useUIHarness>false</useUIHarness>
          <useUIThread>false</useUIThread>
        </configuration>
      </plugin>
     </plugins>
    </build>

Tycho does all the hard work and finds the tests to run as part of the build.

UI Tests

UI tests simply reference the parent pom and have a packaging attribute of eclipse-test-plugin.

Here's a pom.xml snippet from the minerva core tests:

  <parent>
    <groupId>org.aniszczyk.minerva</groupId>
    <artifactId>minerva-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>org.aniszczyk.minerva.ui.tests</artifactId>
  <packaging>eclipse-test-plugin</packaging>

  <name>Minerva UI Test Plug-in (Incubation)</name>

  <properties>
    <local-p2-site>file:/${basedir}/../org.aniszczyk.minerva-updatesite/target/site</local-p2-site>
    <ui.test.vmargs>-Xmx512m -XX:MaxPermSize=256m</ui.test.vmargs>
  </properties>

  <repositories>
    <repository>
      <id>local-p2</id>
      <layout>p2</layout>
      <url>${local-p2-site}</url>
    </repository>
  </repositories>

  <profiles>
    <profile>
      <id>skip-ui-tests</id>
      <activation>
        <property>
          <name>skip-ui-tests</name>
        </property>
      </activation>
      <properties>
        <maven.test.skip>true</maven.test.skip>
      </properties>
    </profile>
  </profiles>

  <build>
    <plugins>
      <plugin>
        <groupId>org.sonatype.tycho</groupId>
        <artifactId>maven-osgi-test-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <testSuite>org.aniszczyk.minerva.tests.ui</testSuite>
          <testClass>org.aniszczyk.minerva.tests.ui.AllTests</testClass>
          <useUIHarness>true</useUIHarness>
          <useUIThread>false</useUIThread>
          <product>org.eclipse.sdk.ide</product>
          <argLine>${ui.test.vmargs}</argLine>
          <application>org.eclipse.ui.ide.workbench</application>
          <dependencies>
            <dependency>
              <type>p2-installable-unit</type>
              <artifactId>org.eclipse.pde.feature.group</artifactId>
              <version>${platform-version}</version>
            </dependency>
            <dependency>
              <type>p2-installable-unit</type>
              <artifactId>org.aniszczyk.minerva.feature.group</artifactId>
              <version>[1.0.0,2.0.0)</version>
            </dependency>
            <dependency>
              <type>p2-installable-unit</type>
              <artifactId>org.eclipse.cvs.feature.group</artifactId>
              <version>[1.1.2,2.0.0)</version>
            </dependency>
           </dependencies>
        </configuration>
      </plugin>
     </plugins>
    </build>

In this case, we use the built in support in Tycho to launch an Eclipse to test the UI.

We also ensure any features are installed that we need (like our minerva feature).

Under the covers, the UI tests use SWTBot via @RunWith(SWTBotJunit4ClassRunner.class)

Documentation

TODO

Static Code Analysis

You can use code coverage by adding the proper maven plug-in dependencies in the parent pom.xml.

 <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>findbugs-maven-plugin</artifactId>
          <version>2.3.2-SNAPSHOT</version>
          <configuration>
            <findbugsXmlOutput>true</findbugsXmlOutput>
            <failOnError>false</failOnError>
          </configuration>
          <executions>
            <execution>
              <goals>
                <goal>check</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-pmd-plugin</artifactId>
          <version>2.5</version>
          <configuration>
            <sourceEncoding>utf-8</sourceEncoding>
            <minimumTokens>100</minimumTokens>
            <targetJdk>1.5</targetJdk>
            <format>xml</format>
            <failOnViolation>false</failOnViolation>
          </configuration>
          <executions>
            <execution>
              <goals>
                <goal>cpd-check</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>

In this example, we're using the findbugs-maven-plugin and maven-pmd-plugin maven plug-ins.

Then, to enable code coverage for each plug-in you have to update their respective pom.xml.

 <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>findbugs-maven-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-pmd-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

Code Coverage

TODO

Signing

If you release your code at eclipse.org, you should get it signed.

There's a /usr/bin/sign binary on build.eclipse.org that you feed a zip file containing your binaries.

Signing is a bit complicated on hudson.eclipse.org (see #332321).

TODO

Publishing

TODO