ChangelogDownloads
HomeGuidesChangelog
ChangelogDownloadsSupportMulti-service IoT Edge GatewaysEUROTECH
Guides
SupportMulti-service IoT Edge GatewaysEUROTECH

ESF Addon Archetype

Suggest Edits

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-<esf-version>.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-<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.

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 archetype expects that this URL points to ESF P2 repository. The repository URL and content can be also changed later on using Eclipse.
    The URL for ESF p2 repository is:
https://s3.amazonaws.com/esf-p2/ESF_<esf-version>_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

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.

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.

Updated 3 months ago