This chapter requires a minimum understanding of MicroEJ Module Manager and Module Natures.
Create a new Project¶
First create a new module project using the
A new project is generated into the workspace:
Configure a Platform¶
Before building the firmware, a target platform must be configured. The
easiest way to do it is to copy a platform file into the
myfirmware > dropins folder. Such file usually ends with
For other ways to setup the input platform to build a firmware see
Build the Firmware and Virtual Device¶
In the Package Explorer, right-click on the project and select Build Module. The build of the Firmware and Virtual Device may take several minutes. Once the build has succeeded, the folder myfirmware > target~ > artifacts contains the firmware output artifacts (see Firmware Input and Output Artifacts) :
mymodule.out: The Firmware Binary to be programmed on device.
mymodule.kpk: The Firmware Package to be imported in a MicroEJ Forge instance.
mymodule.vde: The Virtual Device to be imported in the SDK.
mymodule-workingEnv.zip: This file contains all files produced by the build phase (intermediate, debug and report files).
A Kernel must define the set of classes, methods and static fields all applications are allowed to use.
According to the Kernel and Features specification, no API is open by default to Sandboxed Applications.
This can be done either by declaring Kernel APIs or by definining a Runtime Environment.
The main difference is from the Application development point of view. In the first case, the Application project still declares standard module dependencies. This is the good starting point for quickly building a Kernel with Applications based on the MicroEJ modules as-is. In the second case, the Application project declares the runtime environment dependency. This is the preferred way in case you intend to build and maintain a dedicated Applications ecosystem.
A Kernel API or a Runtime Environment module is added as a dependency with the configuration
<dependency org="com.microej.kernelapi" name="edc" rev="1.0.6" conf="kernelapi->default"/>
Add System Applications¶
A MicroEJ Sandboxed Application can be dynamically installed using Kernel.install() or can be directly linked into the Firmware binary at built-time. In this case, it is called a System Application.
The user can specify the System Applications in two different ways:
Set the property
build-systemapps.dropins.dirto a folder which contains System Applications (
Add a new dependency for each System Application with the configuration
<dependency org="com.microej.app.wadapps" name="management" rev="2.2.2" conf="systemapp->application"/>
All System Applications are also included to the Virtual Device.
If a System Application must only be linked to the Firmware,
declare the dependency with the configuration
systemapp-fw instead of
<dependency org="com.microej.app.wadapps" name="management" rev="2.2.2" conf="systemapp-fw->application"/>
Build Firmware using Meta Build¶
A Meta build project can be useful to automatically build Sandboxed Applications that will be linked as System Application in the Firmware.
The following figure shows the overall build flow (Sandboxed Application build prior to the Firmware build):
Build Firmware using MicroEJ Launches¶
It is still possible to build the Firmware using MicroEJ Launch rather than the regular module build. This speeds-up the build time thanks to MicroEJ Module Manager workspace resolution and Eclipse incremental compilation.
- Import the Firmware project and all System Application projects in the same workspace,
- Prepare a MicroEJ Application for the Kernel as a regular Standalone Application,
- Prepare a MicroEJ Application launch for each System Application using Build Dynamic Feature settings,
- Prepare a MicroEJ Tool launch for each System Application using the Firmware Linker settings.
The following figure shows the overall build flow:
The following section describes module description file (
module.ivy) generated by the
<info organisation="org" module="module" status="integration" revision="1.0.0"> <ea:build organisation="com.is2t.easyant.buildtypes" module="build-firmware-multiapp" revision="2.+"/> <ea:property name="application.main.class" value="org.Main" /> </info>
application.main.class is set to the fully qualified
name of the main java class. The firmware generated from the skeleton
defines its own runtime environment by using ivy dependencies
kernel API instead of relying on a runtime environment
build-firmware-multiapp build type requires the following
configurations, used to specify the different kind of firmware inputs
(see Firmware Input and Output Artifacts) as Ivy dependencies.
<configurations defaultconfmapping="default->default;provided->provided"> <conf name="default" visibility="public"/> <conf name="provided" visibility="public"/> <conf name="platform" visibility="public"/> <conf name="vdruntime" visibility="public"/> <conf name="kernelapi" visibility="private"/> <conf name="systemapp" visibility="private"/> <conf name="systemapp-fw" visibility="private"/> </configurations>
The following table lists the different configuration mapping usage where a dependency line is declared:
<dependency org="..." name="..." rev="..." conf="[Configuration Mapping]"/>
|Configuration Mapping||Dependency Kind||Usage|
||Foundation Library (
||Expected to be provided by the platform. (e.g.
||Add-On Library (
||Embedded in the firmware only, not in the Virtual Device|
||Add-On Library (
||Embedded in the Virtual Device only, not in the firmware|
||Add-On Library (
||Embedded in both the firmware and the Virtual Device|
||Platform dependency used to build the firmware and the Virtual Device. There are other ways to select the platform (see Platform Selection)|
||Runtime Environment (
||See Runtime Environment|
||Linked into both the firmware and the Virtual Device as System Application. There are other ways to select System Applications (see Add System Applications)|
||Linked into the firmware only as System Application.|
Example of minimal firmware dependencies.
The following example firmware contains one System App (
and defines an API that contains all types, methods, and fields from
<dependencies> <dependency org="ej.api" name="edc" rev="1.2.0" conf="provided" /> <dependency org="ej.api" name="kf" rev="1.4.0" conf="provided" /> <dependency org="ej.library.wadapps" name="framework" rev="1.11.0" /> <dependency org="com.microej.library.wadapps.kernel" name="common-impl" rev="3.0.0" /> <dependency org="com.microej.library.wadapps" name="admin-kf-default" rev="1.2.0" /> <!-- Runtime API (set of Kernel API files) --> <dependency org="com.microej.kernelapi" name="edc" rev="1.0.0" conf="kernelapi->default"/> <dependency org="com.microej.kernelapi" name="kf" rev="2.0.0" conf="kernelapi->default"/> <dependency org="com.microej.kernelapi" name="wadapps" rev="1.0.0" conf="kernelapi->default"/> <dependency org="com.microej.kernelapi" name="components" rev="1.0.0" conf="kernelapi->default"/> <!-- System Applications --> <dependency org="com.microej.app.wadapps" name="management" rev="2.2.2" conf="systemapp->application"/> </dependencies>
Build only a Firmware¶
Set the property
<ea:property name="skip.build.virtual.device" value="SET" />
Build only a Virtual Device¶
Set the property
<ea:property name="virtual.device.sim.only" value="SET" />
Build only a Virtual Device with a pre-existing Firmware¶
.kpk file into the folder