ESF Addon Archetype

The ESF Addon Archetype is a Maven Archetype that allows to create 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-7.2.2.jar) must be downloaded from Eurotech Website and installed in the local maven repository with the following command:

mvn install:install-file -Dfile=./esf-addon-archetype-7.2.2.jar -DgroupId=com.eurotech.framework -DartifactId=esf-addon-archetype -Dversion="7.2.2" -Dpackaging=jar

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="7.2.2"

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

At the end of the procedure, 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 can be configured during the archetype generation process.

• emulator : contains an Eclipse run configuration to start ESF in the Eclipse IDE. The OSGi and ESF persistence such as the OSGi storage area, the ESF deployment packages installed by the user and the ESF configuration snapshots are stored in the target directory of the emulator so that the emulator can be restarted with the latest packages and configuration until the target directory is deleted.

• 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 an 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 Eclipse IDE. Maven dependencies should not be added to the build, not even test dependencies as this will lead to not reproducible builds.

• tests: contains OSGi integration tests executed by the tycho-surefire-plugin.

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, ESF 7.2.2 archetype expects that this URL points to ESF 7.2.2 P2 repository. The repository URL and content can be also changed later on using Eclipse.
  The URL for ESF 7.2.2 p2 repository is:

https://s3.amazonaws.com/esf-p2/ESF_7.2.2_latest/repository

Building

Linux users will have to set the name of their primary network interface in emulator/src/main/resources/framework/kura.properties. Search primary.network.interface, uncomment the line and assign the the property the name of a Ethernet or Wi-Fi network interface, as reported by the command ip link.

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

mvn clean install -Dtycho.localArtifacts=ignore

Note that will wipe the persistence of the emulator, deleting the deployment packages and configurations installed by the user.

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

Importing Projects in Eclipse IDE

To use the emulator, the Eclipse workspace must be created in the root of the project generated by the archetype. 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.

Running the Emulator

🚧

Build Once Before Running Emulator

The build must be run at least once before attempting to run the emulator. See Building above for more details on how to run the build.

The emulator will not run properly if this is skipped.

Right click on the ESF_Emulator.launch file in the emulator project and select Run as | 1 ESF Emulator

The ESF emulator admin UI is available at localhost:8080.

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.