ESF Addon Archetype

The ESF Addon Archetype is a Maven archetype that simplifies the process of creating a new ESF add-on. It creates a development environment with the following features:

Maven-based build
Tycho-surefire-based integration test template
Eclipse Emulator
Uses a remote P2 repository for the target platform

The ESF Archetype jar (esf-addon-archetype-<esf-version>.jar) must be downloaded from the Eurotech Website and installed in the local maven repository with the following command:

mvn install:install-file -Dfile=./esf-addon-archetype-<esf-version>.jar \
-DgroupId=com.eurotech.framework -DartifactId=esf-addon-archetype -Dversion="<esf-version>" \ 
-Dpackaging=jar -DgeneratePom=true

After that, it is possible to generate a project skeleton using the archetype with the following command:

mvn archetype:generate -DarchetypeArtifactId=esf-addon-archetype \
-DarchetypeGroupId=com.eurotech.framework \
-DarchetypeVersion="<esf-version>"

The command will start the generation of the archetype in interactive mode.

Maven will ask for a few parameters on the command line:

groupId: the Maven group ID of the generated POM files
artifactId: the Maven artifact ID of the generated parent POM file and the name of the generated top-level project folder
version: the Maven version of the generated projects — currently, it must be a SNAPSHOT version
package: the Java package to be used for the main bundle

The following properties can be changed by answering n after the Confirm properties configuration prompt, which appears after editing the properties above.

mainBundleSymbolicName: the symbolic name for the main bundle of the project
mainBundleVendor: the vendor for the main bundle
targetPlatformP2Repo: the URL of the p2 repository to be used. The ESF archetype expects this URL to point to the ESF p2 repository. The repository URL and content can also be changed later using Eclipse. The URL for the ESF p2 repository is:

https://s3.amazonaws.com/esf-p2/ESF_<esf-version>_latest/repository

At the end of the procedure, in the location where the Maven archetype generation has been run, the archetype will generate a subfolder in the working directory containing the following subfolders:

bundles: the directory where developed bundles can be placed. After the first archetype execution, this directory contains a single project, whose artifact ID is the one configured during the archetype generation process explained above.
features: contains Eclipse features and is meant to simplify the build of Deployment Packages, which can be found in the target directory of the feature. After the first archetype execution, this directory contains a feature for the main bundle. The user can add more features to create more complex deployment packages, for example, to package a host bundle along with a native library fragment.
target-definition: The .target file contained in the project is the way to specify the project dependencies and points to the ESF P2 repository. With this setup, the Eclipse IDE and Tycho Maven build share the same target platform so that if the Maven build fails, the same errors should be displayed by the Eclipse IDE. Maven dependencies should not be added to the build, not even test dependencies, as this will lead to non-reproducible builds.
tests: contains OSGi integration tests executed by the tycho-surefire-plugin.

Building

Make sure Java 8 is installed on the system and that Maven is using it. This can be verified by running:

mvn -version

To build all the bundles, features, and run the tests, execute:

mvn clean install -Dtycho.localArtifacts=ignore

Setting tycho.localArtifacts=ignore is recommended to limit the contents of the effective target platform, as described here. Note, however, that this setting cannot always be used — for example, if you want to perform a partial build to build only the tests.

Importing Projects in Eclipse IDE

If the project is put under Git version control, it is a good idea to add a .gitignore file to avoid committing files that are not necessary for the Maven build.

In Eclipse IDE import the projects with File | Import | Maven | Existing Maven Projects.

Note that the parent POM file cannot be selected.

Open the .target file in the target-definition project and click on Set as Active Target Platform. Note that this will download the bundles from the ESF P2 repository and it may take a while to complete.

Eclipse IDE should rebuild the workspace automatically and show no errors. Please make sure that also the Eclipse IDE has Java 8 as selected JRE and compiler target.

[!TIP] The Eclipse IDE may not be able to correctly identify the source code. If that happen, add the following plugin definition in the bundles > pom.xml in the pluginManagement > plugins section:

<!-- This plugin's configuration is used to store Eclipse m2e
settings only. It has no influence on the Maven build itself. -->
<plugin>
    <groupId>org.eclipse.m2e</groupId>
    <artifactId>lifecycle-mapping</artifactId>
    <version>1.0.0</version>
    <configuration>
        <lifecycleMappingFilters>
            <lifecycleMappingFilter>
                <symbolicName>org.eclipse.m2e.pde.connector</symbolicName>
                <versionRange>[2.1.2,)</versionRange>
                <packagingTypes>
                    <packagingType>eclipse-test-plugin</packagingType>
                    <packagingType>eclipse-plugin</packagingType>
                    <packagingType>eclipse-feature</packagingType>
                </packagingTypes>
            </lifecycleMappingFilter>
        </lifecycleMappingFilters>
        <lifecycleMappingMetadata>
            <pluginExecutions>
                <pluginExecution>
                    <pluginExecutionFilter>
                        <groupId>biz.aQute.bnd</groupId>
                        <artifactId>bnd-maven-plugin</artifactId>
                        <versionRange>[0.0.0,)</versionRange>
                        <goals>
                            <goal>bnd-process</goal>
                        </goals>
                    </pluginExecutionFilter>
                    <action>
                        <ignore />
                    </action>
                </pluginExecution>
            </pluginExecutions>
        </lifecycleMappingMetadata>
    </configuration>
</plugin>

Adding Bundles

Existing bundles can be copied in the directory bundles. If the bundle has already a POM file, this must be replaced. The project must be also added to the <modules> of bundles/pom.xml. If a deployment package is desired, a new feature must be created in the directory features; take a look to the existing feature.

Include dependencies

See page Manage addon dependencies.